Skip to content
Source
Sign inSign up
TanStack/ai
Open History to see the last commit

tools.md

349 lines10.1 KB

1---
2title: Tools
3id: tools
4order: 1
5description: "Define isomorphic AI tools in TanStack AI with toolDefinition() for type-safe server- and client-side function calling across any framework."
6keywords:
7 - tanstack ai
8 - tools
9 - function calling
10 - toolDefinition
11 - isomorphic tools
12 - server tools
13 - client tools
14 - type safety
15---
16​
17Tools (also called "function calling") allow AI models to interact with external systems, APIs, or perform computations. TanStack AI provides an isomorphic tool system that enables type-safe, framework-agnostic tool definitions that work on both server and client.
18​
19Tools enable your AI application to:
20​
21- **Fetch data** from APIs or databases
22- **Perform calculations** or data transformations
23- **Interact with services** like email, calendars, or payment systems
24- **Execute client-side operations** like updating UI or local storage
25- **Create hybrid tools** that execute in both server and client contexts
26​
27> Looking for provider-native tools like Anthropic web search, OpenAI code
28> interpreter, or Gemini URL context? See [Provider Tools](./provider-tools.md).
29​
30## Framework Support
31​
32TanStack AI works with **any** JavaScript framework:
33- Next.js, Express, Remix, Fastify, etc.
34- React, Vue, Solid, Svelte, vanilla JS, etc.
35​
36TanStack AI works with any JavaScript framework.
37​
38## Isomorphic Tool Architecture
39​
40TanStack AI uses a two-step tool definition process:
41​
421. **Define once** with `toolDefinition()` - Creates a shared tool schema
432. **Implement** with `.server()` or `.client()` - Add execution logic for each environment
44​
45This approach provides:
46​
47- **Type Safety**: Full TypeScript inference from Zod schemas
48- **Code Reuse**: Define schemas once, use everywhere
49- **Flexibility**: Tools can execute on server, client, or both
50- **Schema Options**: Use Zod schemas or raw JSON Schema objects
51​
52## Schema Options
53​
54TanStack AI supports two ways to define tool schemas:
55​
56### Option 1: Zod Schemas (Recommended)
57​
58Zod schemas provide full TypeScript type inference and runtime validation:
59​
60```typescript
61import { z } from "zod";
62​
63const inputSchema = z.object({
64 location: z.string().meta({ description: "City name" }),
65 unit: z.enum(["celsius", "fahrenheit"]).optional(),
66});
67```
68​
69### Option 2: JSON Schema Objects
70​
71For cases where you already have JSON Schema definitions or prefer not to use Zod, you can pass raw JSON Schema objects directly:
72​
73```typescript
74import type { JSONSchema } from "@tanstack/ai";
75​
76const inputSchema: JSONSchema = {
77 type: "object",
78 properties: {
79 location: {
80 type: "string",
81 description: "City name",
82 },
83 unit: {
84 type: "string",
85 enum: ["celsius", "fahrenheit"],
86 },
87 },
88 required: ["location"],
89};
90```
91​
92> **Note:** When using JSON Schema, TypeScript will infer `any` for input/output types since JSON Schema cannot provide compile-time type information. Zod schemas are recommended for full type safety.
93​
94## Tool Definition
95​
96Tools are defined using `toolDefinition()` from `@tanstack/ai`:
97​
98```typescript
99import { toolDefinition } from "@tanstack/ai";
100import { z } from "zod";
101​
102// Step 1: Define the tool schema
103const getWeatherDef = toolDefinition({
104 name: "get_weather",
105 description: "Get the current weather for a location",
106 inputSchema: z.object({
107 location: z.string().meta({ description: "The city and state, e.g. San Francisco, CA" }),
108 unit: z.enum(["celsius", "fahrenheit"]).optional(),
109 }),
110 outputSchema: z.object({
111 temperature: z.number(),
112 conditions: z.string(),
113 location: z.string(),
114 }),
115});
116​
117// Step 2: Create a server implementation
118const getWeatherServer = getWeatherDef.server(async ({ location, unit }) => {
119 const response = await fetch(
120 `https://api.weather.com/v1/current?location=${location}&unit=${
121 unit || "fahrenheit"
122 }`
123 );
124 const data = await response.json();
125 return {
126 temperature: data.temperature,
127 conditions: data.conditions,
128 location: data.location,
129 };
130});
131```
132​
133### Using JSON Schema
134​
135If you prefer JSON Schema or have existing schema definitions:
136​
137```typescript
138import { toolDefinition } from "@tanstack/ai";
139import type { JSONSchema } from "@tanstack/ai";
140​
141// Define schemas using JSON Schema
142const inputSchema: JSONSchema = {
143 type: "object",
144 properties: {
145 location: {
146 type: "string",
147 description: "The city and state, e.g. San Francisco, CA",
148 },
149 unit: {
150 type: "string",
151 enum: ["celsius", "fahrenheit"],
152 },
153 },
154 required: ["location"],
155};
156​
157const outputSchema: JSONSchema = {
158 type: "object",
159 properties: {
160 temperature: { type: "number" },
161 conditions: { type: "string" },
162 location: { type: "string" },
163 },
164 required: ["temperature", "conditions", "location"],
165};
166​
167// Create the tool definition
168const getWeatherDef = toolDefinition({
169 name: "get_weather",
170 description: "Get the current weather for a location",
171 inputSchema,
172 outputSchema,
173});
174​
175// Create server implementation (args is typed as `any` with JSON Schema)
176const getWeatherServer = getWeatherDef.server(async (args) => {
177 const { location, unit } = args;
178 const response = await fetch(
179 `https://api.weather.com/v1/current?location=${location}&unit=${unit || "fahrenheit"}`
180 );
181 return await response.json();
182});
183```
184​
185## Using Tools in Chat
186​
187### Server-Side
188​
189```typescript
190import { chat, toServerSentEventsResponse } from "@tanstack/ai";
191import { openaiText } from "@tanstack/ai-openai";
192import { getWeatherDef } from "./tools";
193​
194export async function POST(request: Request) {
195 const { messages } = await request.json();
196​
197 // Create server implementation
198 const getWeather = getWeatherDef.server(async ({ location, unit }) => {
199 const response = await fetch(`https://api.weather.com/v1/current?...`);
200 return await response.json();
201 });
202​
203 const stream = chat({
204 adapter: openaiText("gpt-5.2"),
205 messages,
206 tools: [getWeather], // Pass server tools
207 });
208​
209 return toServerSentEventsResponse(stream);
211```
212​
213### Client-Side with Type Safety
214​
215```typescript
216import { useChat, fetchServerSentEvents } from "@tanstack/ai-react";
217import {
218 clientTools,
219 createChatClientOptions,
220 type InferChatMessages
221} from "@tanstack/ai-client";
222import { updateUIDef, saveToStorageDef } from "./tools";
223​
224// Create client implementations
225const updateUI = updateUIDef.client((input) => {
226 // Update UI state
227 setNotification(input.message);
228 return { success: true };
229});
230​
231const saveToStorage = saveToStorageDef.client((input) => {
232 localStorage.setItem("data", JSON.stringify(input));
233 return { saved: true };
234});
235​
236// Create typed tools array (no 'as const' needed!)
237const tools = clientTools(updateUI, saveToStorage);
238​
239const textOptions = createChatClientOptions({
240 connection: fetchServerSentEvents("/api/chat"),
241 tools,
242});
243​
244// Infer message types for full type safety
245type ChatMessages = InferChatMessages<typeof textOptions>;
246​
247function ChatComponent() {
248 const { messages, sendMessage } = useChat(textOptions);
250 // messages is now fully typed with tool names and outputs!
251 return <Messages messages={messages} />;
253```
254​
255## Hybrid Tools
256​
257Tools can be implemented for both server and client, enabling flexible execution patterns:
258​
259```typescript
260// Define once
261const addToCartDef = toolDefinition({
262 name: "add_to_cart",
263 description: "Add item to shopping cart",
264 inputSchema: z.object({
265 itemId: z.string(),
266 quantity: z.number(),
267 }),
268 outputSchema: z.object({
269 success: z.boolean(),
270 cartId: z.string(),
271 }),
272 needsApproval: true,
273});
274​
275// Server implementation - Store in database
276const addToCartServer = addToCartDef.server(async (input) => {
277 const cart = await db.carts.create({
278 data: { itemId: input.itemId, quantity: input.quantity },
279 });
280 return { success: true, cartId: cart.id };
281});
282​
283// Client implementation - Update local wishlist
284const addToCartClient = addToCartDef.client((input) => {
285 const wishlist = JSON.parse(localStorage.getItem("wishlist") || "[]");
286 wishlist.push(input.itemId);
287 localStorage.setItem("wishlist", JSON.stringify(wishlist));
288 return { success: true, cartId: "local" };
289});
290```
291​
292On the server, pass the definition (for client execution) or server implementation:
293​
294```typescript
295chat({
296 adapter: openaiText("gpt-5.2"),
297 messages,
298 tools: [addToCartDef], // Client will execute, or
299 tools: [addToCartServer], // Server will execute
300});
301```
302​
303## Type Safety Benefits
304​
305The isomorphic architecture provides complete type safety:
306​
307```typescript
308// In your React component
309messages.forEach((message) => {
310 message.parts.forEach((part) => {
311 if (part.type === 'tool-call' && part.name === 'add_to_cart') {
312 // ✅ TypeScript knows part.name is literally 'add_to_cart'
313 // ✅ part.input is typed as { itemId: string, quantity: number }
314 // ✅ part.output is typed as { success: boolean, cartId: string } | undefined
316 if (part.output) {
317 console.log(part.output.cartId); // ✅ Fully typed!
318 }
319 }
320 });
321});
322```
323​
324## Tool Execution Flow
325​
3261. **Model decides to call a tool** - Based on user input and tool descriptions
3272. **Tool is identified** - Server or client implementation
3283. **Tool executes** - Automatically on server or client
3294. **Result is returned** - To the model as a tool result message
3305. **Model continues** - Uses the result to generate a response
331​
332## Tool States
333​
334Tools go through different states during execution:
335​
336- `awaiting-input` - Tool call received, waiting for arguments
337- `input-streaming` - Partial arguments being streamed
338- `input-complete` - All arguments received
339- `approval-requested` - Tool requires user approval (if `needsApproval: true`)
340- `approval-responded` - User has approved/denied
341​
342> **Tip:** If your use case involves calling multiple tools with complex logic (filtering, aggregation, parallel calls), consider [Code Mode](../code-mode/code-mode) — it lets the LLM write a TypeScript program that orchestrates tools in a single execution instead of one tool call at a time.
343​
344## Next Steps
345​
346- [Server Tools](./server-tools) - Learn about server-side tool execution
347- [Client Tools](./client-tools) - Learn about client-side tool execution
348- [Tool Approval Flow](./tool-approval) - Implement approval workflows
349- [How Tools Work](./tool-architecture) - Deep dive into the tool architecture