Open History to see the last commit
1---
2title: "@tanstack/ai-client"
3slug: /api/ai-client
4order: 2
5description: "API reference for @tanstack/ai-client — the framework-agnostic headless client for managing chat state and streaming transports."
6keywords:
7 - tanstack ai
8 - "@tanstack/ai-client"
9 - headless client
10 - ChatClient
11 - chat state
12 - connection adapters
13 - api reference
14---
15
16Framework-agnostic headless client for managing chat state and streaming.
17
18## Installation
19
20```bash
21npm install @tanstack/ai-client
22```
23
24## `ChatClient`
25
26The main client class for managing chat state.
27
28```typescript
29import { ChatClient, fetchServerSentEvents } from "@tanstack/ai-client";
30
31const client = new ChatClient({
32 connection: fetchServerSentEvents("/api/chat"),
33 initialMessages: [],
34 onMessagesChange: (messages) => {
35 console.log("Messages updated:", messages);
36 },
37 onToolCall: async ({ toolName, input }) => {
38 // Handle client tool execution
39 return { result: "..." };
40 },
41});
42```
43
44### Constructor Options
45
46- `connection` - Connection adapter for streaming
47- `initialMessages?` - Initial messages array
48- `id?` - Unique identifier for this chat instance
49- `threadId?` - Thread ID for AG-UI run correlation. Persists across sends; auto-generated if omitted
50- `forwardedProps?` - Arbitrary client-controlled JSON forwarded to the server in the AG-UI `RunAgentInput.forwardedProps` field
51- `body?` - **Deprecated.** Use `forwardedProps` instead. Still works — values are merged into `forwardedProps` on the wire and mirrored under the legacy `data` field for backward compatibility
52- `onResponse?` - Callback when response is received
53- `onChunk?` - Callback when stream chunk is received
54- `onFinish?` - Callback when response finishes
55- `onError?` - Callback when error occurs
56- `onMessagesChange?` - Callback when messages change
57- `onLoadingChange?` - Callback when loading state changes
58- `onErrorChange?` - Callback when error state changes
59- `onToolCall?` - Callback for client-side tool execution
60- `streamProcessor?` - Stream processing configuration
61
62### Methods
63
64#### `sendMessage(content: string)`
65
66Sends a user message and gets a response.
67
68```typescript
69await client.sendMessage("Hello!");
70```
71
72#### `append(message: ModelMessage | UIMessage)`
73
74Appends a message to the conversation.
75
76```typescript
77await client.append({
78 role: "user",
79 content: "Additional context",
80});
81```
82
83#### `reload()`
84
85Reloads the last assistant message.
86
87```typescript
88await client.reload();
89```
90
91#### `stop()`
92
93Stops the current response generation.
94
95```typescript
96client.stop();
97```
98
99#### `clear()`
100
101Clears all messages.
102
103```typescript
104client.clear();
105```
106
107#### `setMessagesManually(messages: UIMessage[])`
108
109Manually sets the messages array.
110
111```typescript
112client.setMessagesManually([...newMessages]);
113```
114
115#### `addToolResult(result)`
116
117Adds the result of a client-side tool execution.
118
119```typescript
120await client.addToolResult({
121 toolCallId: "call_123",
122 tool: "toolName",
123 output: { result: "..." },
124 state: "output-available",
125});
126```
127
128#### `addToolApprovalResponse(response)`
129
130Responds to a tool approval request.
131
132```typescript
133await client.addToolApprovalResponse({
134 id: "approval_123",
135 approved: true,
136});
137```
138
139### Properties
140
141- `messages: UIMessage[]` - Current messages
142- `isLoading: boolean` - Whether a response is being generated
143- `error: Error | undefined` - Current error, if any
144
145## Connection Adapters
146
147### `fetchServerSentEvents(url, options?)`
148
149Creates an SSE connection adapter.
150
151```typescript
152import { fetchServerSentEvents } from "@tanstack/ai-client";
153
154const adapter = fetchServerSentEvents("/api/chat", {
155 headers: {
156 Authorization: "Bearer token",
157 },
158});
159```
160
161### `fetchHttpStream(url, options?)`
162
163Creates an HTTP stream connection adapter.
164
165```typescript
166import { fetchHttpStream } from "@tanstack/ai-client";
167
168const adapter = fetchHttpStream("/api/chat");
169```
170
171### `stream(connectFn)`
172
173Creates a custom connection adapter.
174
175```typescript
176import { stream } from "@tanstack/ai-client";
177
178const adapter = stream(async (messages, data, signal) => {
179 // `data` here carries the merged forwardedProps. The fetch-based
180 // adapters serialize it as the AG-UI `RunAgentInput.forwardedProps`
181 // field on the wire (with a backward-compat `data` mirror).
182 const response = await fetch("/api/chat", {
183 method: "POST",
184 body: JSON.stringify({ messages, forwardedProps: data }),
185 signal,
186 });
187 return processStream(response);
188});
189```
190
191## Helper Functions
192
193### `clientTools(...tools)`
194
195Creates a typed array of client tools with proper type inference. This eliminates the need for `as const` when defining tool arrays and enables proper discriminated union type narrowing.
196
197```typescript
198import { clientTools } from "@tanstack/ai-client";
199import { myTool1, myTool2 } from "./tools";
200
201// Create client implementations
202const tool1Client = myTool1.client((input) => {
203 // Implementation
204 return { result: "..." };
205});
206
207const tool2Client = myTool2.client((input) => {
208 // Implementation
209 return { result: "..." };
210});
211
212// Create typed tools array (no 'as const' needed!)
213const tools = clientTools(tool1Client, tool2Client);
214
215// Now when you use these tools in chat options:
216const chatOptions = createChatClientOptions({
217 connection: fetchServerSentEvents("/api/chat"),
218 tools, // Fully typed with literal tool names
219});
220
221// In your component:
222messages.forEach((message) => {
223 message.parts.forEach((part) => {
224 if (part.type === "tool-call" && part.name === "myTool1") {
225 // ✅ TypeScript knows part.name is literally "myTool1"
226 // ✅ part.input is typed from myTool1's input schema
227 // ✅ part.output is typed from myTool1's output schema
228 }
229 });
230});
231```
232
233### `createChatClientOptions(options)`
234
235Helper function to create typed chat client options with proper type inference.
236
237```typescript
238import { createChatClientOptions, clientTools } from "@tanstack/ai-client";
239
240const tools = clientTools(tool1, tool2);
241
242const chatOptions = createChatClientOptions({
243 connection: fetchServerSentEvents("/api/chat"),
244 tools,
245});
246
247// Use InferChatMessages to extract message types
248type ChatMessages = InferChatMessages<typeof chatOptions>;
249```
250
251## Types
252
253### `UIMessage`
254
255```typescript
256interface UIMessage {
257 id: string;
258 role: "user" | "assistant";
259 parts: MessagePart[];
260 createdAt?: Date;
261}
262```
263
264### `MessagePart`
265
266```typescript
267type MessagePart = TextPart | ThinkingPart | ToolCallPart | ToolResultPart;
268```
269
270### `TextPart`
271
272```typescript
273interface TextPart {
274 type: "text";
275 content: string;
276}
277```
278
279### `ThinkingPart`
280
281```typescript
282interface ThinkingPart {
283 type: "thinking";
284 content: string;
285}
286```
287
288Thinking parts represent the model's internal reasoning process. They are typically displayed in a collapsible format and automatically collapse when the response text appears. Thinking parts are UI-only and are not sent back to the model in subsequent requests.
289
290**Note:** Thinking parts are only available when using models that support reasoning/thinking (e.g., Anthropic Claude with thinking enabled, OpenAI GPT-5 with reasoning enabled).
291
292### `ToolCallPart`
293
294```typescript
295interface ToolCallPart {
296 type: "tool-call";
297 id: string;
298 name: string;
299 arguments: string; // JSON string (may be incomplete during streaming)
300 input?: any; // Parsed tool input (typed from tool's inputSchema)
301 state: ToolCallState;
302 approval?: ApprovalRequest;
303 output?: any; // Tool execution output (typed from tool's outputSchema)
304}
305```
306
307When using typed tools with `clientTools()` and `createChatClientOptions()`, the `input` and `output` fields are automatically typed based on your tool's Zod schemas, and `name` becomes a discriminated union enabling type narrowing.
308
309### `ToolResultPart`
310
311```typescript
312interface ToolResultPart {
313 type: "tool-result";
314 id: string;
315 toolCallId: string;
316 tool: string;
317 output: any;
318 state: ToolResultState;
319 errorText?: string;
320}
321```
322
323### `ToolCallState`
324
325```typescript
326type ToolCallState =
327 | "pending"
328 | "approval-requested"
329 | "executing"
330 | "output-available"
331 | "output-error"
332 | "cancelled";
333```
334
335### `ToolResultState`
336
337```typescript
338type ToolResultState =
339 | "pending"
340 | "executing"
341 | "output-available"
342 | "output-error";
343```
344
345## Stream Processing
346
347Configure stream processing with chunk strategies:
348
349```typescript
350import { ImmediateStrategy, fetchServerSentEvents } from "@tanstack/ai-client";
351
352const client = new ChatClient({
353 connection: fetchServerSentEvents("/api/chat"),
354 streamProcessor: {
355 chunkStrategy: new ImmediateStrategy(), // Emit every chunk
356 },
357});
358```
359
360## Next Steps
361
362- [Getting Started](../getting-started/quick-start) - Learn the basics
363- [Connection Adapters](../chat/connection-adapters) - Learn about adapters
364- [@tanstack/ai-react API](./ai-react) - React hooks wrapper