Tools

A tool is a function an 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; 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 creating the session. This function runs in your app and can use its database connections and dependencies. Keep the app connected while the agent needs the tool.

Use ctx.finish(value) to return a result and finish the tool. Background tools can send multiple results before finishing. Saved tool results appear in session history; the agent loop decides how to present them to the model.

Choose the session's tools before creation. The model can call those tools; it cannot add new ones or grant them access to another environment. Brain does not automatically retry failed calls, and cancellation does not undo effects that already happened.

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