# @assistant-ui/react-ai-sdk
URL: /docs/api-reference/integrations/vercel-ai-sdk

Vercel AI SDK v5 integration with chat runtime hooks and transport utilities.

Vercel AI SDK integration for assistant-ui.

<Callout type="info">
  This package provides integration with AI SDK v5. For AI SDK v4, see the [AI
  SDK v4 (Legacy)](/docs/runtimes/ai-sdk/v4-legacy) documentation.
</Callout>

API Reference \[#api-reference]

useChatRuntime \[#usechatruntime]

Creates a runtime directly with AI SDK v5's `useChat` hook integration. This is the recommended approach for most use cases.

```tsx
import { useChatRuntime, AssistantChatTransport } from "@assistant-ui/react-ai-sdk";
import { AssistantRuntimeProvider } from "@assistant-ui/react";

const MyRuntimeProvider = ({ children }: { children: React.ReactNode }) => {
  const runtime = useChatRuntime({
    transport: new AssistantChatTransport({
      api: "/api/chat",
    }),
  });

  return (
    <AssistantRuntimeProvider runtime={runtime}>
      {children}
    </AssistantRuntimeProvider>
  );
};
```

To customize the API endpoint, simply change the `api` parameter:

```tsx
const runtime = useChatRuntime({
  transport: new AssistantChatTransport({
    api: "/my-custom-api/chat",
  }),
});
```

<ParametersTable
  parameters={[
{
  name: "options",
  type: "UseChatRuntimeOptions",
  description: "Configuration options for the chat runtime.",
  children: [
    {
      type: "UseChatRuntimeOptions",
      parameters: [
        {
          name: "api",
          type: "string",
          description: "The API endpoint URL. Defaults to '/api/chat'.",
        },
        {
          name: "transport",
          type: "ChatTransport",
          description:
            "Custom transport implementation. Defaults to AssistantChatTransport which forwards system messages and tools.",
        },
        {
          name: "cloud",
          type: "AssistantCloud",
          description:
            "Optional AssistantCloud instance for chat persistence.",
        },
        {
          name: "initialMessages",
          type: "UIMessage[]",
          description: "Initial messages to populate the chat.",
        },
        {
          name: "onFinish",
          type: "(message: UIMessage) => void",
          description: "Callback when a message completes streaming.",
        },
        {
          name: "onError",
          type: "(error: Error) => void",
          description: "Callback for handling errors.",
        },
      ],
    },
  ],
},
]}
/>

<Callout type="info">
  By default, `useChatRuntime` uses `AssistantChatTransport` which automatically
  forwards system messages and frontend tools to your backend API. This enables
  your backend to receive the full context from the assistant-ui.
</Callout>

useAISDKRuntime \[#useaisdkruntime]

For advanced use cases where you need direct access to the `useChat` hook from AI SDK.

```tsx
import { useChat } from "@ai-sdk/react";
import { useAISDKRuntime } from "@assistant-ui/react-ai-sdk";
import { AssistantRuntimeProvider } from "@assistant-ui/react";

const MyRuntimeProvider = ({ children }: { children: React.ReactNode }) => {
  const chat = useChat({
    api: "/api/chat",
  });

  const runtime = useAISDKRuntime(chat);

  return (
    <AssistantRuntimeProvider runtime={runtime}>
      {children}
    </AssistantRuntimeProvider>
  );
};
```

<ParametersTable
  parameters={[
{
  name: "chat",
  type: "ReturnType<typeof useChat>",
  description: "The chat helpers from @ai-sdk/react's useChat hook.",
},
{
  name: "options",
  type: "AISDKRuntimeOptions",
  description: "Optional configuration options.",
  children: [
    {
      type: "AISDKRuntimeOptions",
      parameters: [
        {
          name: "cloud",
          type: "AssistantCloud",
          description:
            "Optional AssistantCloud instance for chat persistence.",
        },
        {
          name: "adapters",
          type: "RuntimeAdapters",
          description:
            "Optional runtime adapters for attachments, feedback, speech, etc.",
        },
      ],
    },
  ],
},
]}
/>

AssistantChatTransport \[#assistantchattransport]

A transport that extends the default AI SDK transport to automatically forward system messages and frontend tools to your backend.

```tsx
import { AssistantChatTransport } from "@assistant-ui/react-ai-sdk";
import { useChatRuntime } from "@assistant-ui/react-ai-sdk";

const runtime = useChatRuntime({
  transport: new AssistantChatTransport({
    api: "/my-custom-api/chat",
  }),
});
```

<ParametersTable
  parameters={[
{
  name: "options",
  type: "HttpChatTransportInitOptions",
  description: "Transport configuration options.",
  children: [
    {
      type: "HttpChatTransportInitOptions",
      parameters: [
        {
          name: "api",
          type: "string",
          description: "The API endpoint URL.",
        },
        {
          name: "headers",
          type: "Record<string, string> | Headers",
          description: "Optional headers to include in requests.",
        },
        {
          name: "credentials",
          type: "RequestCredentials",
          description: "Optional credentials mode for fetch requests.",
        },
      ],
    },
  ],
},
]}
/>

frontendTools \[#frontendtools]

Helper function to convert frontend tool definitions to AI SDK format for use in your backend.

```tsx
import { frontendTools } from "@assistant-ui/react-ai-sdk";
import { streamText, convertToModelMessages } from "ai";
import { openai } from "@ai-sdk/openai";

export async function POST(req: Request) {
  const { messages, system, tools } = await req.json();

  const result = streamText({
    model: openai("gpt-4o"),
    system,
    messages: convertToModelMessages(messages),
    tools: {
      // Wrap frontend tools with the helper
      ...frontendTools(tools),
      // Your backend tools
      myBackendTool: tool({
        // ...
      }),
    },
  });

  return result.toUIMessageStreamResponse();
}
```

<ParametersTable
  parameters={[
{
  name: "tools",
  type: "Record<string, unknown>",
  description:
    "Frontend tools object forwarded from AssistantChatTransport.",
},
]}
/>

<Callout type="info">
  The `frontendTools` helper converts frontend tool definitions to the AI SDK
  format and ensures they are properly handled by the streaming response.
</Callout>