Persistence (Advanced)
- GenerationsUpdated
- Realtime Voice Chat
- Text-to-Speech
- Transcription
- Transcription: Advanced
- Voice Creation
- Audio Recording
- Audio Generation
- Image Generation
- Image Generation: Advanced
- Video Generation
- Video Generation: Advanced
- Live Generation
- World Generation
- Motion GenerationNew
- 3D Model GenerationNew
- 3D Model Generation: AdvancedNew
- Generation HooksUpdated
- Build your first harness
- Host options
- Send and show media
- Connect clients
- Write a client in any language
- Access and tenants
- Run in the terminal
- Deploy a harness
- Send inputs safely
- Run a tool without a model
- Durable sessions
- Run background work on workers
- List, rename, and fork sessions
- Lifecycle and retention
- Run side effects once
- Wait for a person
- Build on the session log
- Control how a turn ends
- Store settings per thread
- Compact a long session
- Fork and reset a thread
- One log for a session tree
- Write a plugin
- Track usage and cost
- Ask before risky tool calls
- Give your agent coding tools
- Sandbox and extend the coding tools
- Run the coding tools for many threads
- Undo a turn
- Build a coding agent
- Delegate to coding agents
- Switch between agent profiles
- Auth and connectors
- Share a thread between people
- Connect model providersUpdated
- Sign in with a ChatGPT or SuperGrok planNew
- Build your own UI
- Code mode in a harness
- Work until a goal is met
- Run agents from a harness
- Hand off a conversation
- Add skills
- Use MCP servers
- Give your agent a computer
- Use from any MCP client
- Use a harness from an editor (ACP)
- Overview
- Quick Start
- Providers
- Harnesses
- Harness AuthUpdated
- Workspace
- Tools
- Policy
- Lifecycle & Snapshots
- Portable Snapshots
- Keep Files After Reload
- Save a Named Version
- Branch From a Version
- Send a Frozen File
- Let the Agent Save and Fork
- Pick Which Files to Keep
- What a Snapshot Stores
- Checkpoint at Any Time
- Store Checkpoints
- Instance Durability
- Durable Runs
- Events
Sandboxes (Advanced)
- Runtime Context
- Bring Your Own Key
- Keep Keys on the Server
- Debug Logging
- Multimodal Content
- Files API
- Per-Model Type Safety
- Runtime Adapter Switching
- Tree-Shaking
- Extend Adapter
- Extend Adapter: Advanced
- Typed Pre-Configured Options
- Test with a Fake Model
- Prompt Caching
- Mid-Conversation Changes
- Approval Flow Processing
TanStack useChat with an AI SDK server
Point TanStack AI useChat at a Vercel AI SDK route. Wrap an AI SDK ChatTransport with fromChatTransport, and pass it as the connection. Your streamText route does not change.
Use this page to move the client first. To move the server first, see AI SDK useChat with a TanStack AI server.
Against your AI SDK route, TanStack useChat gives you:
- Client persistence, with no server code.
- Resume after a reload, when the route has the AI SDK resume GET.
- A message queue while a reply streams.
- Client tools that the route reads from the request, with no copy on the route.
- Typed structured output, with partial objects while it streams.
- Typed approvals, TanStack devtools, and hooks for React, Solid, Vue, Svelte, Preact, Angular and more.
Warning
This bridge is a stop gap while you port. Some features change shape or are dropped on the way (see AI SDK bridge compatibility). When the client works, port the route to chat() with the migration guide, then remove the bridge.
1. Install the packages#
npm i @tanstack/ai @tanstack/ai-client @tanstack/ai-react @tanstack/ai-vercel-compat aipnpm add @tanstack/ai @tanstack/ai-client @tanstack/ai-react @tanstack/ai-vercel-compat aiyarn add @tanstack/ai @tanstack/ai-client @tanstack/ai-react @tanstack/ai-vercel-compat aibun add @tanstack/ai @tanstack/ai-client @tanstack/ai-react @tanstack/ai-vercel-compat ai2. Connect useChat to the route#
import { useState } from 'react'
import { useChat } from '@tanstack/ai-react'
import { fromChatTransport } from '@tanstack/ai-vercel-compat'
import { DefaultChatTransport } from 'ai'
const connection = fromChatTransport(
new DefaultChatTransport({ api: '/api/chat' }),
)
export function Chat() {
const [input, setInput] = useState('')
const { messages, sendMessage } = useChat({
connection,
threadId: 'support-chat',
})
return (
<div>
{messages.map((message) => (
<div key={message.id}>
{message.parts.map((part, idx) =>
part.type === 'text' ? <span key={idx}>{part.content}</span> : null,
)}
</div>
))}
<input value={input} onChange={(e) => setInput(e.target.value)} />
<button onClick={() => sendMessage(input)}>Send</button>
</div>
)
}DefaultChatTransport sends the request and reads the stream, as it does for the AI SDK hook. Its options work the same, for example headers, credentials and prepareSendMessagesRequest. The threadId goes to the route as the chat id.
3. Keep the server#
Your AI SDK route works as it is:
import { openai } from '@ai-sdk/openai'
import { convertToModelMessages, streamText } from 'ai'
export async function POST(request: Request) {
const { messages } = await request.json()
const result = streamText({
model: openai('gpt-6.1-sol'),
messages: await convertToModelMessages(messages),
})
return result.toUIMessageStreamResponse()
}4. Run client tools and approve tool calls#
Define client tools on the client only. The connection sends their names, descriptions and JSON Schemas to the route in the request body. Read them on the route with clientToolsFromAISDKBody, together with the server tools:
import { openai } from '@ai-sdk/openai'
import { clientToolsFromAISDKBody } from '@tanstack/ai-vercel-compat'
import { convertToModelMessages, streamText, tool } from 'ai'
import { z } from 'zod'
const getWeather = tool({
description: 'Get the weather for a city',
inputSchema: z.object({ city: z.string() }),
execute: async ({ city }) => ({ city, temperature: 72 }),
})
// The route asks for the approval and runs the tool after it.
const bookFlight = tool({
description: 'Book a flight',
inputSchema: z.object({ to: z.string() }),
needsApproval: true,
execute: async ({ to }) => ({ booked: to }),
})
export async function POST(request: Request) {
const body = await request.json()
const result = streamText({
model: openai('gpt-6.1-sol'),
messages: await convertToModelMessages(body.messages),
tools: clientToolsFromAISDKBody(body, { getWeather, bookFlight }),
})
return result.toUIMessageStreamResponse()
}- A server tool wins when a client tool has the same name.
- A client tool has no execute on the route, so streamText stops at the call.
- Browser tools from WebMCP reach the route the same way.
Pass the tools to useChat. The connection gets them from useChat:
- Client tool: give it a .client() implementation. When the route stops at the call, the client runs the tool and sends the output back.
- Tool approval: declare the tool on the route with needsApproval: true and an execute, as bookFlight above. On the client, give it needsApproval: true and no implementation. The call shows up in interrupts. Resolve it with interrupt.resolveInterrupt(true) or false. The answer goes back to the route, and streamText runs or skips the tool.
import { toolDefinition } from '@tanstack/ai'
import { useChat } from '@tanstack/ai-react'
import { fromChatTransport } from '@tanstack/ai-vercel-compat'
import { DefaultChatTransport } from 'ai'
import { z } from 'zod'
const getLocation = toolDefinition({
name: 'getLocation',
description: 'Get the location of the user',
inputSchema: z.object({}),
}).client(() => ({ city: 'Sydney' }))
const bookFlight = toolDefinition({
name: 'bookFlight',
description: 'Book a flight',
inputSchema: z.object({ to: z.string() }),
needsApproval: true,
})
const tools = [getLocation, bookFlight] as const
const connection = fromChatTransport(
new DefaultChatTransport({ api: '/api/chat' }),
)
export function Chat() {
const { interrupts } = useChat({
connection,
threadId: 'support-chat',
tools,
})
return interrupts.map((interrupt) =>
interrupt.kind === 'tool-approval' ? (
<button
key={interrupt.id}
onClick={() => interrupt.resolveInterrupt(true)}
>
Approve {interrupt.toolName}
</button>
) : null,
)
}5. Get typed structured output#
When the route streams an object with Output.object, pass the same schema to useChat as outputSchema. The answer is a structured-output part, with partial objects while it streams and the checked data at the end:
import { useChat } from '@tanstack/ai-react'
import { fromChatTransport } from '@tanstack/ai-vercel-compat'
import { DefaultChatTransport } from 'ai'
import { z } from 'zod'
const recipe = z.object({ name: z.string(), steps: z.array(z.string()) })
const connection = fromChatTransport(
new DefaultChatTransport({ api: '/api/recipe' }),
)
export function Recipe() {
const { messages } = useChat({
connection,
threadId: 'recipe',
outputSchema: recipe,
})
return messages.flatMap((message) =>
message.parts.map((part, i) =>
part.type === 'structured-output' ? (
<h2 key={i}>{part.partial?.name}</h2>
) : null,
),
)
}Only the text of the last step is the answer. Text from an earlier step that calls tools is not part of it. If the answer is not valid JSON for the schema, the run ends with an error. A plain JSON Schema only types the answer. A Zod, Valibot or ArkType schema also checks it.
6. Load a saved chat#
If your app saves AI SDK messages, convert them with fromAISDKMessages and pass them as initialMessages:
import { useChat } from '@tanstack/ai-react'
import {
fromAISDKMessages,
fromChatTransport,
} from '@tanstack/ai-vercel-compat'
import { DefaultChatTransport } from 'ai'
import type { UIMessage } from 'ai'
const connection = fromChatTransport(
new DefaultChatTransport({ api: '/api/chat' }),
)
export function useSavedChat(saved: Array<UIMessage>) {
return useChat({
connection,
threadId: 'support-chat',
initialMessages: fromAISDKMessages(saved),
})
}7. Show data parts as activity#
A data part with an id (writer.write({ type: 'data-weather', id, data }) on the route) arrives as an activity message of type weather. A new value for the same type and id replaces it. A transient data part, or one with no id, arrives as a custom event named data-<name>.
8. Resume a stream#
A dropped connection needs nothing. The connection calls reconnectToStream on the transport, and the reply continues. It waits longer between tries that get no new data, as the TanStack HTTP connections do. To change the waits and the limit, pass reconnect to fromChatTransport, for example { maxAttempts: 10 }.
A reply that ends before its finish chunk, for example at a proxy timeout, also reconnects. When the route has no resume GET, a dropped reply fails with its own error, and a reply that ended early stays as it is.
To continue a reply after a page reload, add client persistence. The route must support the AI SDK resume GET (/api/chat/<id>/stream):
import { localStoragePersistence, useChat } from '@tanstack/ai-react'
import { fromChatTransport } from '@tanstack/ai-vercel-compat'
import { DefaultChatTransport } from 'ai'
const connection = fromChatTransport(
new DefaultChatTransport({ api: '/api/chat' }),
)
export function useSupportChat() {
return useChat({
connection,
threadId: 'support-chat',
persistence: localStoragePersistence(),
})
}The rejoin after a reload needs a transport that replays the reply from its start, as DefaultChatTransport does.
What does not go through#
- AG-UI shared state. The AI SDK has no state.
- Provider metadata on text parts, for example OpenAI item ids on text. TanStack keeps no metadata per text part.
- Sources, citations and generated files arrive as custom events, not as message parts.
For every event and message part, see AI SDK bridge compatibility.
Done#
TanStack useChat streams replies, runs tools, asks for approvals, and continues after a reload against your AI SDK route.