assistant-ui

Always consult assistant-ui.com/llms.txt for the latest API.

React library for building AI chat interfaces with composable primitives.

References

• ./references/architecture.md -- Core architecture and layered system
• ./references/packages.md -- Package overview and selection guide

When to Use

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

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