Vercel AI SDK integration for assistant-ui.

API Reference#

useChatRuntime#

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

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:

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: "transport",
type: "ChatTransport",
description:
"Custom transport implementation. Defaults to AssistantChatTransport (which sends requests to '/api/chat' and forwards system messages and tools). Use new AssistantChatTransport({ api: '/custom-endpoint' }) to customize the endpoint.",
},
{
name: "cloud",
type: "AssistantCloud",
description:
"Optional AssistantCloud instance for chat persistence.",
},
{
name: "adapters",
type: "RuntimeAdapters",
description:
"Optional runtime adapters to extend or override built-in functionality (attachments, speech, dictation, feedback, history).",
},
{
name: "toCreateMessage",
type: "(message: AppendMessage) => CreateUIMessage",
description:
"Optional custom function to convert an AppendMessage into an AI SDK CreateUIMessage before sending.",
},
{
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.",
},
],
},
],
},
]}
/>

useAISDKRuntime#

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

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",
description: "The chat helpers from @ai-sdk/react's useChat hook.",
},
{
name: "options",
type: "AISDKRuntimeAdapter",
description: "Optional configuration options.",
children: [
{
type: "AISDKRuntimeAdapter",
parameters: [
{
name: "adapters",
type: "RuntimeAdapters",
description:
"Optional runtime adapters for attachments, feedback, speech, etc.",
},
],
},
],
},
]}
/>

AssistantChatTransport#

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

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#

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

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: await 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.",
},
]}
/>