Chatbot Tool Usage

With useChat and streamText, you can use tools in your chatbot application.
The AI SDK supports three types of tools in this context:

1. Automatically executed server‑side tools
2. Automatically executed client‑side tools
3. Tools that require user interaction, such as confirmation dialogs

The flow is as follows:

1. The user enters a message in the chat UI.
2. The message is sent to the API route.
3. In your server‑side route, the language model generates tool calls during the streamText call.
4. All tool calls are forwarded to the client.
5. Server‑side tools are executed using their execute method and their results are forwarded to the client.
6. Client‑side tools that should be automatically executed are handled with the onToolCall callback.
   You must call addToolOutput to provide the tool result.
7. Client‑side tools that require user interactions can be displayed in the UI.
   The tool calls and results are available as tool invocation parts in the parts property of the last assistant message.
8. When the user interaction is done, addToolOutput can be used to add the tool result to the chat.
   The chat can be configured to automatically submit when all tool results are available using sendAutomaticallyWhen.
   This triggers another iteration of this flow.

The tool calls and tool executions are integrated into the assistant message as typed tool parts.
A tool part is at first a tool call, and then it becomes a tool result when the tool is executed.
The tool result contains all information about the tool call as well as the result of the tool execution.

Note
Tool result submission can be configured using the sendAutomaticallyWhen option.
You can use the lastAssistantMessageIsCompleteWithToolCalls helper to automatically submit when all tool results are available.
This simplifies the client‑side code while still allowing full control when needed.

Example

In this example, we’ll use three tools:

• getWeatherInformation: An automatically executed server‑side tool that returns the weather in a given city.
• askForConfirmation: A user‑interaction client‑side tool that asks the user for confirmation.
• getLocation: An automatically executed client‑side tool that returns a random city.

API route

// app/api/chat/route.ts
import { openai } from '@ai-sdk/openai';
import {
  convertToModelMessages,
  streamText,
  UIMessage,
} from 'ai';
import { z } from 'zod';

// Allow streaming responses up to 30 seconds
export const maxDuration = 30;

export async function POST(req: Request) {
  const { messages }: { messages: UIMessage[] } = await req.json();

  const result = streamText({
    model: openai('gpt-4o'),
    messages: convertToModelMessages(messages),
    tools: {
      // server-side tool with execute function:
      getWeatherInformation: {
        description: 'show the weather in a given city to the user',
        inputSchema: z.object({
          city: z.string(),
        }),
        execute: async ({ city }: { city: string }) => {
          const weatherOptions = [
            'sunny',
            'cloudy',
            'rainy',
            'snowy',
            'windy',
          ];
          return weatherOptions[
            Math.floor(Math.random() * weatherOptions.length)
          ];
        },
      },

      // client-side tool that starts user interaction:
      askForConfirmation: {
        description: 'Ask the user for confirmation.',
        inputSchema: z.object({
          message: z
            .string()
            .describe('The message to ask for confirmation.'),
        }),
      },

      // client-side tool that is automatically executed on the client:
      getLocation: {
        description:
          'Get the user location. Always ask for confirmation before using this tool.',
      },
    },
  });

  // TODO: return the streaming result to the client
}

(The code above demonstrates how to define server‑side and client‑side tools, including a schema for input validation with zod. The streamText function handles tool calls automatically and forwards them to the client.)