assistant-ui

assistant-ui

请务必查看 assistant-ui.com/llms.txt，以获取最新 API。

用于 AI 聊天界面的 React 库：无样式基元、样式化元素目录、适配任意后端的运行时，以及可选的云端持久化功能。当前版本系列为基于 AI SDK v7 的 @assistant-ui/react 0.15.x，通过 @assistant-ui/ai-sdk 集成。

参考资料

• ./references/architecture.md -- 分层、aui 客户端、数据流、消息模型
• ./references/packages.md -- 所有已发布的软件包及其安装时机

适用场景

使用场景	推荐选择
快速搭建聊天 UI	执行 npx assistant-ui@latest create，然后使用 thread 元素
完全掌控标记	基元（ThreadPrimitive、ComposerPrimitive、MessagePrimitive）
现有 AI 后端	运行时适配器（AI SDK、LangGraph、LangChain、ADK、A2A、AG-UI、Eve、OpenCode）或 useLocalRuntime
带 UI 的工具	"use generative" 工具包、工具 UI、生成式 UI
多线程应用	线程列表元素，以及 Assistant Cloud 或你自己的适配器
应用中的副驾驶	指令、上下文、可见组件、可交互元素
移动端或终端	@assistant-ui/react-native、@assistant-ui/react-ink

架构

┌──────────────────────────────────────────────────────────────┐
│  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     │
└──────────────────────────────────────────────────────────────┘

选择运行时

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

核心软件包

软件包	用途
@assistant-ui/react	基元、钩子、运行时、提供程序
@assistant-ui/ai-sdk	AI SDK v7 集成（useChatRuntime、AssistantChatTransport、AISDKToolkit、frontendTools）
@assistant-ui/core	React、React Native、Ink 共用的框架无关运行时
@assistant-ui/store	AuiConfig、AuiProvider、useAui 状态层
@assistant-ui/react-markdown	Markdown 渲染（MarkdownTextPrimitive）
assistant-stream	流式传输协议、编码器、可恢复流
assistant-cloud	Assistant Cloud 客户端
assistant-ui	CLI（create、init、add、update、upgrade、doctor、mcp、agent）

@assistant-ui/react-ai-sdk 会为旧版安装重新导出 @assistant-ui/ai-sdk；新代码应从 @assistant-ui/ai-sdk 导入。样式化组件不属于任何软件包：npx assistant-ui@latest add thread 会将它们复制到 components/assistant-ui/elements/。完整清单请参阅 ./references/packages.md。

快速开始

"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() 会通过 AssistantChatTransport 向 /api/chat 发送请求，该传输还会转发前端工具和系统指令。传入 new AssistantChatTransport({ api }) 可更改端点。

状态访问

aui 上的作用域访问器是属性；作用域上的方法仍需保留括号。每个选择器都只返回一个基本值或稳定引用。

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 }) => {});

提供作用域

工具、建议、可交互元素、MCP 管理器及其他作用域通过 AuiConfig 声明，并传递给提供程序；useAui() 不接受参数。

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>;

嵌套作用域使用 <AuiProvider extends={useAui()} config={config}>；独立根节点使用 extends={null}。

相关技能

• setup -- CLI、模板、运行时适配器、平台
• elements -- 样式化组件目录，以及安装和覆盖组件的方法
• primitives -- 无样式构建模块和 composer 功能
• runtime -- 运行时、aui 客户端、适配器、事件
• tools -- 工具包、工具 UI、审批、MCP、WebMCP
• generative-ui -- present 工具和组件词汇
• streaming -- assistant-stream、传输方式、可恢复流
• cloud -- Assistant Cloud 持久化和身份验证
• thread-list -- 多会话管理
• copilots -- 将助手与应用关联
• markdown -- Markdown、代码、数学、图表
• react-mcp -- 用户管理的 MCP 服务
• observability -- 跟踪和 Span 可视化
• react-native -- Expo 和 React Native
• ink -- 使用 Ink 进行终端聊天
• update -- 升级和迁移