Tools

Tools are functions that can be called by the AI model during conversations. They allow your agent to perform actions, retrieve information, or interact with external systems based on user requests.

Creating a tool

Create a tool in src/tools/:

import { Autonomous, z } from "@botpress/runtime";

export default new Autonomous.Tool({
  name: "myTool",
  description: "A tool that does something useful",
  input: z.object({}), // Input schema
  output: z.object({}), // Output schema
  handler: async ({}) => {
    // Tool logic
    return {};
  },
});

Tool input and output

Define input and output schemas using Zod schemas. The AI model uses these schemas to understand when and how to call your tool:

import { Autonomous, z } from "@botpress/runtime";

export default new Autonomous.Tool({
  name: "getWeather",
  description: "Get the current weather for a location",
  input: z.object({
    location: z.string().describe("The city or location name"),
    unit: z.enum(["celsius", "fahrenheit"]).optional().describe("Temperature unit"),
  }),
  output: z.object({
    temperature: z.number(),
    condition: z.string(),
  }),
  handler: async ({ location, unit }) => {
    // Fetch weather data
    const weather = await fetchWeatherData(location, unit);
    return {
      temperature: weather.temp,
      condition: weather.condition,
    };
  },
});

Using tools in conversations

Provide an array of tools to your agent in a conversation handler:

import { Conversation } from "@botpress/runtime";
import getWeather from "../tools/weather";

export default new Conversation({
  channel: "*",
  handler: async ({ execute }) => {
    await execute({
      instructions: "You are a helpful weather assistant.",
      tools: [getWeather],
    });
  },
});

Converting actions to tools

You can convert actions to tools using the asTool() method:

import { Conversation, actions } from "@botpress/runtime";

export default new Conversation({
  channel: "*",
  handler: async ({ execute }) => {
    await execute({
      instructions: "You are a helpful assistant.",
      tools: [actions.calculateTotal.asTool()],
    });
  },
});

Converting workflows to tools

You can convert workflows to tools using the asTool() method:

import { Conversation } from "@botpress/runtime";
import myWorkflow from "../workflows/index"

export default new Conversation({
  channel: "*",
  handler: async ({ execute }) => {
    await execute({
      instructions: "You are a helpful assistant.",
      tools: [myWorkflow.asTool()],
    });
  },
});

Tool handler

The handler function receives the input parameters and executes the tool’s logic. It can also call custom actions.

Basic handler

import { Autonomous, z } from "@botpress/runtime";

export default new Autonomous.Tool({
  name: "searchDatabase",
  description: "Search the database",
  input: z.object({
    query: z.string(),
  }),
  handler: async ({ query }) => {
    // Perform search
    return { results: [] };
  },
});

import { Autonomous, actions, z } from "@botpress/runtime";

export default new Autonomous.Tool({
  name: "processOrder",
  description: "Process a customer order",
  input: z.object({
    orderId: z.string(),
  }),
  handler: async ({ orderId }) => {
    const result = await actions.validateOrder({ orderId });
    return result;
  },
});

Multiple tools

You can provide multiple tools to your agent:

import { Conversation } from "@botpress/runtime";
import { getWeather, searchDatabase, processOrder } from "../tools/index";

export default new Conversation({
  channel: "*",
  handler: async ({ execute }) => {
    await execute({
      instructions: "You are a helpful assistant with access to various tools.",
      tools: [
        getWeather,
        searchDatabase,
        processOrder,
      ],
    });
  },
});

Tool descriptions

The description field is crucial—it helps the AI model understand when to use your tool. Write clear, concise descriptions:

export default new Autonomous.Tool({
  name: "calculateTotal",
  description: "Calculate the total price of items including tax and shipping. Use this when the user asks about prices, costs, or totals.",
  input: z.object({
    items: z.array(z.object({
      price: z.number(),
      quantity: z.number(),
    })),
  }),
  // ...
});

Signals

Tools can throw special signals to influence the AI’s behavior:

ThinkSignal

Throw a ThinkSignal to provide additional context to the AI without returning a result:

import { Autonomous } from "@botpress/runtime";

export default new Autonomous.Tool({
  name: "searchDatabase",
  handler: async ({ query }) => {
    const results = await search(query);

    if (results.length === 0) {
      throw new Autonomous.ThinkSignal(
        "No results found",
        "No results were found. Try a different search query."
      );
    }

    return results;
  },
});

Best practices

• Write clear, descriptive tool names and descriptions
• Use Zod schemas with .describe() to provide context for each input parameter
• Keep tool handlers focused on a single responsibility
• Use tools for operations that require external data or actions
• Test tools independently before using them in conversations

Tools are ideal for operations that the AI model needs to perform dynamically based on user requests. They enable your agent to go beyond just generating text and actually interact with systems, retrieve data, and perform actions.

Reference

Tool props

Show Tool props

name · string · required

Unique tool name. Must be a valid TypeScript identifier.

description · string

Human-readable description for the LLM. Helps the AI understand when and how to use the tool.

input · z.ZodTypeAny

Optional Zui/Zod schema for input validation. Defines the parameters the tool accepts.

output · z.ZodTypeAny

Optional Zui/Zod schema for output validation. Defines the return type of the tool.

handler · (args: any, ctx: object) => Promise<any> · required

Async function that implements the tool logic. See handler parameters below for details.

aliases · string[]

Optional array of alternative names for the tool.

metadata · Record<string, unknown>

Optional metadata object for storing additional tool information.

staticInputValues · object

Optional partial input values that will be automatically applied to all tool calls, removing them from LLM control.

retry · (args: { input: any; attempt: number; error?: unknown }) => boolean | Promise<boolean>

Optional custom retry logic function. Receives an object with input, attempt number, and optional error, returns Boolean indicating whether to retry.

Handler parameters

The handler function receives validated input and execution context:

Show Handler parameters

args · any · required

The validated input arguments matching the tool’s input schema. All properties are typed based on the schema definition.

ctx · object · required

Tool call context containing metadata about the tool call.

Show child attributes

callId · string · required

Unique identifier for this specific tool call.