@assistant-ui/react-ai-sdk

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

Vercel AI SDK integration for assistant-ui.

This package provides integration with AI SDK v6. For older versions, see the AI SDK v5 (Legacy) or AI SDK v4 (Legacy) documentation.

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",
  }),
});

options?: UseChatRuntimeOptions

Configuration options for the chat runtime.

UseChatRuntimeOptions

transport?: ChatTransport

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.

cloud?: AssistantCloud

Optional AssistantCloud instance for chat persistence.

adapters?: RuntimeAdapters

Optional runtime adapters to extend or override built-in functionality (attachments, speech, dictation, feedback, history).

toCreateMessage?: (message: AppendMessage) => CreateUIMessage

Optional custom function to convert an AppendMessage into an AI SDK CreateUIMessage before sending.

initialMessages?: UIMessage[]

Initial messages to populate the chat.

onFinish?: (message: UIMessage) => void

Callback when a message completes streaming.

onError?: (error: Error) => void

Callback for handling errors.

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.

`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>
  );
};

chat?: ReturnType<typeof useChat>

The chat helpers from @ai-sdk/react's useChat hook.

options?: AISDKRuntimeAdapter

Optional configuration options.

AISDKRuntimeAdapter

adapters?: RuntimeAdapters

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",
  }),
});

options?: HttpChatTransportInitOptions

Transport configuration options.

HttpChatTransportInitOptions

api?: string

The API endpoint URL.

headers?: Record<string, string> | Headers

Optional headers to include in requests.

credentials?: RequestCredentials

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();
}

tools?: Record<string, unknown>

Frontend tools object forwarded from AssistantChatTransport.

The frontendTools helper converts frontend tool definitions to the AI SDK format and ensures they are properly handled by the streaming response.