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