--- title: Chatbot Tool Usage description: Learn how to use tools with the useChat hook. --- # Chatbot Tool Usage With [`useChat`](/docs/reference/ai-sdk-ui/use-chat) and [`streamText`](/docs/reference/ai-sdk-core/stream-text), 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. 1. The message is sent to the API route. 1. In your server side route, the language model generates tool calls during the `streamText` call. 1. All tool calls are forwarded to the client. 1. Server-side tools are executed using their `execute` method and their results are forwarded to the client. 1. Client-side tools that should be automatically executed are handled with the `onToolCall` callback. You must call `addToolOutput` to provide the tool result. 1. Client-side tool 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. 1. When the user interaction is done, `addToolOutput` can be used to add the tool result to the chat. 1. 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. 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 ```tsx filename='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: 'anthropic/claude-sonnet-4.5', 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: 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.', inputSchema: z.object({}), }, }, }); return result.toUIMessageStreamResponse(); } ``` ### Client-side page The client-side page uses the `useChat` hook to create a chatbot application with real-time message streaming. Tool calls are displayed in the chat UI as typed tool parts. Please make sure to render the messages using the `parts` property of the message. There are three things worth mentioning: 1. The [`onToolCall`](/docs/reference/ai-sdk-ui/use-chat#on-tool-call) callback is used to handle client-side tools that should be automatically executed. In this example, the `getLocation` tool is a client-side tool that returns a random city. You call `addToolOutput` to provide the result (without `await` to avoid potential deadlocks). Always check `if (toolCall.dynamic)` first in your `onToolCall` handler. Without this check, TypeScript will throw an error like: `Type 'string' is not assignable to type '"toolName1" | "toolName2"'` when you try to use `toolCall.toolName` in `addToolOutput`. 2. The [`sendAutomaticallyWhen`](/docs/reference/ai-sdk-ui/use-chat#send-automatically-when) option with `lastAssistantMessageIsCompleteWithToolCalls` helper automatically submits when all tool results are available. 3. The `parts` array of assistant messages contains tool parts with typed names like `tool-askForConfirmation`. The client-side tool `askForConfirmation` is displayed in the UI. It asks the user for confirmation and displays the result once the user confirms or denies the execution. The result is added to the chat using `addToolOutput` with the `tool` parameter for type safety. ```tsx filename='app/page.tsx' highlight="2,6,10,14-20" 'use client'; import { useChat } from '@ai-sdk/react'; import { DefaultChatTransport, lastAssistantMessageIsCompleteWithToolCalls, } from 'ai'; import { useState } from 'react'; export default function Chat() { const { messages, sendMessage, addToolOutput } = useChat({ transport: new DefaultChatTransport({ api: '/api/chat', }), sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls, // run client-side tools that are automatically executed: async onToolCall({ toolCall }) { // Check if it's a dynamic tool first for proper type narrowing if (toolCall.dynamic) { return; } if (toolCall.toolName === 'getLocation') { const cities = ['New York', 'Los Angeles', 'Chicago', 'San Francisco']; // No await - avoids potential deadlocks addToolOutput({ tool: 'getLocation', toolCallId: toolCall.toolCallId, output: cities[Math.floor(Math.random() * cities.length)], }); } }, }); const [input, setInput] = useState(''); return ( <> {messages?.map(message => (

{`${message.role}: `} {message.parts.map(part => { switch (part.type) { // render text parts as simple text: case 'text': return part.text; // for tool parts, use the typed tool part names: case 'tool-askForConfirmation': { const callId = part.toolCallId; switch (part.state) { case 'input-streaming': return (

Loading confirmation request...

); case 'input-available': return (

{part.input.message}

); case 'output-available': return (

Location access allowed: {part.output}

); case 'output-error': return

Error: {part.errorText}

; } break; } case 'tool-getLocation': { const callId = part.toolCallId; switch (part.state) { case 'input-streaming': return (

Preparing location request...

); case 'input-available': return

Getting location...

; case 'output-available': return

Location: {part.output}

; case 'output-error': return (

Error getting location: {part.errorText}

); } break; } case 'tool-getWeatherInformation': { const callId = part.toolCallId; switch (part.state) { // example of pre-rendering streaming tool inputs: case 'input-streaming': return (

{JSON.stringify(part, null, 2)}

); case 'input-available': return (

Getting weather information for {part.input.city}...

); case 'output-available': return (

Weather in {part.input.city}: {part.output}

); case 'output-error': return (

Error getting weather for {part.input.city}:{' '} {part.errorText}

); } break; } } })}

))} ); } ``` ### Error handling Sometimes an error may occur during client-side tool execution. Use the `addToolOutput` method with a `state` of `output-error` and `errorText` value instead of `output` record the error. ```tsx filename='app/page.tsx' highlight="19,36-41" 'use client'; import { useChat } from '@ai-sdk/react'; import { DefaultChatTransport, lastAssistantMessageIsCompleteWithToolCalls, } from 'ai'; import { useState } from 'react'; export default function Chat() { const { messages, sendMessage, addToolOutput } = useChat({ transport: new DefaultChatTransport({ api: '/api/chat', }), sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls, // run client-side tools that are automatically executed: async onToolCall({ toolCall }) { // Check if it's a dynamic tool first for proper type narrowing if (toolCall.dynamic) { return; } if (toolCall.toolName === 'getWeatherInformation') { try { const weather = await getWeatherInformation(toolCall.input); // No await - avoids potential deadlocks addToolOutput({ tool: 'getWeatherInformation', toolCallId: toolCall.toolCallId, output: weather, }); } catch (err) { addToolOutput({ tool: 'getWeatherInformation', toolCallId: toolCall.toolCallId, state: 'output-error', errorText: 'Unable to get the weather information', }); } } }, }); } ``` ## Dynamic Tools When using dynamic tools (tools with unknown types at compile time), the UI parts use a generic `dynamic-tool` type instead of specific tool types: ```tsx filename='app/page.tsx' { message.parts.map((part, index) => { switch (part.type) { // Static tools with specific (`tool-${toolName}`) types case 'tool-getWeatherInformation': return ; // Dynamic tools use generic `dynamic-tool` type case 'dynamic-tool': return (

Tool: {part.toolName}

{part.state === 'input-streaming' && (

{JSON.stringify(part.input, null, 2)}

)} {part.state === 'output-available' && (

{JSON.stringify(part.output, null, 2)}

)} {part.state === 'output-error' && (

Error: {part.errorText}

)}

); } }); } ``` Dynamic tools are useful when integrating with: - MCP (Model Context Protocol) tools without schemas - User-defined functions loaded at runtime - External tool providers ## Tool call streaming Tool call streaming is **enabled by default** in AI SDK 5.0, allowing you to stream tool calls while they are being generated. This provides a better user experience by showing tool inputs as they are generated in real-time. ```tsx filename='app/api/chat/route.ts' export async function POST(req: Request) { const { messages }: { messages: UIMessage[] } = await req.json(); const result = streamText({ model: 'anthropic/claude-sonnet-4.5', messages: convertToModelMessages(messages), // toolCallStreaming is enabled by default in v5 // ... }); return result.toUIMessageStreamResponse(); } ``` With tool call streaming enabled, partial tool calls are streamed as part of the data stream. They are available through the `useChat` hook. The typed tool parts of assistant messages will also contain partial tool calls. You can use the `state` property of the tool part to render the correct UI. ```tsx filename='app/page.tsx' highlight="9,10" export default function Chat() { // ... return ( <> {messages?.map(message => (

{message.parts.map(part => { switch (part.type) { case 'tool-askForConfirmation': case 'tool-getLocation': case 'tool-getWeatherInformation': switch (part.state) { case 'input-streaming': return

{JSON.stringify(part.input, null, 2)}

; case 'input-available': return

{JSON.stringify(part.input, null, 2)}

; case 'output-available': return

{JSON.stringify(part.output, null, 2)}

; case 'output-error': return

Error: {part.errorText}

; } } })}

))} ); } ``` ## Step start parts When you are using multi-step tool calls, the AI SDK will add step start parts to the assistant messages. If you want to display boundaries between tool calls, you can use the `step-start` parts as follows: ```tsx filename='app/page.tsx' // ... // where you render the message parts: message.parts.map((part, index) => { switch (part.type) { case 'step-start': // show step boundaries as horizontal lines: return index > 0 ? (

) : null; case 'text': // ... case 'tool-askForConfirmation': case 'tool-getLocation': case 'tool-getWeatherInformation': // ... } }); // ... ``` ## Server-side Multi-Step Calls You can also use multi-step calls on the server-side with `streamText`. This works when all invoked tools have an `execute` function on the server side. ```tsx filename='app/api/chat/route.ts' highlight="15-21,24" import { openai } from '@ai-sdk/openai'; import { convertToModelMessages, streamText, UIMessage, stepCountIs } from 'ai'; import { z } from 'zod'; export async function POST(req: Request) { const { messages }: { messages: UIMessage[] } = await req.json(); const result = streamText({ model: 'anthropic/claude-sonnet-4.5', messages: convertToModelMessages(messages), tools: { getWeatherInformation: { description: 'show the weather in a given city to the user', inputSchema: z.object({ city: z.string() }), // tool has execute function: execute: async ({}: { city: string }) => { const weatherOptions = ['sunny', 'cloudy', 'rainy', 'snowy', 'windy']; return weatherOptions[ Math.floor(Math.random() * weatherOptions.length) ]; }, }, }, stopWhen: stepCountIs(5), }); return result.toUIMessageStreamResponse(); } ``` ## Errors Language models can make errors when calling tools. By default, these errors are masked for security reasons, and show up as "An error occurred" in the UI. To surface the errors, you can use the `onError` function when calling `toUIMessageResponse`. ```tsx export function errorHandler(error: unknown) { if (error == null) { return 'unknown error'; } if (typeof error === 'string') { return error; } if (error instanceof Error) { return error.message; } return JSON.stringify(error); } ``` ```tsx const result = streamText({ // ... }); return result.toUIMessageStreamResponse({ onError: errorHandler, }); ``` In case you are using `createUIMessageResponse`, you can use the `onError` function when calling `toUIMessageResponse`: ```tsx const response = createUIMessageResponse({ // ... async execute(dataStream) { // ... }, onError: error => `Custom error: ${error.message}`, }); ```

chatbot-tool-usage