Add your first tool

Your agent can talk, but it cannot do anything yet. In this guide you will add a small tool, declare it in the manifest, and watch the agent call it to answer a question. This continues from Build your first agent, so start from that my-agent project.

Prerequisites

The tool you will write is a TypeScript package, so you need Node.js and pnpm installed. The compiler uses them to bundle the tool at build time.

Scaffold the tool

From the project root, scaffold a JavaScript tool package named math:

agentc tool init math --language javascript

You should see:

 ✓ Created math

This creates a ready-to-use math/ package with its entry point, package configuration, and runtime type declarations already configured. agentc.d.ts is one line, and it is what tells your editor the shape of everything the host provides to tool code. Install the dependencies:

cd math
pnpm install
cd ..

The scaffold uses pnpm by default. See Write a tool if you would rather use npm.

Write the tool

A tool is an exported class that extends Tool. It has static metadata for the model and an asynchronous execute method. Replace the contents of math/src/index.ts with a single tool that adds two numbers:

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 };
  }
}

The description and the parameter descriptions matter: they are what the model reads to decide when and how to call the tool.

Declare the tool in the manifest

The tool package exists, but the agent does not know about it until you declare it. Add a tool block to agent.acl, pointing source at the package directory:

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

Because this tool declares no capabilities, it is available to the agent without any further configuration. Controlling access with capabilities comes later, in Control tool access with capabilities.

Rebuild and run

Rebuild so the tool is bundled into the binary:

agentc build

Then ask the agent something that needs the tool:

./artifacts/build/my-agent run "What is 21 plus 21?"

The agent calls adder with a: 21 and b: 21, reads the result, and answers 42. You have given your agent its first capability.

What you will do next

So far you have run the agent from the command line. In Serve and connect you will start the HTTP server and send your agent a request over the network.