assistant-ui

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

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

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