NylorunDocsBeta
BuildDefine

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

PartValue
MethodPOST by default, or the tool's method: PUT, PATCH, GET or DELETE.
URLThe tool's url, with each {field} its path names filled from the input.
BodyFor POST, PUT and PATCH: the input's other fields as JSON, with content-type: application/json. GET and DELETE send no body.
Query stringFor GET and DELETE: the input's other fields, after any query string the URL has.
Nylorun-Session-Id, Nylorun-Turn-Id, Nylorun-Agent-IdThe 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-KeyThe 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.
traceparentThe 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 null is left out. A GET or DELETE tool 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 via sends 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

AnswerResult
2xx with JSONThe tool output, checked against output (tool.invalid-output when it does not match).
2xx with text, and no outputThe text.
2xx that is not JSON when output is set, or JSON that does not parsehttp.invalid-response
401credential_rejected. The body is not shown, and the call is not retried.
Any other statushttp.status, with the start of the body.
No answer within the timeouthttp.timeout
A refused addresshttp.refused
Not sent: DNS, a refused connection, TLShttp.unreachable
Sent, and the connection losthttp.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 secretshttp.credential, not sent
Refused by the tool policy, or denied by a persontool.denied, not sent
Interrupted toolAttempts times by a crash or a restarttool.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.secrets

Write 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. localhost means your machine, and private addresses are allowed.
  • Server. Set NYLORUN_ENDPOINT_PRIVATE=refuse and NYLORUN_ENDPOINT_HTTP=refuse unless your services live on a private network. See Docker Compose.

Other tools

ToolWhere it runskindPage
Remote MCP server toolsYour MCP server, reached through the gatewaymcpMCP
An agent used as a toolOur harness, with a fresh context—Subagents
load_skill, read_skill_resourceOur harness, when the agent has skillsharnessSkills
read_artifact, save_artifactOur harness; save_artifact with a sandboxharnessFiles
tool_search, tool_callOur harness, when MCP tools are deferredharnessMCP
bash, read, write, edit, grep, globThe 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 filesandboxAgents, Files the agent makes
schedule_wakeThe Runtime, which books the session's next turn; with runtime.selfWakeruntimeTriggers and wakes
memoryThe Runtime, which reads and writes the Agent's memories; with harness.memoryruntimeAgent 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.

Next step

On this page