Skip to content
Source
Sign inSign up
TanStack/ai
Open History to see the last commit

ai-client.md

364 lines8.6 KB

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;
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;
277```
278​
279### `ThinkingPart`
280​
281```typescript
282interface ThinkingPart {
283 type: "thinking";
284 content: string;
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)
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;
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