Tools
Give the model an HTTP tool, one request the Runtime makes to your service.
An HTTP tool is one request to your service, made by the Runtime itself. No code of yours runs during the session.
import { Agent, createClient, http } from "@nylorun/agents";
import { z } from "zod";
const refundOrder = http({
name: "refund_order",
description: "Refund an order.",
input: z.object({ orderId: z.string(), amount: z.number() }),
output: z.object({ refundId: z.string() }),
url: "https://billing.example.com/refunds",
credential: "billing",
});
export const support = Agent({ id: "support" })
.instructions("Refund orders when the customer asks.")
.tools(refundOrder)
.build();
const client = await createClient();
await client.agentManifests.save({
agent: support,
runtime: {
kind: "none",
secrets: {
billing: { type: "bearer", url: "https://billing.example.com/refunds", required: true },
},
},
});In an agent manifest, the same tool is the
file tools/refund_order.json, with inputSchema, outputSchema, and an
http block holding url and credential. The tool is named after its file,
and the tool policy names it by that name. A folder refuses approval in a
tool file (approval_removed); see Approval.
.tools() takes one or more tools and accumulates across calls. The tool goes
into the agent manifest's harness section with its http target. The Runtime
sends each call through its Tool Gate, after the Tenant's
tool policy allows it. credential: "billing" names a
secret slot of the runtime section, so the save declares one; without it the
save is refused with 422 manifest_inconsistent. See
Credentials.
A tool's name may not contain __, and no two tools share a name. No name is
reserved, but a turn fails when one of the agent's tools takes the name of a
tool our harness adds in that session, such as bash on an Agent with a
sandbox. See Names.
Prop
Type
The request
| Part | Value |
|---|---|
| Method | POST by default, or the tool's method: PUT, PATCH, GET or DELETE. |
| URL | The tool's url, with each {field} its path names filled from the input. |
| Body | For POST, PUT and PATCH: the input's other fields as JSON, with content-type: application/json. GET and DELETE send no body. |
| Query string | For GET and DELETE: the input's other fields, after any query string the URL has. |
Nylorun-Session-Id, Nylorun-Turn-Id, Nylorun-Agent-Id | The session, turn, and agent the call belongs to. The agent is the agent manifest's name, or a subagent's id; never the Agent's id. |
Idempotency-Key | The call's key. The Runtime delivers each call at least once: when a crash or a restart interrupts a call, it sends it again with the same key, up to the Tenant's Runtime limit toolAttempts (3 sends by default). Act once per key. |
traceparent | The call's W3C trace context, so your service's spans join the turn's trace. See Traces. |
A URL's path may name input fields as {field}:
export const getOrder = http({
name: "get_order",
description: "Read one order.",
method: "GET",
url: "https://orders.example.com/orders/{orderId}",
input: z.object({ orderId: z.string(), expand: z.array(z.string()).optional() }),
output: z.object({ id: z.string(), status: z.string() }),
});A call with { orderId: "A 1", expand: ["items", "refunds"] } requests
https://orders.example.com/orders/A%201?expand=items&expand=refunds.
- Each
{field}is a required string, number or boolean of the input, named once, and only in the path. Its value is percent-encoded as one path segment and not sent again. An empty value,.or..fails the call before it is sent. - In a query string an array repeats its name and a
nullis left out. AGETorDELETEtool whose input has an object field, or a field the URL's query string already fixes, throws when it is built (tool.invalid). - A credential with
viasends calls to its one URL, so it cannot serve a tool whose URL names a{field}(http.credential).
Keep anything your service needs across calls in your service, keyed by
Nylorun-Session-Id. A valid input schema is not authorization: check the
request in your service.
The answer
| Answer | Result |
|---|---|
2xx with JSON | The tool output, checked against output (tool.invalid-output when it does not match). |
2xx with text, and no output | The text. |
2xx that is not JSON when output is set, or JSON that does not parse | http.invalid-response |
401 | credential_rejected. The body is not shown, and the call is not retried. |
| Any other status | http.status, with the start of the body. |
| No answer within the timeout | http.timeout |
| A refused address | http.refused |
| Not sent: DNS, a refused connection, TLS | http.unreachable |
| Sent, and the connection lost | http.lost |
An answer over the Tenant's Runtime limit toolAnswerBytes (8 MiB by default) | http.too-large |
| No credential for the tool's URL in the Agent's secrets | http.credential, not sent |
| Refused by the tool policy, or denied by a person | tool.denied, not sent |
Interrupted toolAttempts times by a crash or a restart | tool.interrupted: the call may have run |
Each error is a failed tool result the model sees, with its code, and the turn goes on. See Pauses and control.
Each call ends in one tool.completed event, and a row in
session.toolCalls(), with kind: "http", tool set to the tool's declared
name, and server set to the host of the tool's URL. See
Events.
Our harness stores an output over 32 KiB as a file artifact of the session; the
model gets a preview and reads the rest with read_artifact. See
Large results.
Credentials
credential names a secret slot of the runtime section the agent is saved
with: a slot of type bearer or headers, bound to the tool's exact URL. The
save checks it, and refuses a missing slot, a slot of another type, or a slot
bound to another URL with 422 manifest_inconsistent, naming the gap:
harness.tools.refund_order.http.credential "billing" is not a secret slot in runtime.secretsWrite the slot's value into each Agent made from the manifest:
await client.agents.put("teams/support", { manifest: "support" });
await client.agents.secrets.put("teams/support", "billing", { value: process.env.BILLING_TOKEN! });The Runtime adds the Agent's secret for the tool's URL to each request, as for
a remote MCP server. Without one the call fails with http.credential before
it is sent. A credential with via sends the call to that URL instead. See
Secret slots and
Secrets and credentials.
Approval
Which calls wait for a person is not part of the tool. The Tenant's
tool policy holds or refuses calls by the tool's
declared name, agent, and input, for every agent at once. http({ approval })
throws, and saving an agent manifest that sets approval is refused. In an
agent manifest, nylorun check refuses it at its line:
refund/tools/refund_order.json:9:3 error: approval is not set in an agent folder: tool approvals are the Tenant's tool policy, decided at the Tool Gate for every agent. To have a person approve a call, add a rule with "effect": "ask" for the tool to the Tenant's tool policy (nylorun tenant tool-policy put <file>, or PUT /v1/tenant/tool-policy)Reachability
The gateway must reach the tool's URL. Redirects are not followed.
- Local Tenant.
localhostmeans your machine, and private addresses are allowed. - Server. Set
NYLORUN_ENDPOINT_PRIVATE=refuseandNYLORUN_ENDPOINT_HTTP=refuseunless your services live on a private network. See Docker Compose.
Other tools
| Tool | Where it runs | kind | Page |
|---|---|---|---|
| Remote MCP server tools | Your MCP server, reached through the gateway | mcp | MCP |
| An agent used as a tool | Our harness, with a fresh context | — | Subagents |
load_skill, read_skill_resource | Our harness, when the agent has skills | harness | Skills |
read_artifact, save_artifact | Our harness; save_artifact with a sandbox | harness | Files |
tool_search, tool_call | Our harness, when MCP tools are deferred | harness | MCP |
bash, read, write, edit, grep, glob | The sandbox of the Agent the session runs on; our harness runs a read of an image or PDF the model reads, to show it the file | sandbox | Agents, Files the agent makes |
schedule_wake | The Runtime, which books the session's next turn; with runtime.selfWake | runtime | Triggers and wakes |
memory | The Runtime, which reads and writes the Agent's memories; with harness.memory | runtime | Agent memory |
Our harness adds these tools to the model's list after the agent's own. A custom harness offers its own; see Bring your own harness.
tool({ run }) runs your code, so it runs only in the local engine
(@nylorun/harness/run). client.agentManifests.save refuses an agent that
has one, before sending anything. Make it an http() tool or serve it from a
remote MCP server. An HTTP tool runs only on the Runtime; a local run()
reports http.runtime-only.
An HTTP tool is also a stage of a flow agent:
.pipe(order, refund). Its input is the previous stage's output.