defineTool

The defineTool function allows you to create a reusable tool that can be used by agents.

API Reference

defineTool(options)

Defines a tool with the following options:

• name (string, required): The name of the tool (should be camelCase or snake_case)
• description (string | string[], required): The tool description for the LLM (should be descriptive and concise)
• input (object or zchema, optional): A type definition of the input parameters
• output (zchema, optional): A type definition of the output (defaults to void)
• state (object or zchema, optional): A type definition of the tool state
• event (zchema, optional): A type definition of the tool event
• handler (async function, required): The function that implements the tool logic
  • Receives ToolContext as an argument with:
    • input: The typed input parameters
    • state: The tool state object
    • events: Array of tool events
    • trace: String for execution tracing
    • agent: The agent object
    • result: Helper for returning results
  • Returns:
    • A value of the defined output type (or a Promise of it)
    • TOOL_AWAIT_RESULT if the tool is waiting for events

Example

import { defineTool } from 'agentscript-ai/core';
import * as s from 'agentscript-ai/schema';
 
const add = defineTool({
    name: 'add',
    description: 'Add two numbers.',
    input: {
      a: s.number({description: "First number"}),
      b: s.number({description: "Second number"}),
    },
    output: s.number({description: 'The result of addition.'}),
    handler: ({ input }) => input.a + input.b,
});

The defined tool can be used in agent definitions and will be available to the agent during execution.