Distributed tools

Tools let the agent act outside the conversation: run code in a sandbox, read and write storage, search the web, or ask a person for approval. In Brain, every tool runs outside the server, in a service you deploy and write in any language. You declare each tool in the host config, enable tools for a session by name, and Brain calls the tool over HTTP when the model asks for it.

The model sees exactly the tools you enable for its session, so you decide everything the agent can do.

Ways to provide toolsCopy Anchor Link

The local tools, sandbox, and storage services ship with this repository. Run each one as its own service alongside Brain, with its provider keys in its own configuration.

Configure a toolCopy Anchor Link

Add a binding to the tools array of the host config. This binding declares the echo tool from the example tool server in examples/tools, with the default timeout and output limit written out:

{
  "name": "echo",
  "description": "Echo text through an external tool service.",
  "input_schema": {
    "type": "object",
    "properties": { "text": { "type": "string", "maxLength": 4096 } },
    "required": ["text"],
    "additionalProperties": false
  },
  "url": "http://127.0.0.1:8081/tools/echo",
  "token_env": "BRAIN_TOOLS_KEY",
  "tenants": ["local"],
  "timeout_seconds": 300,
  "max_output_bytes": 1048576
}

Brain checks every binding when it starts and doesn't start if one is invalid. Run go run ./cmd/brain -config brain.json -check to validate a config without starting the server.

Enable tools for a sessionCopy Anchor Link

GET /catalog lists the tools available to your tenant, with their names, descriptions, and schemas. It never returns a tool's url or token_env. To give a session tools, pass their names in config.tools when you create it.

curl http://127.0.0.1:8080/catalog \
  -H "Authorization: Bearer $BRAIN_API_KEY"

To try tools without writing a service, follow Local tools & approvals. It generates a host config for the example tool server and runs examples/session.mjs with BRAIN_TOOLS set to the tools to enable.

Handle a tool callCopy Anchor Link

When the model calls a tool, Brain assigns a call ID, records a tool.call event, validates the arguments, and sends a POST request to the tool's url with these headers:

• Content-Type: application/json
• Accept: application/json, text/event-stream
• Authorization: Bearer TOKEN, when the binding sets token_env
• traceparent, when the request belongs to a trace

The body carries the session's identity next to the model's arguments:

{
  "tenant_id": "local",
  "session_id": "SESSION_ID",
  "call_id": "CALL_ID",
  "arguments": { "text": "hello" }
}

tenant_id and session_id come from the authenticated session, not from the model. With inspect_session: true, the body also has an inspection_token and a brain_url.

Here is a minimal tool service in Node.js:

import http from "node:http";

const token = process.env.BRAIN_TOOLS_KEY;

http.createServer(async (req, res) => {
  if (req.headers.authorization !== `Bearer ${token}`) {
    res.writeHead(401).end();
    return;
  }
  let body = "";
  for await (const chunk of req) body += chunk;
  const { tenant_id, session_id, call_id, arguments: args } = JSON.parse(body);
  // Authorize with tenant_id and session_id. Log call_id to match Brain's tool.call event.
  res.writeHead(200, { "Content-Type": "application/json" });
  res.end(JSON.stringify({ content: [{ type: "text", text: args.text }] }));
}).listen(8081, "127.0.0.1");

Return a JSON resultCopy Anchor Link

Respond with status 200, Content-Type: application/json, and a result object:

{ "content": [{ "type": "text", "text": "hello" }] }

Brain rejects a result with neither content nor structured content, an unknown content type, or unknown fields. Error results bypass the success schema while retaining content and size checks.

Stream progress with SSECopy Anchor Link

Respond with Content-Type: text/event-stream to send progress while the tool works. Send zero or more progress events, then exactly one result event whose data is a result object:

event: progress
data: {"status":"waiting_for_operator"}

event: result
data: {"content":[{"type":"text","text":"Operator answered yes."}]}

Each progress payload must be JSON. Brain forwards it to connected clients as a live-only tool.progress event with the call's call_id. Brain ignores comment lines that start with :. Any other event name, or a stream that ends without a result, fails the call.

Handle errors, timeouts, and long jobsCopy Anchor Link

Every tool call ends with a tool.result event. When a call fails, the result has is_error: true, and Brain adds unknown_outcome: true when the tool may have done the work anyway:

Brain sends each tool call at most once; your tool service owns retries and cleanup. The model sees the error, and with an unknown outcome it can check what happened, for example by calling a status tool.

Brain enforces two time limits on every call:

• Response headers within 30 seconds. For longer work, send the response headers right away: start an SSE response and send progress events until the result is ready.
• The whole call within timeout_seconds. For work that can run longer, return a job ID right away and provide separate tools to check status and cancel the job.

Interrupting or closing a session cancels its in-flight tool requests. Work that already started in your service keeps running unless your service stops it, so your service owns cleanup.

Secure your tool serviceCopy Anchor Link

• Check the token: Set token_env on every binding and reject requests without the matching bearer token.
• Authorize with the session's identity: Use the top-level tenant_id and session_id to decide what the call may access. Never trust IDs that the model put in arguments.
• Protect inspection tokens: An inspection_token can read the session's events until the call returns. Don't log or store it.
• Enforce approvals where the action happens: An approval tool records a person's answer; the service that performs the action must still check its own authorization.
• Expect no redirects: Brain doesn't follow redirects from tools. It sends tool requests through the proxy in the standard HTTPS_PROXY and HTTP_PROXY variables when they're set.

Next stepsCopy Anchor Link