Skip to main content
assistant-ui 是一个用于 AI 聊天的无头 React UI 框架。它提供了一个完整的运行时层——包括线程管理、消息分支、附件处理——通过 useExternalStoreRuntime 适配器连接到 useStream
克隆并运行 完整的 assistant-ui 示例,查看一个使用 useExternalStoreRuntime 连接到 LangChain 代理的 Claude 风格聊天界面。

工作原理

  1. 使用 useStream 进行流式传输 — 连接到你的代理,获取响应式消息、加载状态以及提交/取消回调
  2. 使用 useExternalStoreRuntime 进行适配 — 通过将 BaseMessage[] 转换为 ThreadMessageLike[],将 stream.messages 桥接到 assistant-ui 的运行时格式
  3. 提供运行时 — 将你的 UI 包装在 AssistantRuntimeProvider 中,并渲染任何 assistant-ui 线程组件

安装

连接 useStream

useExternalStoreRuntime 适配器将 stream.messages 桥接到 assistant-ui 运行时。将其传递给 AssistantRuntimeProvider 并渲染任何线程组件:

转换消息

toThreadMessages 将 LangChain 的 BaseMessage[] 映射到 assistant-ui 期望的 ThreadMessageLike[] 格式。处理每种消息类型——人类、AI 和工具——并转换内容块、工具调用和推理令牌:

自定义线程 UI

<Thread /> 提供了一个完整的默认线程 UI,包括消息列表、编辑器和滚动管理。通过覆盖组件插槽来自定义各个部分:

最佳实践

  • 记忆化消息转换:toThreadMessages(stream.messages) 包装在 useMemo 中,以避免在每次渲染时重新运行转换
  • 处理附件: 使用 CompositeAttachmentAdapter 配合 SimpleImageAttachmentAdapter 处理图片上传;通过自定义适配器扩展文件处理
  • 使用分支: assistant-ui 通过 MessageBranch 内置了消息分支支持;编辑消息可从该点重新生成
  • 线程持久化: 使用 fetchStateHistory: truereconnectOnMount: trueuseStream 可让 assistant-ui 在页面加载时访问完整的线程历史记录