AI Docs
Chat & Streaming
Transports
Tools
Middleware
Chat UI Recipes
Interrupts
MCP
Resumable Streams
Persistence
Persistence (Advanced)
Media
- GenerationsUpdated
- Realtime Voice Chat
- Text-to-Speech
- Transcription
- Transcription: Advanced
- Voice Creation
- Audio Recording
- Audio Generation
- Image Generation
- Image Generation: AdvancedUpdated
- Video Generation
- Video Generation: Advanced
- Live Generation
- World Generation
- Motion GenerationNew
- 3D Model GenerationNew
- 3D Model Generation: AdvancedNew
- Generation HooksUpdated
Embeddings
Reranking
Evaluate
Code Mode
Computer Use
Harness
- 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)
Sandboxes
- 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)
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
Migration
AI/LLM: This documentation page is available in plain markdown format at/ai/latest/docs/migration/ai-sdk-compatibility.md
AI SDK bridge compatibility
Use these tables to see what @tanstack/ai-vercel-compat does with each feature, event and message part. The guides are AI SDK useChat with a TanStack AI server and TanStack useChat with an AI SDK server. The column for an AI SDK client also covers toChatTransport, which runs the same conversion in the browser.
Warning
The bridge is a stop gap while you port one side of an app. The rows marked β Dropped and β‘οΈ One way are why. Finish the port with the migration guide, then remove the bridge.
Each row has one of these results:
| Result | Meaning |
|---|---|
| β Same | It arrives with the same meaning and data. |
| π Mapped | It arrives as a different shape that carries the same data. |
| π§© Grouped | It is joined with other items into one item, or is split from one. |
| β‘οΈ One way | It crosses in one direction only. |
| β Dropped | It does not cross. |
π Features#
| Feature | AI SDK client, TanStack server | TanStack client, AI SDK server |
|---|---|---|
| Text | β Same | β Same |
| Reasoning and its signature | β Same | β Same |
| Tool-call provider data (Gemini thoughtSignature, OpenAI item ids) | π Mapped to callProviderMetadata and back | π Mapped to tool-call metadata and back |
| Server tools | β Same | β Same |
| Provider-executed tools (web search) | π Mapped to providerExecuted | π Mapped to the TanStack provider-executed flag |
| Client tools | β Same | π Mapped. Their schemas go to the route in the body. Read them with clientToolsFromAISDKBody. |
| Tool approvals | π Mapped to tool-approval-request and back to resume | π Mapped to a tool-approval interrupt. The approval signature goes back to the route. |
| Tool errors and denials | β Same | β Same |
| Steps of a tool loop | π Mapped to start-step / finish-step | π Mapped to STEP_* events, and to step-start parts in the history |
| Files and images from the user | π Mapped to content parts | π Mapped to file parts |
| Web search sources | π Mapped to source-url chunks | π Mapped to custom events |
| Model, response ids and token usage | π Mapped to message metadata under tanstack | β Dropped (the AI SDK stream has none) |
| Message metadata of the app | β Same | π Mapped to metadata.aiSdk and back |
| Activity | π Mapped to a data-<activityType> part | π Mapped from a data-<name> part with an id and object data |
| Subagents | π§© Grouped into one data-subagent card per child | β Dropped (the AI SDK has no subagents) |
| Shared state | β‘οΈ One way, to a data-state part | β Dropped (the AI SDK has no state) |
| Structured output | β Same (the JSON is text) | π Mapped to a typed structured-output part with outputSchema, and back to text in the history |
| Custom events | π Mapped to a transient data-<name> chunk | π Mapped from a transient data-<name> chunk |
| Stream resume | β Same, with a durability log | β Same. A reload needs client persistence. |
| System messages | β Dropped. The server owns its system prompts. | β Dropped. streamText rejects them. |
| Generated files | β Dropped (chat() sends none) | π Mapped to custom events |
β² AI SDK client, TanStack server#
β¬οΈ Reply: chat() events to AI SDK chunks#
| AG-UI event from chat() | AI SDK chunk | Result |
|---|---|---|
| RUN_STARTED | β Dropped. A start with no message id goes before the first part, so the AI SDK client keeps its own message id. | |
| TEXT_MESSAGE_START / CONTENT / END | text-start / text-delta / text-end | β Same |
| REASONING_MESSAGE_START / CONTENT / END | reasoning-start / reasoning-delta / reasoning-end | β Same |
| REASONING_ENCRYPTED_VALUE, message | providerMetadata.tanstack.signature on reasoning-end | π Mapped. The signature can arrive after REASONING_MESSAGE_END. Redacted thinking adds redacted: true. |
| REASONING_ENCRYPTED_VALUE, tool call | thoughtSignature in the tool call's providerMetadata.tanstack | π Mapped |
| TOOL_CALL_START / ARGS | tool-input-start / tool-input-delta | β Same |
| TOOL_CALL_START.metadata | providerMetadata.tanstack on the tool chunks (callProviderMetadata) | π Mapped |
| TOOL_CALL_END | tool-input-available with the parsed input | π Mapped. An object on the end event is the input. Arguments that are not JSON become tool-input-error. |
| Provider-executed call | providerExecuted: true, and a tool-output-available with its sources | π Mapped |
| Sources of a provider-executed call | source-url | π Mapped |
| TOOL_CALL_RESULT | tool-output-available | β Same. JSON output is parsed. |
| TOOL_CALL_RESULT with an error | tool-output-error | π Mapped |
| TOOL_CALL_RESULT that the user denied | tool-output-denied | π Mapped |
| A new model call in the run | start-step, and finish-step at its end | π Mapped |
| RUN_FINISHED metadata (model, responseId, responseItems, source) | message-metadata under tanstack | π Mapped |
| RUN_FINISHED.usage | message-metadata as tanstack.tokenUsage, one entry per model call | π Mapped |
| RUN_FINISHED with an approval interrupt | tool-approval-request, and tanstack.runId in the message metadata | π Mapped |
| RUN_FINISHED with a client tool interrupt | Nothing. The AI SDK client runs a call that has no output. | π Mapped |
| RUN_FINISHED with another interrupt | error. No finish. | π Mapped. The run stays paused. |
| RUN_FINISHED | One finish after the last model call, with that finish reason | π Mapped. Each model call ends with finish-step. |
| RUN_FINISHED with outcome cancelled | abort | π Mapped |
| The event stream ends with no RUN_FINISHED or RUN_ERROR | abort | π Mapped |
| RUN_ERROR | error | π Mapped |
| An error thrown by chat() | error with the error message | π Mapped |
| ACTIVITY_SNAPSHOT / ACTIVITY_DELTA | data-<activityType> with the activity id and the full content | π Mapped. A delta is applied, then the full content is sent. |
| STATE_SNAPSHOT / STATE_DELTA | data-state with id state and the full state | β‘οΈ One way |
| SUBAGENT_* events and child text | data-subagent with id subagentRunId | π§© Grouped. One card holds the name, status, text and error. |
| Child tool calls, reasoning and activity | β Dropped. The card shows the child text only. | |
| Approval inside a subagent | interruptIds on the subagent card | π§© Grouped |
| CUSTOM | Transient data-<name> | π Mapped. It reaches onData, not the message. |
| MESSAGES_SNAPSHOT, RAW | β Dropped | |
| STEP_* and *_CHUNK shorthand events | β Dropped. chat() does not send them. |
β¬οΈ Request: AI SDK message parts to chat() messages#
| AI SDK part | TanStack part | Result |
|---|---|---|
| text | text | β Same |
| reasoning | thinking with the signature | β Same |
| file | image, audio, video or document, by media type | π Mapped. A base64 data URL becomes a data source. |
| tool-<name> / dynamic-tool with output | tool-call plus tool-result | π§© Grouped. The result follows its call. |
| callProviderMetadata.tanstack | tool-call metadata | π Mapped |
| Tool part with providerExecuted | tool-call with no tool-result | π Mapped. chat() does not run it again. |
| Tool part with output-error / output-denied | tool-call plus an error tool-result | π§© Grouped |
| Tool part with approval-responded | Pending tool-call, plus a resume item { approved } | π Mapped. The message needs tanstack.runId in its metadata, else the request is a 400. |
| The reason of an approval answer | β Dropped. resume has no field for it. | |
| Message metadata | metadata | β Same. With more than one step, tanstack.responseItems is removed. |
| system message | β Dropped. Pass systemPrompts to chat() on the server. | |
| source-url, source-document, data-*, step-start, custom, reasoning-file | β Dropped |
π΄ TanStack client, AI SDK server#
β¬οΈ Reply: AI SDK chunks to TanStack events#
| AI SDK chunk | AG-UI event | Result |
|---|---|---|
| start | π Mapped. RUN_STARTED is sent before the chunks. A message id on start is the text message id. | |
| messageMetadata on start, message-metadata, finish | metadata.aiSdk on the message, at the end of the run | π Mapped |
| start-step / finish-step | STEP_STARTED / STEP_FINISHED | β Same |
| reset-step | β Dropped | |
| text-start / text-delta / text-end | TEXT_MESSAGE_START / CONTENT / END | π§© Grouped. All text parts go into one assistant message. |
| Text of an Output.object answer, with outputSchema | structured-output.start, the text, then structured-output.complete with the checked object | π Mapped. A schema failure ends the run with RUN_ERROR. |
| providerMetadata on text chunks | β Dropped. TanStack keeps no metadata per text part. | |
| text-end.citations | CUSTOM named citations | π Mapped |
| reasoning-start / reasoning-delta / reasoning-end | REASONING_MESSAGE_* | β Same. Each reasoning part gets its own id. |
| providerMetadata on reasoning-end | REASONING_ENCRYPTED_VALUE | π Mapped. It goes back to the route unchanged. |
| tool-input-start / tool-input-delta | TOOL_CALL_START / TOOL_CALL_ARGS | β Same |
| providerMetadata on tool input chunks | tool-call metadata.aiSdk.callProviderMetadata | π Mapped |
| providerExecuted | tool-call metadata.providerExecuted | π Mapped. The client does not run the call. |
| inputEncoding: 'text' | One TOOL_CALL_ARGS with the final input | π Mapped |
| tool-input-available | TOOL_CALL_END, after any approval or output for the same call | β Same |
| tool-input-error | TOOL_CALL_END plus an error TOOL_CALL_RESULT | π Mapped |
| tool-output-available | TOOL_CALL_RESULT | β Same |
| providerMetadata on tool output chunks | tool-call metadata.aiSdk.resultProviderMetadata | π Mapped when it comes right after the call. Later, it is dropped. |
| tool-output-available with preliminary: true | β Dropped. Only the final output is sent. | |
| tool-output-error / tool-output-denied | Error TOOL_CALL_RESULT | π Mapped |
| tool-approval-request | Approval interrupt on RUN_FINISHED | π Mapped. Without tools, it is a generic interrupt: resolve it with { approved }. |
| signature, approvalDescriptor, inputSchemaInput, reason of an approval request | tool-call metadata.aiSdk.approval | π Mapped |
| tool-approval-request with isAutomatic | β Dropped. The route already decided, and the output or denial follows. | |
| tool-approval-response | β Dropped | |
| finish | RUN_FINISHED with the finish reason | π Mapped |
| finish with tool-calls | RUN_FINISHED with no finish reason | π Mapped. In TanStack, tool_calls means more steps follow in the same stream. |
| error | RUN_ERROR | π Mapped |
| abort | RUN_FINISHED with a cancelled outcome | π Mapped |
| The stream ends before finish, error or abort | With fromChatTransport, a reconnect | π Mapped. With nothing to resume, the run finishes with what came. |
| data-<name> with an id and object data | ACTIVITY_SNAPSHOT of type <name> | π Mapped. The same type and id replace it. The activity id is data-<name>:<id>. |
| Other data-<name> (transient, no id, or not an object) | CUSTOM named data-<name> | π Mapped |
| source-url, source-document, file, reasoning-file | CUSTOM with the same name | π Mapped |
| custom | β Dropped |
β¬οΈ Request: TanStack messages to AI SDK message parts#
| TanStack part | AI SDK part | Result |
|---|---|---|
| text | text | β Same |
| thinking | reasoning with the stored provider metadata | β Same |
| image, audio, video, document | file | π Mapped. A data source becomes a data URL. |
| tool-call plus its tool-result | One dynamic-tool part | π§© Grouped |
| tool-call metadata.aiSdk | callProviderMetadata, resultProviderMetadata | π Mapped |
| Provider-executed tool-call | dynamic-tool with providerExecuted: true | π Mapped |
| tool-call with an approval answer | dynamic-tool with approval-responded, and the stored signature | π Mapped |
| tool-call that waits for approval | dynamic-tool with approval-requested | π Mapped |
| Client tool declarations of the run | clientTools in the request body | π Mapped |
| A tool result followed by more of the reply | step-start before the next step | π Mapped |
| structured-output, complete | text with the JSON | π Mapped |
| Message metadata.aiSdk | Message metadata | π Mapped |
| system messages | β Dropped. streamText rejects them unless allowSystemInMessages is set. | |
| activity messages | β Dropped | |
| subagent, ui-resource | β Dropped |