Tools

Tools are structured functions that an LLM can call. The SDK provides defineTool for schema-first definitions and createToolkit for bundling tools together.

Key types & signatures

interface ToolConfig<TParams extends z.ZodType, TResult> {
  name: string;
  description: string;
  parameters: TParams;
  execute: (params: z.infer<TParams>) => Promise<TResult> | TResult;
}

function defineTool<TParams extends z.ZodType, TResult>(
  config: ToolConfig<TParams, TResult>
): Tool<TParams, TResult>;

function createToolkit(tools: Tool[]): Toolkit;

Define a custom tool

import { defineTool } from '@dreadnode/agents';
import { z } from 'zod';

const calculator = defineTool({
  name: 'calculator',
  description: 'Perform basic math operations.',
  parameters: z.object({
    operation: z.enum(['add', 'subtract', 'multiply', 'divide']),
    a: z.number(),
    b: z.number(),
  }),
  execute: ({ operation, a, b }) => {
    switch (operation) {
      case 'add':
        return a + b;
      case 'subtract':
        return a - b;
      case 'multiply':
        return a * b;
      case 'divide':
        return a / b;
    }
  },
});

Build a toolkit and use it with an agent

import { anthropic } from '@ai-sdk/anthropic';
import { createAgent, createGenerator, createToolkit, tool } from '@dreadnode/agents';
import { z } from 'zod';
import { defineTool } from '@dreadnode/agents';

const lookup = defineTool({
  name: 'lookup',
  description: 'Fetch an answer from a local map.',
  parameters: z.object({ question: z.string() }),
  execute: ({ question }) => ({ answer: `Local answer for: ${question}` }),
});

const toolkit = createToolkit([lookup]);

const tools = Object.fromEntries(
  toolkit.list().map((name) => {
    const toolDef = toolkit.get(name)!;
    return [
      name,
      tool({
        description: toolDef.description,
        parameters: toolDef.parameters,
        execute: toolDef.execute,
      }),
    ];
  })
);

const generator = createGenerator(anthropic('claude-sonnet-4-20250514'));

const agent = createAgent({
  name: 'tools-agent',
  generator,
  generateOptions: { tools },
});

const result = await agent.run({ input: 'Use the lookup tool to answer: What is Dreadnode?' });
console.log(result.trajectory.lastMessage?.text ?? 'No output');