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, maxIterations } from "@tanstack/ai";
30import { openaiText } from "@tanstack/ai-openai";
31import { myTool } from "./tools";
32
33const stream = chat({
34 adapter: openaiText("gpt-5.2"),
35 messages: [{ role: "user", content: "Hello!" }],
36 tools: [myTool],
37 systemPrompts: ["You are a helpful assistant"],
38 agentLoopStrategy: maxIterations(20),
39});
40```
41
42### Parameters
43
44- `adapter` - An AI adapter instance with model (e.g., `openaiText('gpt-5.2')`, `anthropicText('claude-sonnet-4-5')`)
45- `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`
46- `tools?` - Array of tools for function calling
47- `context?` - Typed runtime context passed to server tools and middleware. If a tool or middleware declares a concrete context type, `chat()` requires a compatible value here
48- `systemPrompts?` - System prompts to prepend to messages
49- `agentLoopStrategy?` - Strategy for agent loops (default: `maxIterations(5)`). Strategies receive `{ iterationCount, finishReason, messages, toolCallCount, lastTurnToolCallCount }` and run between model turns. Iterations are model turns, not tool calls — for tool-call budgets use middleware (`onBeforeToolCall` + `onShouldContinue`); see [Tool-call budgets](../chat/agentic-cycle#tool-call-budgets-middleware-recipe).
50- `middleware?` - Array of chat middleware. Use `onShouldContinue` / `onBeforeToolCall` for app-owned tool budgets.
51- `abortController?` - AbortController for cancellation
52- `modelOptions?` - Provider-native model options. This is where sampling parameters live — `temperature`, `top_p`/`topP`, and the provider's token-limit key (`max_output_tokens`, `max_tokens`, `maxOutputTokens`, …) — under each provider's canonical name, rather than as generic root-level props. See [Moving Sampling Options into modelOptions](../migration/sampling-options-to-model-options). (Renamed from `providerOptions`.)
53- `threadId?` - AG-UI thread identifier propagated into `RUN_STARTED` events for run correlation
54- `runId?` - AG-UI run identifier (auto-generated if omitted)
55- `parentRunId?` - AG-UI parent run identifier for nested runs
56
57### Returns
58
59An async iterable of `StreamChunk`.
60
61## `summarize(options)`
62
63Creates a text summarization.
64
65```typescript
66import { summarize } from "@tanstack/ai";
67import { openaiSummarize } from "@tanstack/ai-openai";
68
69const result = await summarize({
70 adapter: openaiSummarize("gpt-5.2"),
71 text: "Long text to summarize...",
72 maxLength: 100,
73 style: "concise",
74});
75```
76
77### Parameters
78
79- `adapter` - An AI adapter instance with model
80- `text` - Text to summarize
81- `maxLength?` - Maximum length of summary
82- `style?` - Summary style ("concise" | "detailed")
83- `modelOptions?` - Model-specific options
84
85### Returns
86
87A `SummarizationResult` with the summary text.
88
89## `toolDefinition(config)`
90
91Creates an isomorphic tool definition that can be instantiated for server or client execution.
92
93```typescript
94import { chat, toolDefinition } from "@tanstack/ai";
95import { openaiText } from "@tanstack/ai-openai";
96import { z } from "zod";
97
98const myToolDef = toolDefinition({
99 name: "my_tool",
100 description: "Tool description",
101 inputSchema: z.object({
102 param: z.string(),
103 }),
104 outputSchema: z.object({
105 result: z.string(),
106 }),
107 needsApproval: false, // Optional
108});
109
110// Or create client implementation
111const myClientTool = myToolDef.client(async ({ param }) => {
112 // Client-side implementation
113 return { result: "..." };
114});
115
116// Use directly in chat() (server-side, no execute)
117chat({
118 adapter: openaiText("gpt-5.2"),
119 tools: [myToolDef],
120 messages: [{ role: "user", content: "..." }],
121});
122
123// Or create server implementation
124const myServerTool = myToolDef.server(async ({ param }) => {
125 // Server-side implementation
126 return { result: "..." };
127});
128
129// Use directly in chat() (server-side, no execute)
130chat({
131 adapter: openaiText("gpt-5.2"),
132 tools: [myServerTool],
133 messages: [{ role: "user", content: "..." }],
134});
135```
136
137Tools can declare typed runtime context for request-scoped dependencies:
138
139```typescript
140import { chat, toolDefinition, toServerSentEventsResponse } from "@tanstack/ai";
141import { openaiText } from "@tanstack/ai-openai";
142import { session, db } from "./app";
143
144type AppContext = {
145 userId: string;
146 db: { users: { findName(id: string): Promise<string> } };
147};
148
149const currentUser = toolDefinition({
150 name: "current_user",
151 description: "Get the current user",
152}).server<AppContext>(async (_input: unknown, ctx) => {
153 return { name: await ctx.context.db.users.findName(ctx.context.userId) };
154});
155
156export async function POST(request: Request) {
157 const { messages } = await request.json();
158 const stream = chat({
159 adapter: openaiText("gpt-5.2"),
160 messages,
161 tools: [currentUser],
162 context: { userId: session.user.id, db },
163 });
164 return toServerSentEventsResponse(stream);
165}
166```
167
168### Parameters
169
170- `name` - Tool name (must be unique)
171- `description` - Tool description for the model
172- `inputSchema` - Zod schema for input validation
173- `outputSchema?` - Zod schema for output validation
174- `needsApproval?` - Whether tool requires user approval
175- `metadata?` - Additional metadata
176
177### Returns
178
179A `ToolDefinition` object with `.server()` and `.client()` methods for creating concrete implementations.
180
181## `toServerSentEventsStream(stream, abortController?)`
182
183Converts a stream to a ReadableStream in Server-Sent Events format.
184
185```typescript
186import { chat, toServerSentEventsStream } from "@tanstack/ai";
187import { openaiText } from "@tanstack/ai-openai";
188
189const stream = chat({
190 adapter: openaiText("gpt-5.2"),
191 messages: [{ role: "user", content: "Hello!" }],
192});
193const readableStream = toServerSentEventsStream(stream);
194```
195
196### Parameters
197
198- `stream` - Async iterable of `StreamChunk`
199- `abortController?` - Optional AbortController to abort when stream is cancelled
200
201### Returns
202
203A `ReadableStream<Uint8Array>` in Server-Sent Events format. Each chunk is:
204- Prefixed with `"data: "`
205- Followed by `"\n\n"`
206- Stream ends with `"data: [DONE]\n\n"`
207
208## `toServerSentEventsResponse(stream, init?)`
209
210Converts a stream to an HTTP Response with proper SSE headers.
211
212```typescript
213import { chat, toServerSentEventsResponse } from "@tanstack/ai";
214import { openaiText } from "@tanstack/ai-openai";
215
216async function POST() {
217 const stream = chat({
218 adapter: openaiText("gpt-5.2"),
219 messages: [{ role: "user", content: "Hello!" }],
220 });
221 return toServerSentEventsResponse(stream);
222}
223```
224
225### Parameters
226
227- `stream` - Async iterable of `StreamChunk`
228- `init?` - Optional ResponseInit options (including `abortController`)
229
230### Returns
231
232A `Response` object suitable for HTTP endpoints with SSE headers (`Content-Type: text/event-stream`, `Cache-Control: no-cache`, `Connection: keep-alive`).
233
234## `chatParamsFromRequest(req)`
235
236Reads 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.
237
238```typescript
239import { chat, chatParamsFromRequest, toServerSentEventsResponse } from "@tanstack/ai";
240import { openaiText } from "@tanstack/ai-openai";
241import { serverTools } from "./tools";
242
243export async function POST(req: Request) {
244 const params = await chatParamsFromRequest(req);
245 const stream = chat({
246 adapter: openaiText("gpt-5.5"),
247 messages: params.messages,
248 tools: serverTools,
249 });
250 return toServerSentEventsResponse(stream);
251}
252```
253
254### Parameters
255
256- `req` - An incoming `Request` whose JSON body conforms to AG-UI `RunAgentInput`
257
258### Returns
259
260A promise resolving to `{ messages, threadId, runId, parentRunId?, tools, forwardedProps, state, aguiContext, context }`.
261
262The returned `aguiContext` is the AG-UI protocol `RunAgentInput.context` field. It is not the same as TanStack AI runtime `chat({ context })`; validate and map it explicitly if you want those values available to tools or middleware.
263
264The returned `context` field is a deprecated alias of `aguiContext` kept for backward compatibility. Prefer `aguiContext` in new code.
265
266> **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.
267
268## `chatParamsFromRequestBody(body)`
269
270Lower-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.
271
272```typescript
273import { chatParamsFromRequestBody } from "@tanstack/ai";
274
275async function handler(req: Request): Promise<Response> {
276 const body = await req.json();
277 try {
278 const params = await chatParamsFromRequestBody(body);
279 // ...
280 return new Response("ok");
281 } catch (error) {
282 const message = error instanceof Error ? error.message : String(error);
283 return new Response(message, { status: 400 });
284 }
285}
286```
287
288## `mergeAgentTools(serverTools, clientTools)`
289
290Merges 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.
291
292```typescript
293import { chat, chatParamsFromRequest, mergeAgentTools } from "@tanstack/ai";
294import { openaiText } from "@tanstack/ai-openai";
295import { serverTools } from "./tools";
296
297async function handler(req: Request) {
298 const params = await chatParamsFromRequest(req);
299 const stream = chat({
300 adapter: openaiText("gpt-5.5"),
301 messages: params.messages,
302 tools: mergeAgentTools(serverTools, params.tools),
303 });
304}
305```
306
307### Parameters
308
309- `serverTools` - The server's `toolDefinition().server(...)` registry, keyed by tool name
310- `clientTools` - The `tools` array from `chatParamsFromRequest`'s return value
311
312### Returns
313
314A merged tool record suitable for `chat({ tools })`.
315
316## `maxIterations(count)`
317
318Creates an agent loop strategy that limits **model turns** (iterations), not tool calls. One turn can still emit many parallel tool calls — use middleware for tool-call budgets ([recipe](../chat/agentic-cycle#tool-call-budgets-middleware-recipe)).
319
320```typescript
321import { chat, maxIterations } from "@tanstack/ai";
322import { openaiText } from "@tanstack/ai-openai";
323
324const stream = chat({
325 adapter: openaiText("gpt-5.2"),
326 messages: [{ role: "user", content: "Hello!" }],
327 agentLoopStrategy: maxIterations(20),
328});
329```
330
331### Parameters
332
333- `count` - Maximum number of model turns
334
335### Returns
336
337An `AgentLoopStrategy` function.
338
339## Types
340
341### `ModelMessage`
342
343```typescript
344interface ModelMessage {
345 role: "user" | "assistant" | "system" | "tool";
346 content: string;
347 toolCallId?: string;
348}
349```
350
351### `StreamChunk`
352
353```typescript ignore
354type StreamChunk =
355 | ContentStreamChunk
356 | ThinkingStreamChunk
357 | ToolCallStreamChunk
358 | ToolResultStreamChunk
359 | DoneStreamChunk
360 | ErrorStreamChunk;
361
362interface ThinkingStreamChunk {
363 type: "thinking";
364 id: string;
365 model: string;
366 timestamp: number;
367 delta?: string; // Incremental thinking token
368 content: string; // Accumulated thinking content
369}
370```
371
372Stream chunks represent different types of data in the stream:
373
374- **Content chunks** - Text content being generated
375- **Thinking chunks** - Model's reasoning process (when supported by the model)
376- **Tool call chunks** - When the model calls a tool
377- **Tool result chunks** - Results from tool execution
378- **Done chunks** - Stream completion
379- **Error chunks** - Stream errors
380
381### `Tool`
382
383```typescript
384import type { SchemaInput, ToolExecutionContext } from "@tanstack/ai";
385
386interface Tool<TContext = unknown> {
387 name: string;
388 description: string;
389 inputSchema?: SchemaInput;
390 outputSchema?: SchemaInput;
391 execute?: (
392 args: any,
393 context?: ToolExecutionContext<TContext>
394 ) => Promise<any> | any;
395 needsApproval?: boolean;
396 lazy?: boolean;
397 metadata?: Record<string, any>;
398}
399```
400
401### `ToolExecutionContext<TContext>`
402
403```typescript ignore
404type ToolExecutionContext<TContext = unknown> = {
405 toolCallId?: string;
406 emitCustomEvent: (eventName: string, value: Record<string, any>) => void;
407} & (unknown extends TContext ? { context?: TContext } : { context: TContext });
408```
409
410`context` is the runtime value from `chat({ context })` for server tools, or from `ChatClient` / framework hook options for client tools. It is required when a tool declares a concrete `TContext` and optional for untyped tools where the context type is `unknown`.
411
412### `ChatMiddleware<TContext>`
413
414```typescript
415import type {
416 StreamChunk,
417 ChatMiddlewarePhase,
418 ToolCallHookContext,
419 BeforeToolCallDecision,
420 AfterToolCallInfo,
421 FinishInfo,
422 AbortInfo,
423 ErrorInfo,
424} from "@tanstack/ai";
425
426interface ChatMiddlewareContext<TContext = unknown> {
427 requestId: string;
428 streamId: string;
429 threadId: string;
430 phase: ChatMiddlewarePhase;
431 iteration: number;
432 context: TContext;
433 abort(reason?: string): void;
434 defer(promise: Promise<unknown>): void;
435}
436
437interface ChatMiddleware<TContext = unknown> {
438 name?: string;
439 onStart?: (ctx: ChatMiddlewareContext<TContext>) => void | Promise<void>;
440 onChunk?: (
441 ctx: ChatMiddlewareContext<TContext>,
442 chunk: StreamChunk
443 ) => void | StreamChunk | StreamChunk[] | null | Promise<void | StreamChunk | StreamChunk[] | null>;
444 onBeforeToolCall?: (
445 ctx: ChatMiddlewareContext<TContext>,
446 hookCtx: ToolCallHookContext
447 ) => BeforeToolCallDecision | Promise<BeforeToolCallDecision>;
448 onAfterToolCall?: (
449 ctx: ChatMiddlewareContext<TContext>,
450 info: AfterToolCallInfo
451 ) => void | Promise<void>;
452 onFinish?: (
453 ctx: ChatMiddlewareContext<TContext>,
454 info: FinishInfo
455 ) => void | Promise<void>;
456 onAbort?: (
457 ctx: ChatMiddlewareContext<TContext>,
458 info: AbortInfo
459 ) => void | Promise<void>;
460 onError?: (
461 ctx: ChatMiddlewareContext<TContext>,
462 info: ErrorInfo
463 ) => void | Promise<void>;
464}
465```
466
467See [Runtime Context](../advanced/runtime-context) for the recommended context patterns.
468
469## Usage Examples
470
471```typescript
472import { chat, summarize, generateImage, toolDefinition } from "@tanstack/ai";
473import {
474 openaiText,
475 openaiSummarize,
476 openaiImage,
477} from "@tanstack/ai-openai";
478import { z } from "zod";
479
480// --- Streaming chat
481const stream = chat({
482 adapter: openaiText("gpt-5.2"),
483 messages: [{ role: "user", content: "Hello!" }],
484});
485
486// --- Structured response with tools
487const weatherTool = toolDefinition({
488 name: "getWeather",
489 description: "Get the current weather for a city",
490 inputSchema: z.object({
491 city: z.string(),
492 }),
493}).server(async ({ city }) => {
494 // Implementation that fetches weather info
495 return JSON.stringify({ temperature: 72, condition: "Sunny" });
496});
497
498async function examples() {
499 // --- One-shot chat response (stream: false)
500 const response = await chat({
501 adapter: openaiText("gpt-5.2"),
502 messages: [{ role: "user", content: "What's the capital of France?" }],
503 stream: false, // Returns a Promise<string> instead of AsyncIterable
504 });
505
506 // --- Structured response with outputSchema
507 const parsed = await chat({
508 adapter: openaiText("gpt-5.2"),
509 messages: [{ role: "user", content: "Summarize this text in JSON with keys 'summary' and 'keywords': ... " }],
510 outputSchema: z.object({
511 summary: z.string(),
512 keywords: z.array(z.string()),
513 }),
514 });
515
516 const toolResult = await chat({
517 adapter: openaiText("gpt-5.2"),
518 messages: [
519 { role: "user", content: "What's the weather in Paris?" }
520 ],
521 tools: [weatherTool],
522 outputSchema: z.object({
523 answer: z.string(),
524 weather: z.object({
525 temperature: z.number(),
526 condition: z.string(),
527 }),
528 }),
529 });
530
531 // --- Summarization
532 const summary = await summarize({
533 adapter: openaiSummarize("gpt-5.2"),
534 text: "Long text to summarize...",
535 maxLength: 100,
536 });
537
538 // --- Image generation
539 const image = await generateImage({
540 adapter: openaiImage("dall-e-3"),
541 prompt: "A futuristic city skyline at sunset",
542 numberOfImages: 1,
543 size: "1024x1024",
544 });
545}
546```
547
548## Next Steps
549
550- [Getting Started](../getting-started/quick-start) - Learn the basics
551- [Tools Guide](../tools/tools) - Learn about tools
552- [Adapters](../adapters/openai) - Explore adapter options