@assistant-ui/react-ai-sdk

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

Vercel AI SDK integration for assistant-ui.

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

API Reference

`useChatRuntime`

Creates a runtime directly with AI SDK v5'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

api?: string

The API endpoint URL. Defaults to '/api/chat'.

transport?: ChatTransport

Custom transport implementation. Defaults to AssistantChatTransport which forwards system messages and tools.

cloud?: AssistantCloud

Optional AssistantCloud instance for chat persistence.

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?: AISDKRuntimeOptions

Optional configuration options.

AISDKRuntimeOptions

cloud?: AssistantCloud

Optional AssistantCloud instance for chat persistence.

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