The Vercel AI SDK enhances language models by enabling them to perform specific tasks through tool calling. This feature allows models to interact with external functions, enhancing their capabilities beyond text generation.

Defining a Tool

A tool in the AI SDK comprises three main components:

1. Description: An optional explanation that guides the model on when to utilize the tool.

2. Parameters: Defined using Zod or JSON schemas, these parameters specify the expected inputs for the tool.

3. Execute Function: An optional asynchronous function that performs the task when the tool is invoked.

Here's an example of defining a tool that fetches weather information:

import { z } from 'zod';
import { generateText, tool } from 'ai';

const weatherTool = tool({
  description: 'Fetches weather information for a specified location',
  parameters: z.object({
    location: z.string().describe('The location to get the weather for'),
  }),
  execute: async ({ location }) => {
    // Replace with actual weather fetching logic
    return {
      location,
      temperature: 72 + Math.floor(Math.random() * 21) - 10,
    };
  },
});

Integrating Tools with Text Generation

To incorporate tools into text generation, pass them to the tools parameter in the generateText or streamText functions:

const result = await generateText({
  model: yourModel,
  tools: {
    weather: weatherTool,
  },
  prompt: 'What is the weather in San Francisco?',
});

In this setup, if the model determines that fetching weather data is necessary, it will invoke the weather tool.

Multi-Step Calls with maxSteps

For complex interactions requiring multiple tool invocations, the maxSteps parameter allows the model to perform iterative tool calls until a final response is generated:

const { text, steps } = await generateText({
  model: yourModel,
  tools: {
    weather: weatherTool,
  },
  maxSteps: 5,
  prompt: 'What is the weather in San Francisco?',
});

Setting maxSteps to a value greater than 1 enables the model to iteratively generate tool calls and process their results until a final response is achieved.

Accessing Intermediate Steps

The steps property in the result object provides access to intermediate tool calls and results, facilitating detailed analysis of the model's decision-making process:

const allToolCalls = steps.flatMap(step => step.toolCalls);

Handling Tool Calls in Chat Interfaces

When building chat interfaces, the onToolCall callback can manage client-side tools that should be executed automatically. For instance, a tool that fetches the user's location can be handled as follows:

const { messages, input, handleInputChange, handleSubmit, addToolResult } = useChat({
  maxSteps: 5,
  async onToolCall({ toolCall }) {
    if (toolCall.toolName === 'getLocation') {
      const cities = ['New York', 'Los Angeles', 'Chicago', 'San Francisco'];
      return cities[Math.floor(Math.random() * cities.length)];
    }
  },
});

Error Handling

The AI SDK provides specific errors related to tool calls, such as NoSuchToolError, InvalidToolArgumentsError, and ToolExecutionError. These can be managed using try/catch blocks:

try {
  const result = await generateText({ /* parameters */ });
} catch (error) {
  if (NoSuchToolError.isInstance(error)) {
    // Handle missing tool
  } else if (InvalidToolArgumentsError.isInstance(error)) {
    // Handle invalid arguments
  } else if (ToolExecutionError.isInstance(error)) {
    // Handle execution error
  } else {
    // Handle other errors
  }
}

By leveraging these features, developers can extend the functionality of language models, enabling them to perform a wide range of tasks through tool calling.

For more detailed information and advanced configurations, refer to the official documentation.