You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
description: Learn how to use tool calling with the useChat hook.
2
+
title: Chatbot with Tools
3
+
description: Learn how to use tools with the useChat hook.
4
4
---
5
5
6
-
# Chatbot with Tool Calling
6
+
# Chatbot with Tools
7
7
8
8
<Notetype="warning">
9
-
The tool calling functionality described here is experimental. It is currently
10
-
only available for React.
9
+
The tool calling functionality described here currently only available for
10
+
React.
11
11
</Note>
12
12
13
13
With `useChat` and `streamText`, you can use tools in your chatbot application.
14
-
The Vercel AI SDK supports both client and server side tool execution.
14
+
The Vercel AI SDK supports three types of tools in this context:
15
+
16
+
1. Automatically executed server-side tools
17
+
2. Automatically executed client-side tools
18
+
3. Tools that require user interaction, such as confirmation dialogs
15
19
16
20
The flow is as follows:
17
21
22
+
1. The user enters a message in the chat UI.
23
+
1. The message is sent to the API route.
24
+
1. The messages from the client are converted to AI SDK Core messages using `convertToCoreMessages`.
18
25
1. In your server side route, the language model generates tool calls during the `streamText` call.
19
-
The messages from the client are converted to AI SDK Core messages using `convertToCoreMessages`.
20
-
2. All tool calls are forwarded to the client.
21
-
3. Server-side tools are executed using their `execute` method and their results are sent back to the client.
22
-
4. The client-side tools are executed on the client.
23
-
The results of client side tool calls can be appended to last assigned message using `experimental_addToolResult`.
24
-
5. When all tool calls are resolved, the client sends the updated messages with the tool results back to the server, triggering another `streamText` call.
26
+
1. All tool calls are forwarded to the client.
27
+
1. Server-side tools are executed using their `execute` method and their results are forwarded to the client.
28
+
1. Client-side tools that should be automatically executed are handled with the `onToolCall` callback.
29
+
You can return the tool result from the callback.
30
+
1. Client-side tool that require user interactions can be displayed in the UI.
31
+
The tool calls and results are available in the `toolInvocations` property of the last assistant message.
32
+
1. When the user interaction is done, `experimental_addToolResult` can be used to add the tool result to the chat.
33
+
1. When there are tool calls in the last assistant message and all tool results are available, the client sends the updated messages back to the server.
34
+
This triggers another iteration of this flow.
25
35
26
36
The tool call and tool executions are integrated into the assistant message as `toolInvocations`.
27
37
A tool invocation is at first a tool call, and then it becomes a tool result when the tool is executed.
@@ -34,16 +44,15 @@ The tool result contains all information about the tool call as well as the resu
34
44
for backward compatibility.
35
45
</Note>
36
46
37
-
## Example: Client-Side Tool Execution
47
+
## Example
38
48
39
-
In this example, we'll define two tools.
40
-
The client-side tool is a confirmation dialog that asks the user to confirm the execution of the server-side tool.
41
-
The server-side tool is a simple fake tool that restarts an engine.
49
+
In this example, we'll use three tools:
42
50
43
-
### Server-side route
51
+
-`getWeatherInformation`: An automatically executed server-side tool that returns the weather in a given city.
52
+
-`askForConfirmation`: A user-interaction client-side tool that asks the user for confirmation.
53
+
-`getLocation`: An automatically executed client-side tool that returns a random city.
44
54
45
-
Please note that only the `restartEngine` tool has an `execute` method and is executed on the server side.
46
-
The `askForConfirmation` tool is executed on the client side.
55
+
### API route
47
56
48
57
```tsx filename='app/api/chat/route.ts'
49
58
import { openai } from'@ai-sdk/openai';
@@ -60,19 +69,30 @@ export async function POST(req: Request) {
60
69
model: openai('gpt-4-turbo'),
61
70
messages: convertToCoreMessages(messages),
62
71
tools: {
63
-
restartEngine: {
64
-
description:
65
-
'Restarts the engine. '+
66
-
'Always ask for confirmation before using this tool.',
67
-
parameters: z.object({}),
68
-
execute: async () =>'Engine restarted.',
72
+
// server-side tool with execute function:
73
+
getWeatherInformation: {
74
+
description: 'show the weather in a given city to the user',
Copy file name to clipboardexpand all lines: content/docs/07-reference/ai-sdk-ui/01-use-chat.mdx
+180-10
Original file line number
Diff line number
Diff line change
@@ -9,20 +9,190 @@ Allows you to easily create a conversational user interface for your chatbot app
9
9
10
10
## Import
11
11
12
-
### React
12
+
<Tabsitems={['React', 'Svelte', 'Vue', 'Solid']}>
13
+
<Tab>
14
+
<Snippettext="{`import { useChat } from 'ai/react'`}"dark />
15
+
</Tab>
16
+
<Tab>
17
+
<Snippettext="{`import { useChat } from 'ai/svelte'`}"dark />
18
+
</Tab>
19
+
<Tab>
20
+
<Snippettext="{`import { useChat } from 'ai/vue'`}"dark />
21
+
</Tab>
22
+
<Tab>
23
+
<Snippettext="{`import { useChat } from 'ai/solid'`}"dark />
24
+
</Tab>
25
+
</Tabs>
13
26
14
-
<Snippettext={`import { useChat } from "ai/react"`}prompt={false} />
27
+
## API Signature
15
28
16
-
### Svelte
29
+
### Parameters
17
30
18
-
<Snippettext={`import { useChat } from "ai/svelte"`}prompt={false} />
31
+
<PropertiesTable
32
+
content={[
33
+
{
34
+
name: 'api',
35
+
type: "string = '/api/chat'",
36
+
description: 'The chat completion API endpoint offered by the provider.',
37
+
},
38
+
{
39
+
name: 'id',
40
+
type: 'string',
41
+
description:
42
+
'An unique identifier for the chat. If not provided, a random one will be generated. When provided, the `useChat` hook with the same `id` will have shared states across components. This is useful when you have multiple components showing the same chat stream.',
43
+
},
44
+
{
45
+
name: 'initialInput',
46
+
type: "string = ''",
47
+
description: 'An optional string for the initial prompt input.',
48
+
},
49
+
{
50
+
name: 'initialMessages',
51
+
type: 'Messages[] = []',
52
+
description: 'An optional array of initial chat messages',
'Optional callback function that is invoked when a tool call is received. Intended for automatic client-side tool execution. You can optionally return a result for the tool call, either synchronously or asynchronously.',
59
+
},
60
+
{
61
+
name: 'onResponse',
62
+
type: '(response: Response) => void',
63
+
description:
64
+
'An optional callback that will be called with the response from the API endpoint. Useful for throwing customized errors or logging',
65
+
},
66
+
{
67
+
name: 'onFinish',
68
+
type: '(message: Message) => void',
69
+
description:
70
+
'An optional callback function that is called when the completion stream ends.',
71
+
},
72
+
{
73
+
name: 'onError',
74
+
type: '(error: Error) => void',
75
+
description:
76
+
'An optional callback that will be called when the chat stream encounters an error.',
77
+
},
78
+
{
79
+
name: 'generateId',
80
+
type: '() => string',
81
+
description: `Optional. A way to provide a function that is going to be used for ids for messages. If not provided nanoid is used by default.`,
82
+
},
83
+
{
84
+
name: 'headers',
85
+
type: 'Record<string, string> | Headers',
86
+
description:
87
+
'An optional object of headers to be passed to the API endpoint.',
88
+
},
89
+
{
90
+
name: 'body',
91
+
type: 'any',
92
+
description:
93
+
'An optional, additional body object to be passed to the API endpoint.',
94
+
},
95
+
{
96
+
name: 'credentials',
97
+
type: "'omit' | 'same-origin' | 'include'",
98
+
description:
99
+
'An optional literal that sets the mode of credentials to be used on the request. Defaults to same-origin.',
100
+
},
101
+
{
102
+
name: 'sendExtraMessageFields',
103
+
type: 'boolean',
104
+
description:
105
+
"An optional boolean that determines whether to send extra fields you've added to `messages`. Defaults to `false` and only the `content` and `role` fields will be sent to the API endpoint.",
106
+
},
107
+
{
108
+
name: 'experimental_maxAutomaticRoundtrips',
109
+
type: 'number',
110
+
description:
111
+
'React only. Maximal number of automatic roundtrips for tool calls. An automatic tool call roundtrip is a call to the server with the tool call results when all tool calls in the last assistant message have results. A maximum number is required to prevent infinite loops in the case of misconfigured tools. By default, it is set to 0, which will disable the feature.',
112
+
},
113
+
]}
114
+
/>
19
115
20
-
### Vue
116
+
### Returns
21
117
22
-
<Snippettext={`import { useChat } from "ai/vue"`}prompt={false} />
118
+
<PropertiesTable
119
+
content={[
120
+
{
121
+
name: 'messages',
122
+
type: 'Message[]',
123
+
description: 'The current array of chat messages.',
124
+
},
125
+
{
126
+
name: 'error',
127
+
type: 'Error | undefined',
128
+
description: 'An error object returned by SWR, if any.',
'Function to append a message to the chat, triggering an API call for the AI response. It returns a promise that resolves to full response message content when the API call is successfully finished, or throws an error when the API call fails.',
135
+
},
136
+
{
137
+
name: 'reload',
138
+
type: '() => Promise<string | undefined>',
139
+
description:
140
+
"Function to reload the last AI chat response for the given chat history. If the last message isn't from the assistant, it will request the API to generate a new response.",
141
+
},
142
+
{
143
+
name: 'stop',
144
+
type: '() => void',
145
+
description: 'Function to abort the current API request.',
146
+
},
147
+
{
148
+
name: 'setMessages',
149
+
type: '(messages: Message[]) => void',
150
+
description:
151
+
'Function to update the `messages` state locally without triggering an API call.',
152
+
},
153
+
{
154
+
name: 'input',
155
+
type: 'string',
156
+
description: 'The current value of the input field.',
'Form submission handler that automatically resets the input field and appends a user message. You can use the `options` parameter to send additional data, headers and more to the server.',
174
+
},
175
+
{
176
+
name: 'isLoading',
177
+
type: 'boolean',
178
+
description:
179
+
'Boolean flag indicating whether a request is currently in progress.',
180
+
},
181
+
{
182
+
name: 'data',
183
+
type: 'JSONValue[]',
184
+
description: 'Data returned from experimental_StreamData',
'React only. Function to add a tool result to the chat. This will update the chat messages with the tool result and call the API route if all tool results for the last message are available.',
191
+
},
192
+
]}
193
+
/>
23
194
24
-
### Solid
195
+
##Learn more
25
196
26
-
<Snippettext={`import { useChat } from "ai/solid"`}prompt={false} />
0 commit comments