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

ai-client.md

351 lines7.8 KB

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;
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;
264```
265​
266### `ThinkingPart`
267​
268```typescript
269interface ThinkingPart {
270 type: "thinking";
271 content: string;
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)
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;
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