@assistant-ui/react-ai-sdk
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?:
Configuration options for the chat runtime.
UseChatRuntimeOptions
api?:
The API endpoint URL. Defaults to '/api/chat'.
transport?:
Custom transport implementation. Defaults to AssistantChatTransport which forwards system messages and tools.
cloud?:
Optional AssistantCloud instance for chat persistence.
initialMessages?:
Initial messages to populate the chat.
onFinish?:
Callback when a message completes streaming.
onError?:
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?:
The chat helpers from @ai-sdk/react's useChat hook.
options?:
Optional configuration options.
AISDKRuntimeOptions
cloud?:
Optional AssistantCloud instance for chat persistence.
adapters?:
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?:
Transport configuration options.
HttpChatTransportInitOptions
api?:
The API endpoint URL.
headers?:
Optional headers to include in requests.
credentials?:
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?:
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.