assistant-ui

assistant-ui

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

React library for AI chat interfaces: unstyled primitives, a styled elements catalog, a runtime that adapts any backend, and optional cloud persistence. Current line is @assistant-ui/react 0.15.x on AI SDK v7 through @assistant-ui/ai-sdk.

References

• ./references/architecture.md -- layers, the aui client, data flow, message model
• ./references/packages.md -- every published package and when to install it

When to Use

Use Case	Reach for
Chat UI in an afternoon	npx assistant-ui@latest create, then the thread element
Full control over markup	Primitives (ThreadPrimitive, ComposerPrimitive, MessagePrimitive)
Existing AI backend	A runtime adapter (AI SDK, LangGraph, LangChain, ADK, A2A, AG-UI, Eve, OpenCode) or useLocalRuntime
Tools with UI	"use generative" toolkits, tool UI, generative UI
Multi-thread apps	Thread list elements plus Assistant Cloud or your own adapter
Copilots in an app	Instructions, context, visible components, interactables
Mobile or terminal	@assistant-ui/react-native, @assistant-ui/react-ink

Architecture

┌──────────────────────────────────────────────────────────────┐
│  Elements (styled, copied into components/assistant-ui/)     │
│  Primitives (unstyled, @assistant-ui/react)                  │
└───────────────────────────┬──────────────────────────────────┘
                            │ read state, call actions
┌───────────────────────────▼──────────────────────────────────┐
│  aui client: useAui, useAuiState, useAuiEvent, AuiIf         │
│  scopes provided by AuiConfig through AssistantRuntimeProvider│
│  or AuiProvider (@assistant-ui/store on @assistant-ui/tap)   │
└───────────────────────────┬──────────────────────────────────┘
                            │
┌───────────────────────────▼──────────────────────────────────┐
│  Runtime: AssistantRuntime → ThreadRuntime → MessageRuntime  │
│  (@assistant-ui/core, framework neutral)                     │
└───────────────────────────┬──────────────────────────────────┘
                            │
┌───────────────────────────▼──────────────────────────────────┐
│  Adapters and backends: AI SDK · LangGraph · LangChain · ADK │
│  A2A · AG-UI · Eve · OpenCode · custom · Assistant Cloud     │
└──────────────────────────────────────────────────────────────┘

Pick a Runtime

Vercel AI SDK?
├─ Yes → useChatRuntime from @assistant-ui/ai-sdk (recommended)
└─ No
   ├─ LangGraph server → useLangGraphRuntime (@assistant-ui/react-langgraph)
   ├─ LangChain / LangGraph useStream → useStreamRuntime (@assistant-ui/react-langchain)
   ├─ Google ADK → useAdkRuntime (@assistant-ui/react-google-adk)
   ├─ A2A protocol → useA2ARuntime (@assistant-ui/react-a2a)
   ├─ AG-UI protocol → useAgUiRuntime (@assistant-ui/react-ag-ui)
   ├─ Eve agents → useEveAgentRuntime (@assistant-ui/eve)
   ├─ OpenCode → useOpenCodeRuntime (@assistant-ui/react-opencode)
   ├─ Claude Managed Agents → useExternalStoreRuntime + useRemoteThreadListRuntime
   ├─ State already in Redux/Zustand/your store → useExternalStoreRuntime
   ├─ Custom endpoint speaking Assistant Transport → useAssistantTransportRuntime
   └─ Any other custom API → useLocalRuntime with a ChatModelAdapter

Core Packages

Package	Purpose
@assistant-ui/react	Primitives, hooks, runtimes, provider
@assistant-ui/ai-sdk	AI SDK v7 integration (useChatRuntime, AssistantChatTransport, AISDKToolkit, frontendTools)
@assistant-ui/core	Framework-neutral runtime shared by React, React Native, Ink
@assistant-ui/store	AuiConfig, AuiProvider, useAui state layer
@assistant-ui/react-markdown	Markdown rendering (MarkdownTextPrimitive)
assistant-stream	Streaming protocol, encoders, resumable streams
assistant-cloud	Assistant Cloud client
assistant-ui	The CLI (create, init, add, update, upgrade, doctor, mcp, agent)

@assistant-ui/react-ai-sdk re-exports @assistant-ui/ai-sdk for older installs; new code imports from @assistant-ui/ai-sdk. Styled components are not a package: npx assistant-ui@latest add thread copies them into components/assistant-ui/elements/. See ./references/packages.md for the full inventory.

Quick Start

"use client";

import { AssistantRuntimeProvider } from "@assistant-ui/react";
import { useChatRuntime } from "@assistant-ui/ai-sdk";
import { Thread } from "@/components/assistant-ui/elements/thread.aui";

export default function Chat() {
  const runtime = useChatRuntime();
  return (
    <AssistantRuntimeProvider runtime={runtime}>
      <Thread />
    </AssistantRuntimeProvider>
  );
}

useChatRuntime() posts to /api/chat through AssistantChatTransport, which also forwards frontend tools and system instructions. Pass new AssistantChatTransport({ api }) to change the endpoint.

State Access

Scope accessors on aui are properties; methods on a scope keep their parentheses. Selectors return one primitive or stable reference each.

import { useAui, useAuiState, useAuiEvent } from "@assistant-ui/react";

const aui = useAui();
aui.thread.append({ role: "user", content: [{ type: "text", text: "Hi" }] });
aui.thread.cancelRun();
aui.thread.composer().send();
aui.threads.switchToNewThread();

const messages = useAuiState((s) => s.thread.messages);
const isRunning = useAuiState((s) => s.thread.isRunning);

useAuiEvent("threads.selectionChanged", ({ threadId, previousThreadId }) => {});

Providing Scopes

Tools, suggestions, interactables, MCP managers, and other scopes are declared with AuiConfig and handed to the provider; useAui() takes no arguments.

import { AssistantRuntimeProvider, AuiConfig, Suggestions, Tools } from "@assistant-ui/react";
import { useChatRuntime } from "@assistant-ui/ai-sdk";
import toolkit from "./toolkit";

const runtime = useChatRuntime();
const config = AuiConfig({
  tools: Tools({ toolkit }),
  suggestions: Suggestions(["What can you do?", "Summarize this page"]),
});

<AssistantRuntimeProvider runtime={runtime} config={config}>{children}</AssistantRuntimeProvider>;

Nested scopes use <AuiProvider extends={useAui()} config={config}>; an isolated root uses extends={null}.

Related Skills

• setup -- CLI, templates, runtime adapters, platforms
• elements -- the styled component catalog and how to install and override it
• primitives -- unstyled building blocks and composer features
• runtime -- runtimes, the aui client, adapters, events
• tools -- toolkits, tool UI, approvals, MCP, WebMCP
• generative-ui -- the present tool and component vocabularies
• streaming -- assistant-stream, transports, resumable streams
• cloud -- Assistant Cloud persistence and auth
• thread-list -- multi-thread management
• copilots -- grounding the assistant in your app
• markdown -- markdown, code, math, diagrams
• react-mcp -- user-managed MCP servers
• observability -- tracing and span visualization
• react-native -- Expo and React Native
• ink -- terminal chat with Ink
• update -- upgrades and migrations