| name | assistant-ui |
| description | Overview and router for assistant-ui, the React library for building AI chat interfaces from composable primitives. Use for high-level, cross-cutting, or architecture-overview questions: choosing packages, picking a runtime, or understanding the layered model (RuntimeCore, Runtime, the aui client, primitives) and message model. Covers the `@assistant-ui/react` core plus `@assistant-ui/react-ai-sdk`, `@assistant-ui/react-langchain`, `@assistant-ui/react-langgraph`, `assistant-stream`, and `assistant-cloud`, and the platform bindings `@assistant-ui/react-native` and `@assistant-ui/react-ink`; `AssistantRuntimeProvider`; the primitives `ThreadPrimitive`, `MessagePrimitive`, `ComposerPrimitive`; the hooks `useAui`, `useAuiState`, `useAuiEvent`; and runtime selection across `useChatRuntime`, `useExternalStoreRuntime`, `useLangGraphRuntime`, `useLocalRuntime`. Current line is `@assistant-ui/react` 0.15.x on AI SDK v7. For a specific area route to a focused sibling instead: setup, runtime, primitives, tools, streaming, cloud, thread-list, copilots, markdown, react-mcp, observability, or update. Not for hands-on tasks already owned by those siblings. |
| license | MIT |
assistant-ui
Always consult assistant-ui.com/llms.txt for the latest API.
React library for building AI chat interfaces with composable primitives.
References
When to Use
| Use Case | Best For |
|---|
| Chat UI from scratch | Full control over UX |
| Existing AI backend | Connects to any streaming backend |
| Custom message types | Tools, images, files, custom parts |
| Multi-thread apps | Built-in thread list management |
| Production apps | Cloud persistence, auth, analytics |
Architecture
┌─────────────────────────────────────────────────────────┐
│ UI Components (Primitives) │
│ ThreadPrimitive, MessagePrimitive, ComposerPrimitive │
└─────────────────────────┬───────────────────────────────┘
│
┌─────────────────────────▼───────────────────────────────┐
│ aui client + hooks │
│ useAui, useAuiState, useAuiEvent │
└─────────────────────────┬───────────────────────────────┘
│
┌─────────────────────────▼───────────────────────────────┐
│ Runtime Layer │
│ AssistantRuntime → ThreadRuntime → MessageRuntime │
└─────────────────────────┬───────────────────────────────┘
│
┌─────────────────────────▼───────────────────────────────┐
│ Adapters/Backend │
│ AI SDK · LangGraph · Custom · Cloud Persistence │
└─────────────────────────────────────────────────────────┘
Pick a Runtime
Using AI SDK?
├─ Yes → useChatRuntime (recommended)
└─ No
├─ External state (Redux/Zustand)? → useExternalStoreRuntime
├─ LangGraph agent? → useLangGraphRuntime
├─ AG-UI protocol? → useAgUiRuntime
├─ A2A protocol? → useA2ARuntime
└─ Custom API → useLocalRuntime
Core Packages
| Package | Purpose |
|---|
@assistant-ui/react | UI primitives & hooks |
@assistant-ui/core | Framework-agnostic core runtime |
@assistant-ui/store | useAui / AuiProvider state layer |
@assistant-ui/react-ai-sdk | Vercel AI SDK v7 adapter |
@assistant-ui/react-langchain | LangChain / LangGraph useStream adapter |
@assistant-ui/react-markdown | Markdown rendering |
assistant-stream | Streaming protocol |
assistant-cloud | Cloud persistence |
Non-web targets: @assistant-ui/react-native (Expo) and @assistant-ui/react-ink (terminal). See ./references/packages.md for the full inventory.
Quick Start
import { AssistantRuntimeProvider } from "@assistant-ui/react";
import { Thread } from "@/components/assistant-ui/thread";
import { useChatRuntime, AssistantChatTransport } from "@assistant-ui/react-ai-sdk";
function App() {
const runtime = useChatRuntime({
transport: new AssistantChatTransport({ api: "/api/chat" }),
});
return (
<AssistantRuntimeProvider runtime={runtime}>
<Thread />
</AssistantRuntimeProvider>
);
}
State Access
Scope accessors on aui are properties (0.15+); methods on a scope keep their parentheses.
import { useAui, useAuiState } from "@assistant-ui/react";
const aui = useAui();
aui.thread.append({ role: "user", content: [{ type: "text", text: "Hi" }] });
aui.thread.cancelRun();
aui.thread.composer().send();
const messages = useAuiState(s => s.thread.messages);
const isRunning = useAuiState(s => s.thread.isRunning);
Related Skills
/setup - Installation and configuration/primitives - UI component customization/runtime - State management deep dive/tools - Tool registration and UI/streaming - Streaming protocols/cloud - Persistence and auth/thread-list - Multi-thread management/copilots - Grounding the assistant in your app/markdown - Markdown rendering/react-mcp - User-managed MCP servers/observability - Backend tracing and telemetry/update - Version updates and migrations
