TanStack
Migration

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:

ResultMeaning
✅ SameIt arrives with the same meaning and data.
🔄 MappedIt arrives as a different shape that carries the same data.
🧩 GroupedIt is joined with other items into one item, or is split from one.
➡️ One wayIt crosses in one direction only.
❌ DroppedIt does not cross.

📋 Features

FeatureAI SDK client, TanStack serverTanStack 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 chunkResult
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 / ENDtext-start / text-delta / text-end✅ Same
REASONING_MESSAGE_START / CONTENT / ENDreasoning-start / reasoning-delta / reasoning-end✅ Same
REASONING_ENCRYPTED_VALUE, messageproviderMetadata.tanstack.signature on reasoning-end🔄 Mapped. The signature can arrive after REASONING_MESSAGE_END. Redacted thinking adds redacted: true.
REASONING_ENCRYPTED_VALUE, tool callthoughtSignature in the tool call's providerMetadata.tanstack🔄 Mapped
TOOL_CALL_START / ARGStool-input-start / tool-input-delta✅ Same
TOOL_CALL_START.metadataproviderMetadata.tanstack on the tool chunks (callProviderMetadata)🔄 Mapped
TOOL_CALL_ENDtool-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 callproviderExecuted: true, and a tool-output-available with its sources🔄 Mapped
Sources of a provider-executed callsource-url🔄 Mapped
TOOL_CALL_RESULTtool-output-available✅ Same. JSON output is parsed.
TOOL_CALL_RESULT with an errortool-output-error🔄 Mapped
TOOL_CALL_RESULT that the user deniedtool-output-denied🔄 Mapped
A new model call in the runstart-step, and finish-step at its end🔄 Mapped
RUN_FINISHED metadata (model, responseId, responseItems, source)message-metadata under tanstack🔄 Mapped
RUN_FINISHED.usagemessage-metadata as tanstack.tokenUsage, one entry per model call🔄 Mapped
RUN_FINISHED with an approval interrupttool-approval-request, and tanstack.runId in the message metadata🔄 Mapped
RUN_FINISHED with a client tool interruptNothing. The AI SDK client runs a call that has no output.🔄 Mapped
RUN_FINISHED with another interrupterror. No finish.🔄 Mapped. The run stays paused.
RUN_FINISHEDOne finish after the last model call, with that finish reason🔄 Mapped. Each model call ends with finish-step.
RUN_FINISHED with outcome cancelledabort🔄 Mapped
The event stream ends with no RUN_FINISHED or RUN_ERRORabort🔄 Mapped
RUN_ERRORerror🔄 Mapped
An error thrown by chat()error with the error message🔄 Mapped
ACTIVITY_SNAPSHOT / ACTIVITY_DELTAdata-<activityType> with the activity id and the full content🔄 Mapped. A delta is applied, then the full content is sent.
STATE_SNAPSHOT / STATE_DELTAdata-state with id state and the full state➡️ One way
SUBAGENT_* events and child textdata-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 subagentinterruptIds on the subagent card🧩 Grouped
CUSTOMTransient 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 partTanStack partResult
texttext✅ Same
reasoningthinking with the signature✅ Same
fileimage, audio, video or document, by media type🔄 Mapped. A base64 data URL becomes a data source.
tool-<name> / dynamic-tool with outputtool-call plus tool-result🧩 Grouped. The result follows its call.
callProviderMetadata.tanstacktool-call metadata🔄 Mapped
Tool part with providerExecutedtool-call with no tool-result🔄 Mapped. chat() does not run it again.
Tool part with output-error / output-deniedtool-call plus an error tool-result🧩 Grouped
Tool part with approval-respondedPending 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 metadatametadata✅ 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 chunkAG-UI eventResult
start🔄 Mapped. RUN_STARTED is sent before the chunks. A message id on start is the text message id.
messageMetadata on start, message-metadata, finishmetadata.aiSdk on the message, at the end of the run🔄 Mapped
start-step / finish-stepSTEP_STARTED / STEP_FINISHED✅ Same
reset-step❌ Dropped
text-start / text-delta / text-endTEXT_MESSAGE_START / CONTENT / END🧩 Grouped. All text parts go into one assistant message.
Text of an Output.object answer, with outputSchemastructured-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.citationsCUSTOM named citations🔄 Mapped
reasoning-start / reasoning-delta / reasoning-endREASONING_MESSAGE_*✅ Same. Each reasoning part gets its own id.
providerMetadata on reasoning-endREASONING_ENCRYPTED_VALUE🔄 Mapped. It goes back to the route unchanged.
tool-input-start / tool-input-deltaTOOL_CALL_START / TOOL_CALL_ARGS✅ Same
providerMetadata on tool input chunkstool-call metadata.aiSdk.callProviderMetadata🔄 Mapped
providerExecutedtool-call metadata.providerExecuted🔄 Mapped. The client does not run the call.
inputEncoding: 'text'One TOOL_CALL_ARGS with the final input🔄 Mapped
tool-input-availableTOOL_CALL_END, after any approval or output for the same call✅ Same
tool-input-errorTOOL_CALL_END plus an error TOOL_CALL_RESULT🔄 Mapped
tool-output-availableTOOL_CALL_RESULT✅ Same
providerMetadata on tool output chunkstool-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-deniedError TOOL_CALL_RESULT🔄 Mapped
tool-approval-requestApproval interrupt on RUN_FINISHED🔄 Mapped. Without tools, it is a generic interrupt: resolve it with { approved }.
signature, approvalDescriptor, inputSchemaInput, reason of an approval requesttool-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
finishRUN_FINISHED with the finish reason🔄 Mapped
finish with tool-callsRUN_FINISHED with no finish reason🔄 Mapped. In TanStack, tool_calls means more steps follow in the same stream.
errorRUN_ERROR🔄 Mapped
abortRUN_FINISHED with a cancelled outcome🔄 Mapped
The stream ends before finish, error or abortWith fromChatTransport, a reconnect🔄 Mapped. With nothing to resume, the run finishes with what came.
data-<name> with an id and object dataACTIVITY_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-fileCUSTOM with the same name🔄 Mapped
custom❌ Dropped

⬆️ Request: TanStack messages to AI SDK message parts

TanStack partAI SDK partResult
texttext✅ Same
thinkingreasoning with the stored provider metadata✅ Same
image, audio, video, documentfile🔄 Mapped. A data source becomes a data URL.
tool-call plus its tool-resultOne dynamic-tool part🧩 Grouped
tool-call metadata.aiSdkcallProviderMetadata, resultProviderMetadata🔄 Mapped
Provider-executed tool-calldynamic-tool with providerExecuted: true🔄 Mapped
tool-call with an approval answerdynamic-tool with approval-responded, and the stored signature🔄 Mapped
tool-call that waits for approvaldynamic-tool with approval-requested🔄 Mapped
Client tool declarations of the runclientTools in the request body🔄 Mapped
A tool result followed by more of the replystep-start before the next step🔄 Mapped
structured-output, completetext with the JSON🔄 Mapped
Message metadata.aiSdkMessage metadata🔄 Mapped
system messages❌ Dropped. streamText rejects them unless allowSystemInMessages is set.
activity messages❌ Dropped
subagent, ui-resource❌ Dropped