Skip to main content

Tools & Toolkits

VoltAgent allows you to extend the capabilities of your AI agents by providing them with Tools. Tools enable agents to interact with external APIs, perform calculations, access databases, or execute virtually any custom code. This guide covers how to define and use individual tools and the new Toolkit concept for managing related tools.

Defining a Single Tool​

The most basic way to define a tool is using the createTool helper function (or instantiating the Tool class directly).

A tool requires:

  • name: A unique name for the tool (used by the LLM to call it).
  • description: A clear description of what the tool does (used by the LLM to decide when to use it).
  • parameters: A Zod schema defining the input arguments the tool expects.
  • execute: An asynchronous function that contains the tool's logic, taking the validated arguments as input.
import { Agent, createTool, z } from "@voltagent/core";
import { VercelAIProvider } from "@voltagent/vercel-ai";
import { openai } from "@ai-sdk/openai";

// Define a simple weather tool
const getWeatherTool = createTool({
  name: "get_weather",
  description: "Fetches the current weather for a given location.",
  parameters: z.object({
    location: z.string().describe("The city and state, e.g., San Francisco, CA"),
  }),
  execute: async ({ location }) => {
    // In a real scenario, you would call a weather API here
    console.log(`Fetching weather for ${location}...`);
    if (location.toLowerCase().includes("tokyo")) {
      return { temperature: "15°C", condition: "Cloudy" };
    }
    return { temperature: "22°C", condition: "Sunny" };
  },
});

const agent = new Agent({
  name: "WeatherAgent",
  description: "An agent that can fetch weather information.",
  llm: new VercelAIProvider(),
  model: openai("gpt-4o-mini"),
  tools: [getWeatherTool], // Add the tool to the agent
});

// Now the agent can use the 'get_weather' tool when asked about weather.

Grouping Tools with Toolkits​

Often, several tools work together logically. For instance, tools for step-by-step reasoning (think, analyze) or a set of tools interacting with the same API. For these scenarios, VoltAgent provides Toolkits.

A Toolkit allows you to:

  1. Group related tools: Keep your tool management organized.
  2. Define shared instructions: Provide common guidance to the LLM on how to use all tools within the toolkit.
  3. Control instruction injection: Decide if the toolkit's shared instructions should be automatically added to the agent's system prompt.

Defining a Toolkit​

A Toolkit is an object with the following structure:

import { createTool, createToolkit, type Tool, type Toolkit } from "@voltagent/core";

const myCalculatorToolkit = createToolkit({
  name: "calculator_toolkit",
  description: "Tools for performing basic arithmetic operations.",
  // Optional instructions for the LLM
  instructions: `Use these tools for calculations. Always use 'add' for addition, 'subtract' for subtraction.`,
  // Set to true to add the above instructions to the system prompt
  addInstructions: true,
  tools: [
    createTool({
      /* ... definition for 'add' tool ... */
    }),
    createTool({
      /* ... definition for 'subtract' tool ... */
    }),
    // ... other calculator tools
  ],
});

Important: With the introduction of Toolkits, individual Tool instances no longer have their own instructions or addInstructions properties. Instructions are managed at the Toolkit level.

Adding Tools and Toolkits to an Agent​

The tools option in the Agent constructor now accepts an array containing both individual Tool objects and Toolkit objects. The ToolManager handles both seamlessly.

import { Agent, createTool, createToolkit, type Toolkit } from "@voltagent/core";
// ... import other tools and toolkits ...

const agent = new Agent({
    name: "MultiToolAgent",
    description: "An agent with various tools and toolkits.",
    llm: /* ... */,
    model: /* ... */,
    tools: [
        getWeatherTool,      // Add an individual tool
        myCalculatorToolkit, // Add a toolkit
        // ... other tools or toolkits
    ],
});

Automatic Instructions​

When an agent is initialized, its getSystemMessage method checks all the Toolkits provided in the tools array. If a Toolkit has addInstructions: true and defines an instructions string, those instructions will be automatically appended to the agent's base description, forming part of the final system prompt sent to the LLM.

Next Steps​

  • See the Reasoning Tools documentation for a practical example of a pre-built toolkit.
  • Explore creating your own tools to connect agents to your specific data sources and APIs.

Table of Contents