assistant-ui

Overview and router for assistant-ui, the React library for building AI chat interfaces from composable primitives and a styled elements catalog. Use for high-level, cross-cutting, or architecture questions: choosing packages, picking a runtime, or understanding the layers (elements, primitives, the aui client with AuiConfig and AuiProvider, the runtime, adapters) and the message model. Covers `@assistant-ui/react` 0.15.x, `@assistant-ui/ai-sdk` for AI SDK v7 (`useChatRuntime`), `@assistant-ui/core`, `@assistant-ui/store`, `assistant-stream`, `assistant-cloud`, the LangGraph, LangChain, Google ADK, A2A, AG-UI, Eve, OpenCode, and Pi adapters, the `@assistant-ui/react-native` and `@assistant-ui/react-ink` bindings, and the `useAui`, `useAuiState`, and `useAuiEvent` hooks. For a specific area route to a focused sibling instead: setup, elements, primitives, runtime, tools, generative-ui, streaming, cloud, thread-list, copilots, markdown, react-mcp, observability, react-native, ink, or update.

Quality

92%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

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

Repository: stevenknowswhy/ProfessionalBuyer
Path: .claude/skills/assistant-ui/SKILL.md
Commit: 92cff92

Last updated: 4 hours ago
First committed: 11 hours ago

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.