Skip to content
Migration

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

shell
npm i @tanstack/ai @tanstack/ai-client @tanstack/ai-react @tanstack/ai-vercel-compat ai

2. Connect useChat to the route

tsx
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:

ts
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:

ts
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.
tsx
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:

tsx
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:

tsx
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):

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