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

server-tools.md

321 lines9.0 KB

1---
2title: Server Tools
3id: server-tools
4order: 3
5description: "Server tools in TanStack AI execute automatically with full access to databases, APIs, and environment variables. Patterns, examples, and security."
6keywords:
7 - tanstack ai
8 - server tools
9 - function calling
10 - backend tools
11 - tool execute
12 - database access
13---
14​
15Server tools execute automatically when called by the LLM. They have full access to server resources like databases, APIs, and environment variables.
16​
17```mermaid
18sequenceDiagram
19 participant LLM Service
20 participant Server
21 participant Tool
22 participant Database/API
24 LLM Service->>Server: tool_call chunk<br/>{name: "getUserData", args: {...}}
25 Server->>Server: Parse tool call<br/>arguments
26 Server->>Tool: execute(parsedArgs)
27 Tool->>Database/API: Query/Fetch data
28 Database/API-->>Tool: Return data
29 Tool-->>Server: Return result
30 Server->>Server: Create tool_result<br/>message
31 Server->>LLM Service: Continue chat with<br/>tool_result in history
33 Note over LLM Service: Model uses result<br/>to generate response
35 LLM Service-->>Server: Stream content chunks
36 Server-->>Server: Stream to client
37```
38​
39## How It Works
40​
411. **Tool Call Received**: Server receives a `tool_call` chunk from the LLM
422. **Argument Parsing**: The tool arguments (JSON string) are parsed and validated against the input schema
433. **Execution**: The tool's `execute` function is called with the parsed arguments
444. **Result Processing**: The result is:
45 - Validated against the output schema (if defined)
46 - Converted to a tool result message
47 - Added to the conversation history
485. **Continuation**: The chat continues with the tool result, allowing the LLM to generate a response based on the result
50## Automatic vs. Manual Execution
51​
52**Automatic (Default):**
53- Server tools with an `execute` function run automatically
54- Results are added to the conversation immediately
55- No client-side handling required
56​
57**Manual (Advanced):**
58- You can handle tool calls manually by intercepting the stream
59- Useful for custom orchestration or approval flows
60​
61## Server Tool Definition
62​
63```typescript
64import { toolDefinition } from "@tanstack/ai";
65import { z } from "zod";
66​
67const getUserDataDef = toolDefinition({
68 name: "get_user_data",
69 description: "Get user information from the database",
70 inputSchema: z.object({
71 userId: z.string().meta({ description: "The user ID to look up" }),
72 }),
73 outputSchema: z.object({
74 name: z.string(),
75 email: z.string().email(),
76 createdAt: z.string(),
77 }),
78});
79​
80const getUserData = getUserDataDef.server(async ({ userId }) => {
81 // This runs on the server - secure access to database
82 const user = await db.users.findUnique({ where: { id: userId } });
83 return {
84 name: user.name,
85 email: user.email,
86 createdAt: user.createdAt.toISOString(),
87 };
88});
89```
90​
91## Defining Server Tools
92​
93Server tools use the isomorphic `toolDefinition()` API with the `.server()` method:
94​
95```typescript
96import { toolDefinition } from "@tanstack/ai";
97import { z } from "zod";
98​
99// Step 1: Define the tool schema
100const getUserDataDef = toolDefinition({
101 name: "get_user_data",
102 description: "Get user information from the database",
103 inputSchema: z.object({
104 userId: z.string().meta({ description: "The user ID to look up" }),
105 }),
106 outputSchema: z.object({
107 name: z.string(),
108 email: z.string().email(),
109 createdAt: z.string(),
110 }),
111});
112​
113// Step 2: Create server implementation
114const getUserData = getUserDataDef.server(async ({ userId }) => {
115 // This runs on the server - can access database, APIs, etc.
116 const user = await db.users.findUnique({ where: { id: userId } });
117 return {
118 name: user.name,
119 email: user.email,
120 createdAt: user.createdAt.toISOString(),
121 };
122});
123​
124// Example: API call tool
125const searchProductsDef = toolDefinition({
126 name: "search_products",
127 description: "Search for products in the catalog",
128 inputSchema: z.object({
129 query: z.string().meta({ description: "Search query" }),
130 limit: z.number().optional().meta({ description: "Maximum number of results" }),
131 }),
132});
133​
134const searchProducts = searchProductsDef.server(async ({ query, limit = 10 }) => {
135 const response = await fetch(
136 `https://api.example.com/products?q=${query}&limit=${limit}`,
137 {
138 headers: {
139 Authorization: `Bearer ${process.env.API_KEY}`, // Server-only access
140 },
141 }
142 );
143 return await response.json();
144});
145```
146​
147## Using Server Tools
148​
149Pass tools to the `chat` function:
150​
151```typescript
152import { chat, toServerSentEventsResponse } from "@tanstack/ai";
153import { openaiText } from "@tanstack/ai-openai";
154import { getUserData, searchProducts } from "./tools";
155​
156export async function POST(request: Request) {
157 const { messages } = await request.json();
158​
159 const stream = chat({
160 adapter: openaiText("gpt-5.2"),
161 messages,
162 tools: [getUserData, searchProducts],
163 });
164​
165 return toServerSentEventsResponse(stream);
167```
168​
169## Tool Organization Pattern
170​
171For better organization, define tool schemas and implementations separately:
172​
173```typescript
174// tools/definitions.ts
175import { toolDefinition } from "@tanstack/ai";
176import { z } from "zod";
177​
178export const getUserDataDef = toolDefinition({
179 name: "get_user_data",
180 description: "Get user information",
181 inputSchema: z.object({
182 userId: z.string(),
183 }),
184 outputSchema: z.object({
185 name: z.string(),
186 email: z.string(),
187 }),
188});
189​
190export const searchProductsDef = toolDefinition({
191 name: "search_products",
192 description: "Search products",
193 inputSchema: z.object({
194 query: z.string(),
195 }),
196});
197​
198// tools/server.ts
199import { getUserDataDef, searchProductsDef } from "./definitions";
200import { db } from "@/lib/db";
201​
202export const getUserData = getUserDataDef.server(async ({ userId }) => {
203 const user = await db.users.findUnique({ where: { id: userId } });
204 return { name: user.name, email: user.email };
205});
206​
207export const searchProducts = searchProductsDef.server(async ({ query }) => {
208 const products = await db.products.search(query);
209 return products;
210});
211​
212// api/chat/route.ts
213import { chat } from "@tanstack/ai";
214import { openaiText } from "@tanstack/ai-openai";
215import { getUserData, searchProducts } from "@/tools/server";
216​
217const stream = chat({
218 adapter: openaiText("gpt-5.2"),
219 messages,
220 tools: [getUserData, searchProducts],
221});
222```
223​
224## Automatic Execution
225​
226Server tools are automatically executed when the model calls them. The SDK:
227​
2281. Receives the tool call from the model
2292. Executes the tool's `execute` function
2303. Adds the result to the conversation
2314. Continues the chat with the tool result
232​
233You don't need to manually handle tool execution - it's automatic!
234​
235## Error Handling
236​
237Tools should handle errors gracefully:
238​
239```typescript
240const getUserDataDef = toolDefinition({
241 name: "get_user_data",
242 description: "Get user information",
243 inputSchema: z.object({
244 userId: z.string(),
245 }),
246 outputSchema: z.object({
247 name: z.string().optional(),
248 email: z.string().optional(),
249 error: z.string().optional(),
250 }),
251});
252​
253const getUserData = getUserDataDef.server(async ({ userId }) => {
254 try {
255 const user = await db.users.findUnique({ where: { id: userId } });
256 if (!user) {
257 return { error: "User not found" };
258 }
259 return { name: user.name, email: user.email };
260 } catch (error) {
261 return { error: "Failed to fetch user data" };
262 }
263});
264```
265​
266## Using JSON Schema
267​
268If you have existing JSON Schema definitions or prefer not to use Zod, you can define tool schemas using raw JSON Schema objects:
269​
270```typescript
271import { toolDefinition } from "@tanstack/ai";
272import type { JSONSchema } from "@tanstack/ai";
273​
274const inputSchema: JSONSchema = {
275 type: "object",
276 properties: {
277 userId: {
278 type: "string",
279 description: "The user ID to look up",
280 },
281 },
282 required: ["userId"],
283};
284​
285const outputSchema: JSONSchema = {
286 type: "object",
287 properties: {
288 name: { type: "string" },
289 email: { type: "string" },
290 },
291 required: ["name", "email"],
292};
293​
294const getUserDataDef = toolDefinition({
295 name: "get_user_data",
296 description: "Get user information from the database",
297 inputSchema,
298 outputSchema,
299});
300​
301// When using JSON Schema, args is typed as `any`
302const getUserData = getUserDataDef.server(async (args) => {
303 const user = await db.users.findUnique({ where: { id: args.userId } });
304 return { name: user.name, email: user.email };
305});
306```
307​
308> **Note:** JSON Schema tools skip runtime validation. Zod schemas are recommended for full type safety and validation.
309​
310## Best Practices
311​
3121. **Keep tools focused** - Each tool should do one thing well
3132. **Validate inputs** - Use Zod schemas to ensure type safety (JSON Schema skips validation)
3143. **Handle errors** - Return meaningful error messages
3154. **Use descriptions** - Clear descriptions help the model use tools correctly
3165. **Secure sensitive operations** - Never expose API keys or secrets to the client
317​
318## Next Steps
319​
320- [Client Tools](./client-tools) - Learn about client-side tool execution
321- [Tool Approval Flow](./tool-approval) - Add approval workflows for sensitive operations