@tanstack/ai-client

The headless client under every framework package. Use it directly for vanilla JavaScript or a custom binding. For typed chat UI types and selectors, import @tanstack/ai-client/ui and see Custom Chat UI Adapters.

Installation#

npm i @tanstack/ai-client

pnpm add @tanstack/ai-client

yarn add @tanstack/ai-client

bun add @tanstack/ai-client

ChatClient#

Holds the messages and the run state of one chat, and talks to your server route.

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

const client = new ChatClient({
  connection: fetchServerSentEvents("/api/chat"),
  threadId: "support-chat",
});

const unsubscribe = client.subscribeSnapshot(() => {
  const { messages, isLoading } = client.getSnapshot();
  console.log(messages.length, isLoading);
});

client.attach();
await client.sendMessage("Hello!");

Lifecycle: attach() and detach()#

A new client opens no connection. When your view appears, call attach(). When it goes away, call detach(). The framework hooks do this for you on mount and unmount.

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

const client = new ChatClient({
  connection: fetchServerSentEvents("/api/chat"),
  threadId: "thread-1",
  persistence: true,
});

client.attach(); // rejoin a run in progress, and load the thread
client.detach(); // drop the connection, keep the messages and the run pointer

The connection follows the view because a browser allows only about six connections to one origin. A chat that follows a run holds one connection for as long as the run lasts. If every chat on a page held one, the other requests wait behind them.

• attach() is safe to call more than once. A second call does nothing.
• detach() keeps the messages, the resume pointer, and the run id. The run goes on at the server, and a later attach() picks it up from the durable log.
• detach() does not end the run (that is stop()) or the client (that is dispose()).
• A chat with no persistence has nothing to rejoin, so attach() sends no request.

Constructor options#

You must pass threadId. You must also pass connection or fetcher, not both.

Callbacks:

Methods#

Read single values with getMessages(), getIsLoading(), getStatus(), getError(), getIsHydrating(), getIsSubscribed(), getConnectionStatus(), getSessionGenerating(), and getCurrentRunId().

sendMessage(content, body?, sendOptions?)#

content is a string or MultimodalContent: { content, id?, metadata? }. Use the object form to put metadata on the user UIMessage. TanStack writes the tanstack key in metadata. Your keys stay at the top level.

body and sendOptions.body are extra JSON for this request. They shallow-merge with the chat forwardedProps. On a key collision, sendOptions.body wins. sendOptions.whenBusy overrides the queue policy for this send.

The framework hooks expose sendMessage(content, sendOptions) with no positional body. Pass { body } there.

import { client } from "./client";

await client.sendMessage({
  content: "Summarize the attached files",
  metadata: { author: { id: "user-42", name: "Dana" } },
});

await client.sendMessage("Summarize the attached files", undefined, {
  body: { attachmentIds: ["att_1", "att_2"] },
  whenBusy: "interrupt",
});

On the server, read the merged JSON from chatParamsFromRequest:

import {
  chat,
  chatParamsFromRequest,
  toServerSentEventsResponse,
} from "@tanstack/ai";
import { openaiText } from "@tanstack/ai-openai";

export async function POST(request: Request) {
  const { messages, forwardedProps, threadId } = await chatParamsFromRequest(request);
  const attachmentIds = forwardedProps.attachmentIds;
  if (Array.isArray(attachmentIds)) {
    // Look up the uploads. Do not add them to `messages`.
  }
  const stream = chat({
    adapter: openaiText("gpt-6.1-sol"),
    messages,
    threadId,
  });
  return toServerSentEventsResponse(stream);
}

If append() starts the stream, it resolves after the full HTTP response is processed. If a stream is already in progress, the call queues the send, and the promise can resolve before the queued response is processed. A RUN_FINISHED with finishReason: "tool_calls" does not end the wait when the agent loop goes on in the same response.

append() copies metadata from a UIMessage onto the stored message.

After stop(), a later addToolResult() for the stopped turn is ignored. A new user message starts a new turn, and addToolResult() applies to that turn.

getSnapshot() and subscribeSnapshot(listener)#

The snapshot has messages, status, isLoading, error, queue, runId, isSubscribed, connectionStatus, sessionGenerating, hasOlderMessages, isHydrating, and interruptState.

• The snapshot, messages, queue, and their entries are frozen copies. messages.push throws. Use setMessagesManually.
• interruptState is not copied.
• subscribeSnapshot(listener) returns an unsubscribe function. It does not fire with the current value, so read getSnapshot() first.
• subscribeSnapshot is not subscribe(). subscribe() starts the live connection loop.

Connection adapters#

Each adapter pairs with a server response helper from @tanstack/ai. See Transports.

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

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

url can be a string or a function that returns one. options can be an object or a function that returns one per request.

Adapter options#

Fetch adapters take headers, credentials, signal, body, fetchClient, and reconnect.

XHR adapters take headers, withCredentials, signal, body, xhrFactory, and reconnect.

fetchJson() also takes pollIntervalMs (default 250). When a reply has done: false, it waits that long and sends GET ?runId=<id>&offset=<offset>. Serve that GET with resumeJsonResponse().

The adapter body merges into the AG-UI forwardedProps. The chat forwardedProps and the per-send body override it.

fetchHttpStream() needs streaming fetch, Response.body.getReader(), and TextDecoder. If the runtime has none of these, it throws UnsupportedResponseStreamError. Use the XHR adapters in React Native and Expo.

stream(factory)#

Builds a custom adapter from a function that returns AsyncIterable<StreamChunk>. The function gets (messages, data, abortSignal, input). data is the merged forwardedProps. input is the AG-UI RunAgentInput for the run, the same body the HTTP adapters send. Read it on the server with chatParamsFromRequestBody.

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

const connection = stream((_messages, _data, signal, input) =>
  chatOnServer({ input, signal }),
);

Stream errors#

• UnsupportedResponseStreamError: a fetch adapter found no Response.body, getReader(), or TextDecoder.
• StreamTruncatedError: an SSE or NDJSON stream ended in the middle of a line. A server, a proxy, or the network cut the connection.
• DurableStreamIncompleteError and StreamReconnectLimitError: a resumable stream did not finish. See Resumable Streams.

Persistence adapters#

Browser storage adapters for persistence. Each one keeps the messages and the resume state for a threadId. See Client Persistence.

They throw StorageUnavailableError when the browser storage is not available.

createChatClientOptions(options)#

Returns the options unchanged, with full type inference. Use it to define options outside a hook and to get the message type.

import {
  createChatClientOptions,
  fetchServerSentEvents,
  type InferChatMessages,
} from "@tanstack/ai-client";
import { searchProducts } from "./tools";

const chatOptions = createChatClientOptions({
  connection: fetchServerSentEvents("/api/chat"),
  threadId: "support-chat",
  tools: [searchProducts],
});

type ChatMessages = InferChatMessages<typeof chatOptions>;

A plain tools array keeps tool names, inputs, and outputs typed. You do not need as const. When you narrow with part.name === "searchProducts", part.input and part.output get their types from the schemas of that tool.

Client context stays typed too. If a .client<ClientContext>() tool needs context, context becomes required. It stays on the client. To send values to the server, use forwardedProps, then validate them and pass them to chat({ context }).

clientTools(...tools)#

Returns its arguments as a typed tuple. A plain array already gives the same types, so use this only to build a shared tools tuple outside the options call.

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

export const tools = clientTools(searchProducts, showToast);

GenerationClient#

Runs one generation request (image, audio, speech, transcription, summary, or your own type) and keeps its result. The framework generation hooks wrap it. See Generation Hooks.

import type { ImageGenerationResult } from "@tanstack/ai";
import {
  GenerationClient,
  fetchServerSentEvents,
  type ImageGenerateInput,
} from "@tanstack/ai-client";

const generation = new GenerationClient<ImageGenerateInput, ImageGenerationResult>({
  connection: fetchServerSentEvents("/api/generate/image"),
  threadId: "generation",
  onResult: (result) => console.log(result.images.length),
});

await generation.generate({ prompt: "A mountain at sunset" });

• Options: threadId (required), connection or fetcher, body, persistence, byok, byokProvider, devtools, onResult, onError, onProgress, onChunk.
• Methods: generate(input), stop(), reset(), updateOptions(options), dispose(), getResult(), getIsLoading(), getError(), getStatus().
• Snapshot: result, isLoading, error, status ("idle", "generating", "success", or "error"), and runId.

VideoGenerationClient does the same for video jobs. Its snapshot adds jobId and videoStatus, and it takes onJobCreated and onStatusUpdate.

RealtimeClient#

Runs a voice conversation with a realtime model. Pass getToken and adapter. Methods: connect(), disconnect(), startListening(), stopListening(), interrupt(), sendText(text), sendImage(data, mimeType), updateSession(config), and destroy(). See Realtime Chat.

When connect() succeeds, it clears the previous transcript. A transcript that arrives while the microphone starts is kept. A failed connection keeps the previous transcript. Snapshot parts are frozen at runtime, but their TypeScript type stays mutable. Tool input, output, and subagent transcripts on a snapshot are copies.

AudioRecorder#

Records audio from the microphone. Methods: start(), stop() (resolves to the recording), and cancel(). See Audio Recording.

Listeners on the other clients#

GenerationClient, VideoGenerationClient, RealtimeClient, and ByokClient use subscribe(listener) and getSnapshot():

• The listener gets no argument. Call getSnapshot() inside it.
• A listener that throws does not stop the other listeners. The error goes to reportError in the browser and to console.error in other runtimes.

AudioRecorder.subscribe passes the new state: subscribe((state) => ...). getSnapshot() returns that same state.

registerWebMCPTools(tools, options)#

Exposes client tools through the browser WebMCP API. Abort options.signal to remove the tools. See WebMCP Tools.

import { registerWebMCPTools } from "@tanstack/ai-client";
import { searchProducts } from "./tools";

const controller = new AbortController();

await registerWebMCPTools([searchProducts], {
  signal: controller.signal,
  toolOptions: {
    searchProducts: {
      title: "Search products",
      annotations: { readOnlyHint: true },
    },
  },
});

// Later, when the owner of these tools goes away:
controller.abort();

• It returns Promise<void>. During server rendering, in an insecure context, or when WebMCP is not there, it resolves and registers nothing.
• It validates Standard Schema inputs and outputs.
• A tool with needsApproval: true makes the registration fail. If registration fails, the function removes the tools it registered during the call.

Option types: RegisterWebMCPToolsOptions, WebMCPToolOptionsByName, WebMCPToolOptions, WebMCPToolAnnotations.

getWebMCPTools(options?) and subscribeWebMCPTools(listener, options)#

Read the tools that the page registered with WebMCP, as client tools. See Page WebMCP Tools in Chat.

• getWebMCPTools({ filter? }) resolves to the current tools, or [] when WebMCP is not there.
• subscribeWebMCPTools(listener, { signal, filter?, onError? }) calls listener with the tools each time the page adds or removes one. Abort signal to stop.

filter gets a WebMCPPageTool (name, title, description, inputSchema, origin, annotations). Return false to skip it.

createMcpAppBridge(options)#

Creates the bridge that lets an MCP App widget call tools and send chat messages. Options: threadId, callEndpoint, chat, fetchImpl, onLink. See MCP Apps.

defineByok#

Creates a headless BYOK keyring. Import it from @tanstack/ai-client/byok. Pass the keyring to ChatClient, useChat, or a generation hook. See Bring Your Own Key.

import { defineByok, defaultByokStorage } from "@tanstack/ai-client/byok";

export const byok = defineByok({
  storage: defaultByokStorage(),
});

Factory options#

• storage: a KeyringStorage. Default: memoryStorage(), which keeps keys for the session only.
• providers: descriptors whose with companions the keyring adds. With [cloudflareByok, cloudflareAccountByok], a send for cloudflare carries the token and the account id headers. prepare asks for each missing one.

Methods#

The chat and generation clients throw if no provider slug resolves. They do not send every stored key.

Snapshot#

type ByokSnapshot = {
  status: Partial<Record<string, KeyStatus>>;
  locked: boolean;
  prompt: { provider: string; reason: "missing" | "locked" | "invalid" } | null;
  storageError: string | null;
};

type KeyStatus =
  | { state: "empty" }
  | { state: "set"; masked: string }
  | { state: "locked"; masked: string }
  | { state: "validating"; masked: string }
  | { state: "valid"; masked: string }
  | { state: "invalid"; masked: string }
  | { state: "error"; masked: string; message: string };

• status is sparse. Only slugs with a key, a lock, or a validation result appear. A missing entry means no key.
• masked is the last four characters of the key. { state: "empty" } has no masked, so check with "masked" in status.
• storageError is set when loading from storage fails.
• The snapshot never holds the raw key.

Storage#

The library ships no key dialog. Call byok.update(provider, value) from your own UI.

Types#

UIMessage#

interface UIMessage<TTools = any> {
  id: string;
  role: "system" | "user" | "assistant" | "activity";
  name?: string;
  parts: Array<MessagePart<TTools>>;
  createdAt?: Date;
  metadata?: Record<string, any>;
}

metadata is an AG-UI bag. TanStack writes the tanstack key. Your keys stay at the top level.

MessagePart#

Thinking parts are for the UI only. The client does not send them back to the model.

With a typed tools array, ToolCallPart is a union with name as the key. Narrow on part.name to get typed input and output. The approval field exists only on tools with needsApproval: true, so narrow by part.name or check "approval" in part first.

States#

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

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