Write a tool

Tools you write in code come in two languages, TypeScript and Python. This guide covers both. Pick the tab for your language in each step. Both kinds are bundled into the binary at compile time, so there is no runtime installation. For the full field reference, see the tool reference.

TypeScript tools run in an embedded JavaScript runtime. Python tools use RustPython by default, which supports pure-Python packages and needs no Python installation at runtime. Select the static interpreter to use CPython 3.14 for packages with C extensions. Both use the agentc tool development kit (TDK), which gives you typed tool definitions.

Scaffold the package

Generate a ready-to-use package with agentc tool init, then install its dependencies.

agentc tool init math --language javascript
cd math
pnpm install

Write the tool

A tool has a name, a description, a JSON Schema for its inputs, and an execute function. The name and descriptions are what the model reads to decide when and how to call it, so write them carefully.

import type { Tool, ToolInput, ToolOutput } from "@agentc-sh/tdk";

type AddArgs = { a: number; b: number };

export const adder: Tool<AddArgs, number> = {
  name: "adder",
  description: "Adds two numbers together.",
  parameters: {
    type: "object",
    properties: {
      a: { type: "number", description: "The first number." },
      b: { type: "number", description: "The second number." }
    },
    required: ["a", "b"]
  },
  async execute(input: ToolInput<AddArgs>): Promise<ToolOutput<number>> {
    return { output: input.args.a + input.args.b };
  }
};

Declare the tool in the manifest

The package exists, but the agent does not see it until you declare a tool block pointing source at the package directory.

tool "adder" {
  kind   = "javascript"
  source = "./math"
}

Write back to state

A tool can return a state_update alongside its output: an array of RFC 6902 JSON Patch operations. For the ReAct graph, target paths under /context/. The patches are persisted and streamed to the client as state delta events, which is how a tool passes data to a frontend.

async execute(input: ToolInput<AddArgs>): Promise<ToolOutput<number>> {
  return {
    output: input.args.a + input.args.b,
    state_update: [
      { op: "add", path: "/context/last_sum", value: input.args.a + input.args.b }
    ]
  };
}

Build

Rebuild so the tool is bundled into the binary:

agentc build

Where to go next

• Control tool access with capabilities: gate which tools the agent may call.
• Tools and capabilities: how tools, state, and activity events work.
• tool reference: every field of the tool block for each kind.