Tools

A tool is a function your agent can call: look up an order, search documents, update a record or run a calculation. Its description tells the model when to use it, and its input schema defines the arguments your function accepts.

import { hostEnv, tool } from "@aexhq/brain";
import { z } from "zod";

const lookup = tool({
  name: "lookup",
  description: "Look up an item by id.",
  input: z.object({ id: z.string() }),
  run: ({ id }, ctx) => ctx.finish({ id, name: "Example item" }),
});

const tools = [lookup({ env: hostEnv({ name: "app" }) })];

Pass tools when you create the session. This function runs inside your app, so it can use your database connections and dependencies. Keep the app connected while the agent needs it.

Call ctx.finish(value) to return a result and complete the call. Background tools can send several results before they finish. Tool results are saved in session history, and the agent loop decides how to show them to the model.

Good to know

• The tool list is fixed at creation. The model can call the tools you chose, but it can't add new ones or give them access to another environment.
• No automatic retries. Brain never retries a failed call, and cancelling doesn't undo effects that already happened.

Write a tool has a complete example, language choices and packaging. The tool contract covers errors, background work and multiple placements.