Open History to see the last commit
1---
2title: Client Tools
3id: client-tools
4order: 4
5description: "Client tools in TanStack AI run in the browser for UI updates, localStorage, and browser API access with type-safe onToolCall handling."
6keywords:
7 - tanstack ai
8 - client tools
9 - browser tools
10 - ui tools
11 - onToolCall
12 - clientTools
13 - localStorage
14---
15
16Client tools execute in the browser, enabling UI updates, local storage access, and browser API interactions. Unlike server tools, client tools don't have an `execute` function in their server definition.
17
18```mermaid
19sequenceDiagram
20 participant LLM Service
21 participant Server
22 participant Browser
23 participant ClientTool
25 LLM Service->>Server: tool_call chunk<br/>{name: "updateUI", args: {...}}
26 Server->>Server: Check if tool has<br/>server execute
28 Note over Server: No execute function<br/>= client tool
30 Server->>Browser: Forward tool-input-available<br/>chunk via SSE/HTTP
31 Browser->>Browser: onToolCall callback<br/>triggered
32 Browser->>ClientTool: execute(args)
33 ClientTool->>ClientTool: Update UI,<br/>localStorage, etc.
34 ClientTool-->>Browser: Return result
35 Browser->>Server: POST tool result
36 Server->>LLM Service: Add tool_result<br/>to conversation
38 Note over LLM Service: Model uses result<br/>to continue
40 LLM Service-->>Server: Stream response
41 Server-->>Browser: Forward chunks
42```
43
44## When to Use Client Tools
45
46- **UI Updates**: Show notifications, update forms, toggle visibility
47- **Local Storage**: Save user preferences, cache data
48- **Browser APIs**: Access geolocation, camera, clipboard
49- **State Management**: Update React/Vue/Solid state
50- **Navigation**: Change routes, scroll to sections
51
52## How It Works
53
541. **Tool Call from LLM**: LLM decides to call a client tool
552. **Server Detection**: Server sees the tool has no `execute` function
563. **Client Notification**: Server sends a `tool-input-available` chunk to the browser
574. **Client Execution**: Browser's `onToolCall` callback is triggered with:
58 - `toolName`: Name of the tool to execute
59 - `input`: Parsed arguments
605. **Result Return**: Client executes the tool and returns the result
616. **Server Update**: Result is sent back to the server and added to the conversation
627. **LLM Continuation**: LLM receives the result and continues the conversation
63
64## Defining Client Tools
65
66Client tools use the same `toolDefinition()` API but with the `.client()` method:
67
68```typescript
69// tools/definitions.ts - Shared between server and client
70import { toolDefinition } from "@tanstack/ai";
71import { z } from "zod";
72
73export const updateUIDef = toolDefinition({
74 name: "update_ui",
75 description: "Update the UI with new information",
76 inputSchema: z.object({
77 message: z.string().meta({ description: "Message to display" }),
78 type: z.enum(["success", "error", "info"]).meta({ description: "Message type" }),
79 }),
80 outputSchema: z.object({
81 success: z.boolean(),
82 }),
83});
84
85export const saveToLocalStorageDef = toolDefinition({
86 name: "save_to_local_storage",
87 description: "Save data to browser local storage",
88 inputSchema: z.object({
89 key: z.string().meta({ description: "Storage key" }),
90 value: z.string().meta({ description: "Value to store" }),
91 }),
92 outputSchema: z.object({
93 saved: z.boolean(),
94 }),
95});
96```
97
98## Using Client Tools
99
100### Server-Side
101
102To give the LLM access to client tools, pass the tool definitions (not implementations) to the server when creating the chat:
103
104```typescript
105// api/chat/route.ts
106import { chat, toServerSentEventsStream } from "@tanstack/ai";
107import { openaiText } from "@tanstack/ai-openai";
108import { updateUIDef, saveToLocalStorageDef } from "@/tools/definitions";
109
110export async function POST(request: Request) {
111 const { messages } = await request.json();
112
113 const stream = chat({
114 adapter: openaiText("gpt-5.2"),
115 messages,
116 tools: [updateUIDef, saveToLocalStorageDef], // Pass definitions
117 });
118
119 return toServerSentEventsStream(stream);
120}
121```
122
123### Client-Side
124
125Create client implementations with automatic execution and full type safety:
126
127```typescript
128// app/chat.tsx
129import { useChat, fetchServerSentEvents } from "@tanstack/ai-react";
130import {
131 clientTools,
132 createChatClientOptions,
133 type InferChatMessages
134} from "@tanstack/ai-client";
135import { updateUIDef, saveToLocalStorageDef } from "@/tools/definitions";
136import { useState } from "react";
137
138function ChatComponent() {
139 const [notification, setNotification] = useState(null);
140
141 // Step 1: Create client implementations
142 const updateUI = updateUIDef.client((input) => {
143 // Update React state - fully typed!
144 setNotification({ message: input.message, type: input.type });
145 return { success: true };
146 });
147
148 const saveToLocalStorage = saveToLocalStorageDef.client((input) => {
149 localStorage.setItem(input.key, input.value);
150 return { saved: true };
151 });
152
153 // Step 2: Create typed tools array (no 'as const' needed!)
154 const tools = clientTools(updateUI, saveToLocalStorage);
155
156 const chatOptions = createChatClientOptions({
157 connection: fetchServerSentEvents("/api/chat"),
158 tools,
159 });
160
161 // Step 3: Infer message types for full type safety
162 type ChatMessages = InferChatMessages<typeof chatOptions>;
163
164 const { messages, sendMessage, isLoading } = useChat(chatOptions);
165
166 // Step 4: Render with full type safety
167 return (
168 <div>
169 {messages.map((message) => (
170 <MessageComponent key={message.id} message={message} />
171 ))}
172 {notification && (
173 <div className={`notification ${notification.type}`}>
174 {notification.message}
175 </div>
176 )}
177 </div>
178 );
179}
180
181// Messages component with full type safety
182function MessageComponent({ message }: { message: ChatMessages[number] }) {
183 return (
184 <div>
185 {message.parts.map((part) => {
186 if (part.type === "text") {
187 return <p>{part.content}</p>;
188 }
190 if (part.type === "tool-call") {
191 // ✅ part.name is narrowed to specific tool names
192 if (part.name === "update_ui") {
193 // ✅ part.input is typed as { message: string, type: "success" | "error" | "info" }
194 // ✅ part.output is typed as { success: boolean } | undefined
195 return (
196 <div>
197 Tool: {part.name}
198 {part.output && <span>✓ Success</span>}
199 </div>
200 );
201 }
202 }
203 })}
204 </div>
205 );
206}
207```
208
209## Automatic Execution
210
211Client tools are **automatically executed** when the model calls them. No manual `onToolCall` callback needed! The flow is:
212
2131. LLM calls a client tool
2142. Server sends `tool-input-available` chunk to browser
2153. Client automatically executes the matching tool implementation
2164. Result is sent back to server
2175. Conversation continues with the result
218
219## Type Safety Benefits
220
221The isomorphic architecture provides complete end-to-end type safety:
222
223```typescript
224messages.forEach((message) => {
225 message.parts.forEach((part) => {
226 if (part.type === "tool-call" && part.name === "update_ui") {
227 // ✅ TypeScript knows part.name is literally "update_ui"
228 // ✅ part.input is typed as { message: string, type: "success" | "error" | "info" }
229 // ✅ part.output is typed as { success: boolean } | undefined
231 console.log(part.input.message); // ✅ Fully typed!
233 if (part.output) {
234 console.log(part.output.success); // ✅ Fully typed!
235 }
236 }
237 });
238});
239```
240
241## Tool States
242Client tools go through a small set of observable lifecycle states you can surface in the UI to indicate progress:
243
244- `awaiting-input` — the model intends to call the tool but arguments haven't arrived yet.
245- `input-streaming` — the model is streaming the tool arguments (partial input may be available).
246- `input-complete` — all arguments have been received and the tool is executing.
247- `completed` — the tool finished; part.output contains the result (or error details).
248
249Use these states to show loading indicators, streaming progress, and final success/error feedback. The example below maps each state to a simple UI message.
250
251```typescript
252function ToolCallDisplay({ part }: { part: ToolCallPart }) {
253 if (part.state === "awaiting-input") {
254 return <div>🔄 Waiting for arguments...</div>;
255 }
257 if (part.state === "input-streaming") {
258 return <div>📥 Receiving arguments...</div>;
259 }
261 if (part.state === "input-complete") {
262 return <div>✓ Arguments received, executing...</div>;
263 }
265 if (part.output) {
266 return <div>✅ Tool completed successfully</div>;
267 }
269 return null;
270}
271```
272
273## Hybrid Tools
274
275Tools can be implemented for both server and client, enabling flexible execution:
276
277```typescript
278// Define once
279const addToCartDef = toolDefinition({
280 name: "add_to_cart",
281 description: "Add item to shopping cart",
282 inputSchema: z.object({
283 itemId: z.string(),
284 quantity: z.number(),
285 }),
286 outputSchema: z.object({
287 success: z.boolean(),
288 cartId: z.string(),
289 }),
290});
291
292// Server implementation - Store in database
293const addToCartServer = addToCartDef.server(async (input) => {
294 const cart = await db.carts.create({
295 data: { itemId: input.itemId, quantity: input.quantity },
296 });
297 return { success: true, cartId: cart.id };
298});
299
300// Client implementation - Update local wishlist
301const addToCartClient = addToCartDef.client((input) => {
302 const wishlist = JSON.parse(localStorage.getItem("wishlist") || "[]");
303 wishlist.push(input.itemId);
304 localStorage.setItem("wishlist", JSON.stringify(wishlist));
305 return { success: true, cartId: "local" };
306});
307
308// Server: Pass definition for client execution
309chat({ adapter: openaiText('gpt-5.2'), messages: [], tools: [addToCartDef] }); // Client will execute
310
311// Or pass server implementation for server execution
312chat({ adapter: openaiText('gpt-5.2'), messages: [], tools: [addToCartServer] }); // Server will execute
313```
314
315## Best Practices
316
317- **Keep client tools simple** - Since client tools run in the browser, avoid heavy computations or large dependencies that could bloat your bundle size.
318- **Handle errors gracefully** - Define clear error handling in your tool implementations and return meaningful error messages in your output schema.
319- **Update UI reactively** - Use your framework's state management (eg. React/Vue/Solid) to update the UI in response to tool executions.
320- **Secure sensitive data** - Never store sensitive data (like API keys or personal info) in local storage or expose it via client tools.
321- **Provide feedback** - Use tool states to inform users about ongoing operations and results of client tool executions (loading spinners, success messages, error alerts).
322- **Type everything** - Leverage TypeScript and Zod schemas for full type safety from tool definitions to implementations to usage.
323
324## Common Use Cases
325
326- **UI Updates** - Show notifications, update forms, toggle visibility
327- **Local Storage** - Save user preferences, cache data
328- **Browser APIs** - Access geolocation, camera, clipboard
329- **State Management** - Update React/Vue/Solid state
330- **Navigation** - Change routes, scroll to sections
331- **Analytics** - Track user interactions
332
333## Next Steps
334
335- [How Tools Work](./tools) - Deep dive into the tool architecture
336- [Server Tools](./server-tools) - Learn about server-side tool execution
337- [Tool Approval Flow](./tool-approval) - Add approval workflows for sensitive operations
338