assistant-ui 概览
开源 React AI 聊天界面组件库，Radix 风格组合式原语架构，支持流式响应、工具调用渲染、多后端运行时。
#type / concept
#status / evergreen
#tech / dev / frontend
#tech / ai
[!info] related notes
- AI 聊天 UI 设计: ai-chat-ui-assistant-ui
- Thread 原语: Thread & Message 原语
- Composer 原语: Composer 原语
- ActionBar 原语: ActionBar & BranchPicker 原语
- Runtime 架构: Runtime 架构与后端集成
assistant-ui 概览
开源 React 组件库，将 ChatGPT 级别的聊天体验带入你的 React 应用。MIT 协议，Y Combinator 孵化。
核心特点
| 特性 | 说明 |
|---|---|
| 组合式原语 | Thread、Message、Composer、ActionBar 等独立原语，自由组合 |
| 流式打字机 | 原生支持 SSE 流式响应，逐 token 渲染 |
| 工具调用渲染 | function calling 结果渲染为 React 组件，支持人工审批 |
| 多后端运行时 | 通过运行时抽象层切换 Vercel AI SDK / LangGraph / 自定义后端 |
| TypeScript 强类型 | 运行时 API、工具 schema、消息 part 全部类型化 |
| shadcn/ui 集成 | CLI 一键添加预样式组件到项目 |
安装
# 新项目
npx assistant-ui@latest create
# 已有项目
npx assistant-ui@latest init
# 手动安装
npm install @assistant-ui/react @assistant-ui/react-ai-sdk架构分层
┌─────────────────────────────────┐
│ 预构建 UI 组件 (shadcn Thread) │ ← 开箱即用
├─────────────────────────────────┤
│ 原语 (Primitives) │ ← ThreadPrimitive, MessagePrimitive...
├─────────────────────────────────┤
│ 运行时 (Runtime) │ ← useChatRuntime, useLangGraphRuntime...
├─────────────────────────────────┤
│ 后端集成 (Adapters) │ ← Vercel AI SDK, LangGraph, 自定义 SSE
└─────────────────────────────────┘Radix 风格：每个原语都是独立的 headless 组件，开发者掌控布局和样式，原语负责行为和状态管理。
原语一览
| 原语 | 职责 |
|---|---|
ThreadPrimitive | 可滚动消息容器、自动滚动、空状态 |
MessagePrimitive | 单条消息渲染、内容 part 分发、hover 状态 |
ComposerPrimitive | 输入框、提交、附件、语音输入 |
ActionBarPrimitive | 消息级操作按钮（复制、重试、编辑、反馈） |
BranchPickerPrimitive | 多分支回复导航（重新生成/编辑后） |
ThreadListPrimitive | 多会话列表管理 |
后端集成
| 集成 | 包名 |
|---|---|
| Vercel AI SDK | @assistant-ui/react-ai-sdk |
| LangGraph | @assistant-ui/react-langgraph |
| LangChain | @assistant-ui/react-langchain |
| AG-UI 协议 | @assistant-ui/react-ag-ui |
| Google ADK | @assistant-ui/react-google-adk |
| 自定义数据流 | @assistant-ui/react-data-stream |
| 托管云服务 | assistant-cloud |
基础用法
// app/page.tsx
import { Thread } from "@/components/assistant-ui/thread";
import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
export default function ChatPage() {
const runtime = useChatRuntime({
api: "/api/chat", // 后端 API 路由
});
return (
<AssistantRuntimeProvider runtime={runtime}>
<Thread />
</AssistantRuntimeProvider>
);
}优雅之处：
- 所有原语共享同一个
AssistantRuntimeProvider上下文，状态管理自动完成 - 运行时可热切换——从 Vercel AI SDK 换到 LangGraph 只改一行
- 预构建组件可逐步替换为自定义原语，无需重写整个架构