Open History to see the last commit
1---
2title: "@tanstack/ai"
3id: tanstack-ai-api
4order: 1
5---
6
7The core AI library for TanStack AI.
8
9## Installation
10
11```bash
12npm install @tanstack/ai
13```
14
15## `chat(options)`
16
17Creates a streaming chat response.
18
19```typescript
20import { chat } from "@tanstack/ai";
21import { openaiText } from "@tanstack/ai-openai";
22
23const stream = chat({
24 adapter: openaiText("gpt-4o"),
25 messages: [{ role: "user", content: "Hello!" }],
26 tools: [myTool],
27 systemPrompts: ["You are a helpful assistant"],
28 agentLoopStrategy: maxIterations(20),
29});
30```
31
32### Parameters
33
34- `adapter` - An AI adapter instance with model (e.g., `openaiText('gpt-4o')`, `anthropicText('claude-sonnet-4-5')`)
35- `messages` - Array of chat messages
36- `tools?` - Array of tools for function calling
37- `systemPrompts?` - System prompts to prepend to messages
38- `agentLoopStrategy?` - Strategy for agent loops (default: `maxIterations(5)`)
39- `abortController?` - AbortController for cancellation
40- `modelOptions?` - Model-specific options (renamed from `providerOptions`)
41
42### Returns
43
44An async iterable of `StreamChunk`.
45
46## `summarize(options)`
47
48Creates a text summarization.
49
50```typescript
51import { summarize } from "@tanstack/ai";
52import { openaiSummarize } from "@tanstack/ai-openai";
53
54const result = await summarize({
55 adapter: openaiSummarize("gpt-4o"),
56 text: "Long text to summarize...",
57 maxLength: 100,
58 style: "concise",
59});
60```
61
62### Parameters
63
64- `adapter` - An AI adapter instance with model
65- `text` - Text to summarize
66- `maxLength?` - Maximum length of summary
67- `style?` - Summary style ("concise" | "detailed")
68- `modelOptions?` - Model-specific options
69
70### Returns
71
72A `SummarizationResult` with the summary text.
73
74## `toolDefinition(config)`
75
76Creates an isomorphic tool definition that can be instantiated for server or client execution.
77
78```typescript
79import { toolDefinition } from "@tanstack/ai";
80import { z } from "zod";
81
82const myToolDef = toolDefinition({
83 name: "my_tool",
84 description: "Tool description",
85 inputSchema: z.object({
86 param: z.string(),
87 }),
88 outputSchema: z.object({
89 result: z.string(),
90 }),
91 needsApproval: false, // Optional
92});
93
94// Or create client implementation
95const myClientTool = myToolDef.client(async ({ param }) => {
96 // Client-side implementation
97 return { result: "..." };
98});
99
100// Use directly in chat() (server-side, no execute)
101chat({
102 adapter: openaiText("gpt-4o"),
103 tools: [myToolDef],
104 messages: [{ role: "user", content: "..." }],
105});
106
107// Or create server implementation
108const myServerTool = myToolDef.server(async ({ param }) => {
109 // Server-side implementation
110 return { result: "..." };
111});
112
113// Use directly in chat() (server-side, no execute)
114chat({
115 adapter: openaiText("gpt-4o"),
116 tools: [myServerTool],
117 messages: [{ role: "user", content: "..." }],
118});
119```
120
121### Parameters
122
123- `name` - Tool name (must be unique)
124- `description` - Tool description for the model
125- `inputSchema` - Zod schema for input validation
126- `outputSchema?` - Zod schema for output validation
127- `needsApproval?` - Whether tool requires user approval
128- `metadata?` - Additional metadata
129
130### Returns
131
132A `ToolDefinition` object with `.server()` and `.client()` methods for creating concrete implementations.
133
134## `toServerSentEventsStream(stream, abortController?)`
135
136Converts a stream to a ReadableStream in Server-Sent Events format.
137
138```typescript
139import { chat, toServerSentEventsStream } from "@tanstack/ai";
140import { openaiText } from "@tanstack/ai-openai";
141
142const stream = chat({
143 adapter: openaiText("gpt-4o"),
144 messages: [...],
145});
146const readableStream = toServerSentEventsStream(stream);
147```
148
149### Parameters
150
151- `stream` - Async iterable of `StreamChunk`
152- `abortController?` - Optional AbortController to abort when stream is cancelled
153
154### Returns
155
156A `ReadableStream<Uint8Array>` in Server-Sent Events format. Each chunk is:
157- Prefixed with `"data: "`
158- Followed by `"\n\n"`
159- Stream ends with `"data: [DONE]\n\n"`
160
161## `toStreamResponse(stream, init?)`
162
163Converts a stream to an HTTP Response with proper SSE headers.
164
165```typescript
166import { chat, toStreamResponse } from "@tanstack/ai";
167import { openaiText } from "@tanstack/ai-openai";
168
169const stream = chat({
170 adapter: openaiText("gpt-4o"),
171 messages: [...],
172});
173return toStreamResponse(stream);
174```
175
176### Parameters
177
178- `stream` - Async iterable of `StreamChunk`
179- `init?` - Optional ResponseInit options (including `abortController`)
180
181### Returns
182
183A `Response` object suitable for HTTP endpoints with SSE headers (`Content-Type: text/event-stream`, `Cache-Control: no-cache`, `Connection: keep-alive`).
184
185## `maxIterations(count)`
186
187Creates an agent loop strategy that limits iterations.
188
189```typescript
190import { chat, maxIterations } from "@tanstack/ai";
191import { openaiText } from "@tanstack/ai-openai";
192
193const stream = chat({
194 adapter: openaiText("gpt-4o"),
195 messages: [...],
196 agentLoopStrategy: maxIterations(20),
197});
198```
199
200### Parameters
201
202- `count` - Maximum number of tool execution iterations
203
204### Returns
205
206An `AgentLoopStrategy` object.
207
208## Types
209
210### `ModelMessage`
211
212```typescript
213interface ModelMessage {
214 role: "user" | "assistant" | "system" | "tool";
215 content: string;
216 toolCallId?: string;
217}
218```
219
220### `StreamChunk`
221
222```typescript
223type StreamChunk =
224 | ContentStreamChunk
225 | ThinkingStreamChunk
226 | ToolCallStreamChunk
227 | ToolResultStreamChunk
228 | DoneStreamChunk
229 | ErrorStreamChunk;
230
231interface ThinkingStreamChunk {
232 type: "thinking";
233 id: string;
234 model: string;
235 timestamp: number;
236 delta?: string; // Incremental thinking token
237 content: string; // Accumulated thinking content
238}
239```
240
241Stream chunks represent different types of data in the stream:
242
243- **Content chunks** - Text content being generated
244- **Thinking chunks** - Model's reasoning process (when supported by the model)
245- **Tool call chunks** - When the model calls a tool
246- **Tool result chunks** - Results from tool execution
247- **Done chunks** - Stream completion
248- **Error chunks** - Stream errors
249
250### `Tool`
251
252```typescript
253interface Tool {
254 type: "function";
255 function: {
256 name: string;
257 description: string;
258 parameters: Record<string, any>;
259 };
260 execute?: (args: any) => Promise<any> | any;
261 needsApproval?: boolean;
262}
263```
264
265## Usage Examples
266
267```typescript
268import { chat, summarize, generateImage } from "@tanstack/ai";
269import {
270 openaiText,
271 openaiSummarize,
272 openaiImage,
273} from "@tanstack/ai-openai";
274
275// --- Streaming chat
276const stream = chat({
277 adapter: openaiText("gpt-4o"),
278 messages: [{ role: "user", content: "Hello!" }],
279});
280
281// --- One-shot chat response (stream: false)
282const response = await chat({
283 adapter: openaiText("gpt-4o"),
284 messages: [{ role: "user", content: "What's the capital of France?" }],
285 stream: false, // Returns a Promise<string> instead of AsyncIterable
286});
287
288// --- Structured response with outputSchema
289import { z } from "zod";
290const parsed = await chat({
291 adapter: openaiText("gpt-4o"),
292 messages: [{ role: "user", content: "Summarize this text in JSON with keys 'summary' and 'keywords': ... " }],
293 outputSchema: z.object({
294 summary: z.string(),
295 keywords: z.array(z.string()),
296 }),
297});
298
299// --- Structured response with tools
300import { toolDefinition } from "@tanstack/ai";
301const weatherTool = toolDefinition({
302 name: "getWeather",
303 description: "Get the current weather for a city",
304 inputSchema: z.object({
305 city: z.string().describe("City name"),
306 }),
307}).server(async ({ city }) => {
308 // Implementation that fetches weather info
309 return JSON.stringify({ temperature: 72, condition: "Sunny" });
310});
311
312const toolResult = await chat({
313 adapter: openaiText("gpt-4o"),
314 messages: [
315 { role: "user", content: "What's the weather in Paris?" }
316 ],
317 tools: [weatherTool],
318 outputSchema: z.object({
319 answer: z.string(),
320 weather: z.object({
321 temperature: z.number(),
322 condition: z.string(),
323 }),
324 }),
325});
326
327// --- Summarization
328const summary = await summarize({
329 adapter: openaiSummarize("gpt-4o"),
330 text: "Long text to summarize...",
331 maxLength: 100,
332});
333
334// --- Image generation
335const image = await generateImage({
336 adapter: openaiImage("dall-e-3"),
337 prompt: "A futuristic city skyline at sunset",
338 numberOfImages: 1,
339 size: "1024x1024",
340});
341```
342
343## Next Steps
344
345- [Getting Started](../getting-started/quick-start) - Learn the basics
346- [Tools Guide](../guides/tools) - Learn about tools
347- [Adapters](../adapters/openai) - Explore adapter options