跳到主要内容

构建客户端

从零实现 AG-UI 客户端,消费事件流并构建终端、Web 或其他形态的交互界面。

AG-UI 客户端负责连接智能体、发送输入并消费事件流。客户端不局限于 Web 页面:终端、移动应用、聊天平台等任何能处理事件并与用户交互的环境都可以成为客户端。

客户端的职责

  1. 发起运行:向智能体端点提交运行输入(消息、线程/运行 ID、工具、状态等)。
  2. 接收事件流:通过 SSE/WebSocket 等方式持续接收事件。
  3. 解释协议事件:按事件类型更新本地会话模型(消息、工具调用、状态、步骤、活动等)。
  4. 渲染与交互:将更新呈现给用户,并收集用户输入或前端工具执行结果。
  5. 处理控制流:支持取消、错误展示、中断处理与恢复。

示例:终端客户端思路

官方文档提供了基于 Mastra 与 OpenAI 的 CLI 客户端示例(展示如何连接智能体、实现工具并在终端交互)。典型步骤包括:

  • 准备环境:Node.js(示例要求较新版本)、包管理器(如 pnpm)、API Key
  • 安装依赖并配置智能体(如 @ag-ui/mastra、模型与工具)
  • 建立事件订阅循环,将 TEXT_MESSAGE_* 渲染为流式输出
  • 处理工具调用事件,在本地执行工具并将结果回传

具体代码与命令请以官方 Quickstart:Build clients 文档为准。

实现建议

1. 会话与状态模型

建议在客户端维护统一状态,例如:

  • 消息列表(含角色、内容、进行中状态)
  • 工具调用表(按 toolCallId 聚合参数流与结果)
  • 共享应用状态(由 STATE_SNAPSHOT/DELTA 驱动)
  • 当前运行状态(runId、步骤、错误、中断信息)

2. 事件分发与聚合

  • 为每类事件实现处理器,避免在单一回调中堆叠复杂逻辑。
  • 对流式事件(文本、工具参数、推理消息)按 ID 进行增量拼接。
  • 收到 *_END 或运行结束事件时完成收尾与 UI 状态切换。

3. 健壮性

  • 处理网络断开、超时与重连策略(按产品需求)。
  • 对未知/自定义事件保留可观测记录,避免阻塞主流程。
  • 在 RUN_ERROR 或中断结果时提供明确的用户反馈与恢复路径。

4. 渐进式接入

建议按能力逐步实现:

  1. 文本流式聊天 + 运行生命周期
  2. 工具调用展示与(可选)前端工具执行
  3. 共享状态快照/增量同步
  4. 人机协同中断、活动/推理/子智能体可视化
  5. 自定义事件与业务扩展

生产环境提示

从零构建客户端有助于深入理解协议;生产环境可优先评估成熟客户端方案(如 CopilotKit 等)以获得更完整的功能与工程支持。

参考

Type to search…

↑↓ navigate↵ selectEsc close