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. TypeScript tools use agentc:tools, while Python tools use agentc_tools.

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

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

import { Schema, Tool, type ToolInput, type ToolOutput } from "agentc:tools";

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

export class Adder extends Tool<AddArgs, number> {
  static readonly description = "Adds two numbers together.";

  static readonly parameters = new Schema({
    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 };
  }
}

Use runtime libraries

The runtime provides its libraries to every tool. They are not package dependencies, and each one is imported like any other module. The runtime libraries are catalogued at runtime libraries.

import { fetch } from "agentc:http";

const response = await fetch("https://example.com");

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"
  export = "Adder"
}

Write back to state

A tool can return a state_update alongside its output: an array of RFC 6902 JSON Patch operations. For ReAct, add an operation at /context/- whose value is the operation to apply to context. The nested operation's path is relative to the context object. Context changes persist and appear in state delta events. See the ReAct state reference.

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

Send activity updates

Tools can emit stateless activity updates while they run. emit is optional, so call it with optional invocation.

input.emit?.({
  activity_type: "progress",
  patch: [
    { op: "add", path: "/message", value: "Working" }
  ]
});

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.