@tanstack/ai-client

Framework-agnostic headless client for managing chat state and streaming.

Installation

npm install @tanstack/ai-client

npm install @tanstack/ai-client

ChatClient

The main client class for managing chat state.

typescript

import {
  ChatClient,
  clientTools,
  fetchServerSentEvents,
} from "@tanstack/ai-client";
import { myClientTool } from "./tools";

const client = new ChatClient({
  connection: fetchServerSentEvents("/api/chat"),
  initialMessages: [],
  tools: clientTools(myClientTool),
  onMessagesChange: (messages) => {
    console.log("Messages updated:", messages);
  },
});

import {
  ChatClient,
  clientTools,
  fetchServerSentEvents,
} from "@tanstack/ai-client";
import { myClientTool } from "./tools";

const client = new ChatClient({
  connection: fetchServerSentEvents("/api/chat"),
  initialMessages: [],
  tools: clientTools(myClientTool),
  onMessagesChange: (messages) => {
    console.log("Messages updated:", messages);
  },
});

Constructor Options

connection - Connection adapter for streaming
initialMessages? - Initial messages array
id? - Unique identifier for this chat instance
threadId? - Thread ID for AG-UI run correlation. Persists across sends; auto-generated if omitted
forwardedProps? - Arbitrary client-controlled JSON forwarded to the server in the AG-UI RunAgentInput.forwardedProps field
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
context? - Typed client-local runtime context passed to client tool implementations. This value is not serialized to the server
tools? - Registered .client() tool implementations. The client automatically executes matching tools when the model calls them
onResponse? - Callback when response is received
onChunk? - Callback when stream chunk is received
onFinish? - Callback when response finishes
onError? - Callback when error occurs
onMessagesChange? - Callback when messages change
onLoadingChange? - Callback when loading state changes
onErrorChange? - Callback when error state changes
streamProcessor? - Stream processing configuration

Methods

sendMessage(content: string)

Sends a user message and gets a response.

typescript

await client.sendMessage("Hello!");

await client.sendMessage("Hello!");

append(message: ModelMessage | UIMessage)

Appends a message to the conversation.

typescript

await client.append({
  role: "user",
  content: "Additional context",
});

await client.append({
  role: "user",
  content: "Additional context",
});

reload()

Reloads the last assistant message.

typescript

await client.reload();

await client.reload();

stop()

Stops the current response generation.

typescript

client.stop();

client.stop();

clear()

Clears all messages.

typescript

client.clear();

client.clear();

setMessagesManually(messages: UIMessage[])

Manually sets the messages array.

typescript

client.setMessagesManually([...newMessages]);

client.setMessagesManually([...newMessages]);

addToolResult(result)

Adds the result of a client-side tool execution.

typescript

await client.addToolResult({
  toolCallId: "call_123",
  tool: "toolName",
  output: { result: "..." },
  state: "output-available",
});

await client.addToolResult({
  toolCallId: "call_123",
  tool: "toolName",
  output: { result: "..." },
  state: "output-available",
});

addToolApprovalResponse(response)

Responds to a tool approval request.

typescript

await client.addToolApprovalResponse({
  id: "approval_123",
  approved: true,
});

await client.addToolApprovalResponse({
  id: "approval_123",
  approved: true,
});

Properties

messages: UIMessage[] - Current messages
isLoading: boolean - Whether a response is being generated
error: Error | undefined - Current error, if any

Connection Adapters

For a complete transport walkthrough, see Connection Adapters. For React Native and Expo, see Quick Start: React Native.

fetchServerSentEvents(url, options?)

Creates an SSE connection adapter.

typescript

import { fetchServerSentEvents } from "@tanstack/ai-client";

const adapter = fetchServerSentEvents("/api/chat", {
  headers: {
    Authorization: "Bearer token",
  },
});

import { fetchServerSentEvents } from "@tanstack/ai-client";

const adapter = fetchServerSentEvents("/api/chat", {
  headers: {
    Authorization: "Bearer token",
  },
});

fetchHttpStream(url, options?)

Creates a newline-delimited JSON HTTP stream connection adapter. Pair it with toHttpResponse() on the server.

typescript

import { fetchHttpStream } from "@tanstack/ai-client";

const adapter = fetchHttpStream("/api/chat");

import { fetchHttpStream } from "@tanstack/ai-client";

const adapter = fetchHttpStream("/api/chat");

fetchHttpStream() requires a runtime with streaming fetch, Response.body.getReader(), and TextDecoder. If the runtime cannot expose an incremental response body, it throws UnsupportedResponseStreamError; use the XHR adapters in React Native or Expo.

xhrHttpStream(url, options?)

Creates an XMLHttpRequest-backed newline-delimited JSON stream adapter. This is the recommended default for React Native and Expo chat screens. Pair it with toHttpResponse() on the server.

typescript

import { xhrHttpStream } from "@tanstack/ai-client";

const adapter = xhrHttpStream("http://192.168.1.10:8787/chat/http", {
  headers: { Authorization: "Bearer token" },
  withCredentials: true,
});

import { xhrHttpStream } from "@tanstack/ai-client";

const adapter = xhrHttpStream("http://192.168.1.10:8787/chat/http", {
  headers: { Authorization: "Bearer token" },
  withCredentials: true,
});

xhrServerSentEvents(url, options?)

Creates an XMLHttpRequest-backed SSE adapter for runtimes where XHR progress events are more reliable than streaming fetch. Pair it with toServerSentEventsResponse() on the server.

typescript

import { xhrServerSentEvents } from "@tanstack/ai-client";

const adapter = xhrServerSentEvents("http://192.168.1.10:8787/chat/sse");

import { xhrServerSentEvents } from "@tanstack/ai-client";

const adapter = xhrServerSentEvents("http://192.168.1.10:8787/chat/sse");

Adapter options

Fetch adapters accept:

headers?: Record<string, string> | Headers
credentials?: RequestCredentials
signal?: AbortSignal
body?: Record<string, any>
fetchClient?: typeof globalThis.fetch

XHR adapters accept:

headers?: Record<string, string> | Headers
withCredentials?: boolean
signal?: AbortSignal
body?: Record<string, any>
xhrFactory?: () => XMLHttpRequest

body is merged into the AG-UI forwardedProps payload. Values from forwardedProps on the client and per-message sendMessage(..., data) calls override static adapter body values.

Stream errors

UnsupportedResponseStreamError - thrown by fetch-based adapters when Response.body, Response.body.getReader(), or TextDecoder is missing.
StreamTruncatedError - thrown when an SSE or NDJSON stream ends with unterminated trailing data, usually because the server, proxy, or network cut the connection mid-line.

stream(connectFn)

Creates a custom connection adapter.

typescript

import { stream } from "@tanstack/ai-client";

const adapter = stream(async (messages, data, signal) => {
  // `data` here carries the merged forwardedProps. The fetch-based
  // adapters serialize it as the AG-UI `RunAgentInput.forwardedProps`
  // field on the wire (with a backward-compat `data` mirror).
  const response = await fetch("/api/chat", {
    method: "POST",
    body: JSON.stringify({ messages, forwardedProps: data }),
    signal,
  });
  return processStream(response);
});

import { stream } from "@tanstack/ai-client";

const adapter = stream(async (messages, data, signal) => {
  // `data` here carries the merged forwardedProps. The fetch-based
  // adapters serialize it as the AG-UI `RunAgentInput.forwardedProps`
  // field on the wire (with a backward-compat `data` mirror).
  const response = await fetch("/api/chat", {
    method: "POST",
    body: JSON.stringify({ messages, forwardedProps: data }),
    signal,
  });
  return processStream(response);
});

Helper Functions

clientTools(...tools)

Creates 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.

typescript

import { clientTools } from "@tanstack/ai-client";
import { myTool1, myTool2 } from "./tools";

// Create client implementations
const tool1Client = myTool1.client((input) => {
  // Implementation
  return { result: "..." };
});

const tool2Client = myTool2.client((input) => {
  // Implementation
  return { result: "..." };
});

// Create typed tools array (no 'as const' needed!)
const tools = clientTools(tool1Client, tool2Client);

// Now when you use these tools in chat options:
const chatOptions = createChatClientOptions({
  connection: fetchServerSentEvents("/api/chat"),
  tools, // Fully typed with literal tool names
});

// In your component:
messages.forEach((message) => {
  message.parts.forEach((part) => {
    if (part.type === "tool-call" && part.name === "myTool1") {
      // ✅ TypeScript knows part.name is literally "myTool1"
      // ✅ part.input is typed from myTool1's input schema
      // ✅ part.output is typed from myTool1's output schema
    }
  });
});

import { clientTools } from "@tanstack/ai-client";
import { myTool1, myTool2 } from "./tools";

// Create client implementations
const tool1Client = myTool1.client((input) => {
  // Implementation
  return { result: "..." };
});

const tool2Client = myTool2.client((input) => {
  // Implementation
  return { result: "..." };
});

// Create typed tools array (no 'as const' needed!)
const tools = clientTools(tool1Client, tool2Client);

// Now when you use these tools in chat options:
const chatOptions = createChatClientOptions({
  connection: fetchServerSentEvents("/api/chat"),
  tools, // Fully typed with literal tool names
});

// In your component:
messages.forEach((message) => {
  message.parts.forEach((part) => {
    if (part.type === "tool-call" && part.name === "myTool1") {
      // ✅ TypeScript knows part.name is literally "myTool1"
      // ✅ part.input is typed from myTool1's input schema
      // ✅ part.output is typed from myTool1's output schema
    }
  });
});

createChatClientOptions(options)

Helper function to create typed chat client options with proper type inference.

typescript

import { createChatClientOptions, clientTools } from "@tanstack/ai-client";

const tools = clientTools(tool1, tool2);

const chatOptions = createChatClientOptions({
  connection: fetchServerSentEvents("/api/chat"),
  tools,
});

// Use InferChatMessages to extract message types
type ChatMessages = InferChatMessages<typeof chatOptions>;

import { createChatClientOptions, clientTools } from "@tanstack/ai-client";

const tools = clientTools(tool1, tool2);

const chatOptions = createChatClientOptions({
  connection: fetchServerSentEvents("/api/chat"),
  tools,
});

// Use InferChatMessages to extract message types
type ChatMessages = InferChatMessages<typeof chatOptions>;

createChatClientOptions also preserves typed client runtime context:

typescript

type ClientContext = {
  activeProjectId: string;
};

const tool = projectTool.client<ClientContext>((input, ctx) => {
  return runProjectAction(ctx.context.activeProjectId, input);
});

const chatOptions = createChatClientOptions({
  connection: fetchServerSentEvents("/api/chat"),
  tools: clientTools(tool),
  context: {
    activeProjectId: "project_123",
  },
});

type ClientContext = {
  activeProjectId: string;
};

const tool = projectTool.client<ClientContext>((input, ctx) => {
  return runProjectAction(ctx.context.activeProjectId, input);
});

const chatOptions = createChatClientOptions({
  connection: fetchServerSentEvents("/api/chat"),
  tools: clientTools(tool),
  context: {
    activeProjectId: "project_123",
  },
});

Client runtime context is local to the client instance. Use forwardedProps for explicit client-to-server handoff of serializable values, then validate and map those values into server chat({ context }).

Types

UIMessage

typescript

interface UIMessage {
  id: string;
  role: "user" | "assistant";
  parts: MessagePart[];
  createdAt?: Date;
}

interface UIMessage {
  id: string;
  role: "user" | "assistant";
  parts: MessagePart[];
  createdAt?: Date;
}

MessagePart

typescript

type MessagePart = TextPart | ThinkingPart | ToolCallPart | ToolResultPart;

type MessagePart = TextPart | ThinkingPart | ToolCallPart | ToolResultPart;

TextPart

typescript

interface TextPart {
  type: "text";
  content: string;
}

interface TextPart {
  type: "text";
  content: string;
}

ThinkingPart

typescript

interface ThinkingPart {
  type: "thinking";
  content: string;
}

interface ThinkingPart {
  type: "thinking";
  content: string;
}

Thinking 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.

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).

ToolCallPart

typescript

interface ToolCallPart {
  type: "tool-call";
  id: string;
  name: string;
  arguments: string; // JSON string (may be incomplete during streaming)
  input?: any; // Parsed tool input (typed from tool's inputSchema)
  state: ToolCallState;
  approval?: ApprovalRequest;
  output?: any; // Tool execution output (typed from tool's outputSchema)
}

interface ToolCallPart {
  type: "tool-call";
  id: string;
  name: string;
  arguments: string; // JSON string (may be incomplete during streaming)
  input?: any; // Parsed tool input (typed from tool's inputSchema)
  state: ToolCallState;
  approval?: ApprovalRequest;
  output?: any; // Tool execution output (typed from tool's outputSchema)
}

When 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.

ToolResultPart

typescript

interface ToolResultPart {
  type: "tool-result";
  toolCallId: string;
  content: string;
  state: ToolResultState;
  error?: string;
}

interface ToolResultPart {
  type: "tool-result";
  toolCallId: string;
  content: string;
  state: ToolResultState;
  error?: string;
}

ToolCallState

typescript

type ToolCallState =
  | "awaiting-input"
  | "input-streaming"
  | "input-complete"
  | "approval-requested"
  | "approval-responded"
  | "complete";

type ToolCallState =
  | "awaiting-input"
  | "input-streaming"
  | "input-complete"
  | "approval-requested"
  | "approval-responded"
  | "complete";

ToolResultState

typescript

type ToolResultState =
  | "streaming"
  | "complete"
  | "error";

type ToolResultState =
  | "streaming"
  | "complete"
  | "error";

Stream Processing

Configure stream processing with chunk strategies:

typescript

import { ImmediateStrategy, fetchServerSentEvents } from "@tanstack/ai-client";

const client = new ChatClient({
  connection: fetchServerSentEvents("/api/chat"),
  streamProcessor: {
    chunkStrategy: new ImmediateStrategy(), // Emit every chunk
  },
});

import { ImmediateStrategy, fetchServerSentEvents } from "@tanstack/ai-client";

const client = new ChatClient({
  connection: fetchServerSentEvents("/api/chat"),
  streamProcessor: {
    chunkStrategy: new ImmediateStrategy(), // Emit every chunk
  },
});

Next Steps

Getting Started - Learn the basics
Connection Adapters - Learn about adapters
@tanstack/ai-react API - React hooks wrapper

Installation#

ChatClient#

Constructor Options#

Methods#

sendMessage(content: string)#

append(message: ModelMessage | UIMessage)#

reload()#

stop()#

clear()#

setMessagesManually(messages: UIMessage[])#

addToolResult(result)#

addToolApprovalResponse(response)#

Properties#

Connection Adapters#

fetchServerSentEvents(url, options?)#

fetchHttpStream(url, options?)#

xhrHttpStream(url, options?)#

xhrServerSentEvents(url, options?)#

Adapter options#

Stream errors#

stream(connectFn)#

Helper Functions#

clientTools(...tools)#

createChatClientOptions(options)#

Types#

UIMessage#

MessagePart#

TextPart#

ThinkingPart#

ToolCallPart#

ToolResultPart#

ToolCallState#

ToolResultState#

Stream Processing#

Next Steps#

Installation

ChatClient

Constructor Options

Methods

sendMessage(content: string)

append(message: ModelMessage | UIMessage)

reload()

stop()

clear()

setMessagesManually(messages: UIMessage[])

addToolResult(result)

addToolApprovalResponse(response)

Properties

Connection Adapters

fetchServerSentEvents(url, options?)

fetchHttpStream(url, options?)

xhrHttpStream(url, options?)

xhrServerSentEvents(url, options?)

Adapter options

Stream errors

stream(connectFn)

Helper Functions

clientTools(...tools)

createChatClientOptions(options)

Types

UIMessage

MessagePart

TextPart

ThinkingPart

ToolCallPart

ToolResultPart

ToolCallState

ToolResultState

Stream Processing

Next Steps