ToolsCall Tools in Parallel

Call Tools in Parallel

Some language models support calling tools in parallel. This is particularly useful when multiple tools are independent of each other and can be executed in parallel during the same generation step.

User: How is it going?
Assistant: All good, how may I help you?
What is the weather in Paris and New York?
Send Message


Let's create a React component that imports the useChat hook from the ai/react module. The useChat hook will call the /api/chat endpoint when the user sends a message. The endpoint will generate the assistant's response based on the conversation history and stream it to the client. If the assistant responds with a tool call, the hook will automatically display them as well.

You will use the maxToolRoundtrips to specify the maximum number of consecutive tool calls that can made before the model or the user responds with a text message. In this example, you will set it to 1 to allow for one round trip to happen.

import { useChat } from 'ai/react';
export default function Page() {
const { messages, input, setInput, append } = useChat({
api: '/api/chat',
maxToolRoundtrips: 1,
return (
onChange={event => {
onKeyDown={async event => {
if (event.key === 'Enter') {
append({ content: input, role: 'user' });
{, index) => (
<div key={index}>{message.content}</div>


You will create a new route at /api/chat that will use the streamText function from the ai module to generate the assistant's response based on the conversation history.

You will use the tools parameter to specify a tool called celsiusToFahrenheit that will convert a user given value in celsius to fahrenheit.

You will add the getWeather function and use zod to specify the schema for its parameters.

import { ToolInvocation, convertToCoreMessages, streamText } from 'ai';
import { openai } from '@ai-sdk/openai';
import { z } from 'zod';
interface Message {
role: 'user' | 'assistant';
content: string;
toolInvocations?: ToolInvocation[];
function getWeather({ city, unit }) {
return { value: 25, description: 'Sunny' };
export async function POST(req: Request) {
const { messages }: { messages: Message[] } = await req.json();
const result = await streamText({
model: openai('gpt-4o'),
system: 'You are a helpful assistant.',
messages: convertToCoreMessages(messages),
tools: {
getWeather: {
description: 'Get the weather for a location',
parameters: z.object({
city: z.string().describe('The city to get the weather for'),
unit: z
.enum(['C', 'F'])
.describe('The unit to display the temperature in'),
execute: async ({ city, unit }) => {
const { value, description } = getWeather({ city, unit });
return `It is currently 25°${value}°${unit} and ${description} in ${city}!`;
return result.toAIStreamResponse();

View Example on GitHub