Open History to see the last commit
1---
2title: "@tanstack/ai"
3id: tanstack-ai-api
4order: 1
5description: "API reference for @tanstack/ai — the core TanStack AI library providing chat(), generateImage(), toolDefinition(), and streaming utilities."
6keywords:
7 - tanstack ai
8 - "@tanstack/ai"
9 - api reference
10 - chat
11 - toolDefinition
12 - generateImage
13 - core library
14---
15
16The core AI library for TanStack AI.
17
18## Installation
19
20```bash
21npm install @tanstack/ai
22```
23
24## `chat(options)`
25
26Creates a streaming chat response.
27
28```typescript
29import { chat } from "@tanstack/ai";
30import { openaiText } from "@tanstack/ai-openai";
31
32const stream = chat({
33 adapter: openaiText("gpt-5.2"),
34 messages: [{ role: "user", content: "Hello!" }],
35 tools: [myTool],
36 systemPrompts: ["You are a helpful assistant"],
37 agentLoopStrategy: maxIterations(20),
38});
39```
40
41### Parameters
42
43- `adapter` - An AI adapter instance with model (e.g., `openaiText('gpt-5.2')`, `anthropicText('claude-sonnet-4-5')`)
44- `messages` - Array of chat messages. Accepts mixed `UIMessage | ModelMessage` arrays — internal conversion handles AG-UI fan-out dedup, drops `reasoning`/`activity`, and collapses `developer` → `system`
45- `tools?` - Array of tools for function calling
46- `systemPrompts?` - System prompts to prepend to messages
47- `agentLoopStrategy?` - Strategy for agent loops (default: `maxIterations(5)`)
48- `abortController?` - AbortController for cancellation
49- `modelOptions?` - Model-specific options (renamed from `providerOptions`)
50- `threadId?` - AG-UI thread identifier propagated into `RUN_STARTED` events for run correlation
51- `runId?` - AG-UI run identifier (auto-generated if omitted)
52- `parentRunId?` - AG-UI parent run identifier for nested runs
53
54### Returns
55
56An async iterable of `StreamChunk`.
57
58## `summarize(options)`
59
60Creates a text summarization.
61
62```typescript
63import { summarize } from "@tanstack/ai";
64import { openaiSummarize } from "@tanstack/ai-openai";
65
66const result = await summarize({
67 adapter: openaiSummarize("gpt-5.2"),
68 text: "Long text to summarize...",
69 maxLength: 100,
70 style: "concise",
71});
72```
73
74### Parameters
75
76- `adapter` - An AI adapter instance with model
77- `text` - Text to summarize
78- `maxLength?` - Maximum length of summary
79- `style?` - Summary style ("concise" | "detailed")
80- `modelOptions?` - Model-specific options
81
82### Returns
83
84A `SummarizationResult` with the summary text.
85
86## `toolDefinition(config)`
87
88Creates an isomorphic tool definition that can be instantiated for server or client execution.
89
90```typescript
91import { toolDefinition } from "@tanstack/ai";
92import { z } from "zod";
93
94const myToolDef = toolDefinition({
95 name: "my_tool",
96 description: "Tool description",
97 inputSchema: z.object({
98 param: z.string(),
99 }),
100 outputSchema: z.object({
101 result: z.string(),
102 }),
103 needsApproval: false, // Optional
104});
105
106// Or create client implementation
107const myClientTool = myToolDef.client(async ({ param }) => {
108 // Client-side implementation
109 return { result: "..." };
110});
111
112// Use directly in chat() (server-side, no execute)
113chat({
114 adapter: openaiText("gpt-5.2"),
115 tools: [myToolDef],
116 messages: [{ role: "user", content: "..." }],
117});
118
119// Or create server implementation
120const myServerTool = myToolDef.server(async ({ param }) => {
121 // Server-side implementation
122 return { result: "..." };
123});
124
125// Use directly in chat() (server-side, no execute)
126chat({
127 adapter: openaiText("gpt-5.2"),
128 tools: [myServerTool],
129 messages: [{ role: "user", content: "..." }],
130});
131```
132
133### Parameters
134
135- `name` - Tool name (must be unique)
136- `description` - Tool description for the model
137- `inputSchema` - Zod schema for input validation
138- `outputSchema?` - Zod schema for output validation
139- `needsApproval?` - Whether tool requires user approval
140- `metadata?` - Additional metadata
141
142### Returns
143
144A `ToolDefinition` object with `.server()` and `.client()` methods for creating concrete implementations.
145
146## `toServerSentEventsStream(stream, abortController?)`
147
148Converts a stream to a ReadableStream in Server-Sent Events format.
149
150```typescript
151import { chat, toServerSentEventsStream } from "@tanstack/ai";
152import { openaiText } from "@tanstack/ai-openai";
153
154const stream = chat({
155 adapter: openaiText("gpt-5.2"),
156 messages: [...],
157});
158const readableStream = toServerSentEventsStream(stream);
159```
160
161### Parameters
162
163- `stream` - Async iterable of `StreamChunk`
164- `abortController?` - Optional AbortController to abort when stream is cancelled
165
166### Returns
167
168A `ReadableStream<Uint8Array>` in Server-Sent Events format. Each chunk is:
169- Prefixed with `"data: "`
170- Followed by `"\n\n"`
171- Stream ends with `"data: [DONE]\n\n"`
172
173## `toServerSentEventsResponse(stream, init?)`
174
175Converts a stream to an HTTP Response with proper SSE headers.
176
177```typescript
178import { chat, toServerSentEventsResponse } from "@tanstack/ai";
179import { openaiText } from "@tanstack/ai-openai";
180
181const stream = chat({
182 adapter: openaiText("gpt-5.2"),
183 messages: [...],
184});
185return toServerSentEventsResponse(stream);
186```
187
188### Parameters
189
190- `stream` - Async iterable of `StreamChunk`
191- `init?` - Optional ResponseInit options (including `abortController`)
192
193### Returns
194
195A `Response` object suitable for HTTP endpoints with SSE headers (`Content-Type: text/event-stream`, `Cache-Control: no-cache`, `Connection: keep-alive`).
196
197## `chatParamsFromRequest(req)`
198
199Reads an HTTP `Request`, parses its JSON body, and validates it against AG-UI `RunAgentInputSchema`. Returns parsed chat parameters ready to spread into `chat()`. On a malformed body, **throws a 400 `Response`** that frameworks like TanStack Start, SolidStart, Remix, and React Router 7 return to the client automatically.
200
201```typescript
202import { chat, chatParamsFromRequest, toServerSentEventsResponse } from "@tanstack/ai";
203import { openaiText } from "@tanstack/ai-openai";
204
205export async function POST(req: Request) {
206 const params = await chatParamsFromRequest(req);
207 const stream = chat({
208 adapter: openaiText("gpt-4o"),
209 messages: params.messages,
210 tools: serverTools,
211 });
212 return toServerSentEventsResponse(stream);
213}
214```
215
216### Parameters
217
218- `req` - An incoming `Request` whose JSON body conforms to AG-UI `RunAgentInput`
219
220### Returns
221
222A promise resolving to `{ messages, threadId, runId, parentRunId?, tools, forwardedProps, state, context }`.
223
224> **Framework note.** Next.js Route Handlers, SvelteKit, Hono, and raw Node do not auto-handle thrown `Response` objects. In those, wrap with try/catch or use `chatParamsFromRequestBody(await req.json())` directly.
225
226## `chatParamsFromRequestBody(body)`
227
228Lower-level variant of `chatParamsFromRequest` that validates an already-parsed body. Rejects with an `AGUIError` on malformed input. Use this when you need explicit error handling control.
229
230```typescript
231const body = await req.json();
232try {
233 const params = await chatParamsFromRequestBody(body);
234 // ...
235} catch (error) {
236 return new Response(error.message, { status: 400 });
237}
238```
239
240## `mergeAgentTools(serverTools, clientTools)`
241
242Merges a server-side tool registry with the AG-UI client-declared tools received in the request payload. Server tools win on name collision; client-only tools become no-execute stubs that the runtime dispatches via `ClientToolRequest` events.
243
244```typescript
245import { chat, chatParamsFromRequest, mergeAgentTools } from "@tanstack/ai";
246
247const params = await chatParamsFromRequest(req);
248const stream = chat({
249 adapter: openaiText("gpt-4o"),
250 messages: params.messages,
251 tools: mergeAgentTools(serverTools, params.tools),
252});
253```
254
255### Parameters
256
257- `serverTools` - The server's `toolDefinition().server(...)` registry, keyed by tool name
258- `clientTools` - The `tools` array from `chatParamsFromRequest`'s return value
259
260### Returns
261
262A merged tool record suitable for `chat({ tools })`.
263
264## `maxIterations(count)`
265
266Creates an agent loop strategy that limits iterations.
267
268```typescript
269import { chat, maxIterations } from "@tanstack/ai";
270import { openaiText } from "@tanstack/ai-openai";
271
272const stream = chat({
273 adapter: openaiText("gpt-5.2"),
274 messages: [...],
275 agentLoopStrategy: maxIterations(20),
276});
277```
278
279### Parameters
280
281- `count` - Maximum number of tool execution iterations
282
283### Returns
284
285An `AgentLoopStrategy` object.
286
287## Types
288
289### `ModelMessage`
290
291```typescript
292interface ModelMessage {
293 role: "user" | "assistant" | "system" | "tool";
294 content: string;
295 toolCallId?: string;
296}
297```
298
299### `StreamChunk`
300
301```typescript
302type StreamChunk =
303 | ContentStreamChunk
304 | ThinkingStreamChunk
305 | ToolCallStreamChunk
306 | ToolResultStreamChunk
307 | DoneStreamChunk
308 | ErrorStreamChunk;
309
310interface ThinkingStreamChunk {
311 type: "thinking";
312 id: string;
313 model: string;
314 timestamp: number;
315 delta?: string; // Incremental thinking token
316 content: string; // Accumulated thinking content
317}
318```
319
320Stream chunks represent different types of data in the stream:
321
322- **Content chunks** - Text content being generated
323- **Thinking chunks** - Model's reasoning process (when supported by the model)
324- **Tool call chunks** - When the model calls a tool
325- **Tool result chunks** - Results from tool execution
326- **Done chunks** - Stream completion
327- **Error chunks** - Stream errors
328
329### `Tool`
330
331```typescript
332interface Tool {
333 type: "function";
334 function: {
335 name: string;
336 description: string;
337 parameters: Record<string, any>;
338 };
339 execute?: (args: any) => Promise<any> | any;
340 needsApproval?: boolean;
341}
342```
343
344## Usage Examples
345
346```typescript
347import { chat, summarize, generateImage } from "@tanstack/ai";
348import {
349 openaiText,
350 openaiSummarize,
351 openaiImage,
352} from "@tanstack/ai-openai";
353
354// --- Streaming chat
355const stream = chat({
356 adapter: openaiText("gpt-5.2"),
357 messages: [{ role: "user", content: "Hello!" }],
358});
359
360// --- One-shot chat response (stream: false)
361const response = await chat({
362 adapter: openaiText("gpt-5.2"),
363 messages: [{ role: "user", content: "What's the capital of France?" }],
364 stream: false, // Returns a Promise<string> instead of AsyncIterable
365});
366
367// --- Structured response with outputSchema
368import { z } from "zod";
369const parsed = await chat({
370 adapter: openaiText("gpt-5.2"),
371 messages: [{ role: "user", content: "Summarize this text in JSON with keys 'summary' and 'keywords': ... " }],
372 outputSchema: z.object({
373 summary: z.string(),
374 keywords: z.array(z.string()),
375 }),
376});
377
378// --- Structured response with tools
379import { toolDefinition } from "@tanstack/ai";
380const weatherTool = toolDefinition({
381 name: "getWeather",
382 description: "Get the current weather for a city",
383 inputSchema: z.object({
384 city: z.string().meta({ description: "City name" }),
385 }),
386}).server(async ({ city }) => {
387 // Implementation that fetches weather info
388 return JSON.stringify({ temperature: 72, condition: "Sunny" });
389});
390
391const toolResult = await chat({
392 adapter: openaiText("gpt-5.2"),
393 messages: [
394 { role: "user", content: "What's the weather in Paris?" }
395 ],
396 tools: [weatherTool],
397 outputSchema: z.object({
398 answer: z.string(),
399 weather: z.object({
400 temperature: z.number(),
401 condition: z.string(),
402 }),
403 }),
404});
405
406// --- Summarization
407const summary = await summarize({
408 adapter: openaiSummarize("gpt-5.2"),
409 text: "Long text to summarize...",
410 maxLength: 100,
411});
412
413// --- Image generation
414const image = await generateImage({
415 adapter: openaiImage("dall-e-3"),
416 prompt: "A futuristic city skyline at sunset",
417 numberOfImages: 1,
418 size: "1024x1024",
419});
420```
421
422## Next Steps
423
424- [Getting Started](../getting-started/quick-start) - Learn the basics
425- [Tools Guide](../tools/tools) - Learn about tools
426- [Adapters](../adapters/openai) - Explore adapter options