AG-UI 客户端负责连接智能体、发送输入并消费事件流。客户端不局限于 Web 页面:终端、移动应用、聊天平台等任何能处理事件并与用户交互的环境都可以成为客户端。
客户端的职责
- 发起运行:向智能体端点提交运行输入(消息、线程/运行 ID、工具、状态等)。
- 接收事件流:通过 SSE/WebSocket 等方式持续接收事件。
- 解释协议事件:按事件类型更新本地会话模型(消息、工具调用、状态、步骤、活动等)。
- 渲染与交互:将更新呈现给用户,并收集用户输入或前端工具执行结果。
- 处理控制流:支持取消、错误展示、中断处理与恢复。
示例:终端客户端思路
官方文档提供了基于 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. 渐进式接入
建议按能力逐步实现:
- 文本流式聊天 + 运行生命周期
- 工具调用展示与(可选)前端工具执行
- 共享状态快照/增量同步
- 人机协同中断、活动/推理/子智能体可视化
- 自定义事件与业务扩展
生产环境提示
从零构建客户端有助于深入理解协议;生产环境可优先评估成熟客户端方案(如 CopilotKit 等)以获得更完整的功能与工程支持。
参考
- 官方文档:Build clients
- 事件机制 与 事件参考
- SDK 与客户端