AG-UI 定义了智能体后端与用户应用之间的标准交互架构:通过事件流输出执行过程,通过兼容输入接收用户与应用侧信息。
架构概览
典型部署中,AG-UI 连接以下组件:
- 应用(Application):面向用户的界面,如 Web 聊天、Copilot 面板、终端或聊天平台机器人。
- AG-UI 客户端(Client):负责协议通信的组件/SDK(如 HTTP Agent 客户端或特定集成客户端)。
- 智能体后端(Agent / Server):执行推理与工具调用的服务,可由框架实现或自研。
- 安全代理/网关(可选):用于鉴权、路由、多智能体接入或协议转换。
通信方向是双向的:客户端向智能体发送运行输入;智能体向客户端持续推送事件流。
设计原则
- 事件驱动通信:智能体在执行期间发出标准化事件,客户端按事件更新 UI 与状态。
- 双向交互:支持用户输入、前端工具结果、审批与中断响应等回传。
- 轻量与低约束:协议尽量减少对实现细节的强制要求,便于适配多种框架。
- 传输灵活:同一语义可承载于 SSE、WebSocket、Webhook 等不同传输方式。
- 可兼容与可扩展:支持宽松格式匹配、原生事件转换,以及
RAW/CUSTOM扩展。
运行与事件模型
一次智能体运行通常由生命周期事件界定:
RUN_STARTED:运行开始,建立runId/threadId等上下文- 运行过程中:发出文本、工具、状态、步骤、活动、推理、子智能体等事件
RUN_FINISHED或RUN_ERROR:运行结束(成功、失败或中断结果,视协议版本与实现而定)
客户端应将事件流归并为一致的会话状态模型,以支持实时渲染、回放与错误恢复。
核心事件类别(概览)
| 类别 | 典型事件 | 用途 |
|---|---|---|
| 生命周期 | RUN_STARTED, RUN_FINISHED, RUN_ERROR, STEP_* |
标识运行与步骤边界 |
| 文本消息 | TEXT_MESSAGE_START/CONTENT/END 等 |
流式文本输出 |
| 工具调用 | TOOL_CALL_START/ARGS/END/RESULT 等 |
工具执行与结果传递 |
| 状态管理 | STATE_SNAPSHOT, STATE_DELTA, MESSAGES_SNAPSHOT |
共享状态与消息同步 |
| 活动 | ACTIVITY_SNAPSHOT, ACTIVITY_DELTA |
结构化进行中活动展示 |
| 推理 | REASONING_* |
可展示的推理/过程信息 |
| 子智能体 | SUBAGENT_STARTED/FINISHED/ERROR |
子智能体生命周期与归因 |
| 特殊/扩展 | RAW, CUSTOM |
外部事件透传与自定义扩展 |
输入与双向能力
客户端向智能体提交的输入通常包含(具体以 SDK/实现为准):
- 会话标识与运行参数
- 用户消息与历史上下文
- 可用工具定义(包括前端可执行工具)
- 共享状态与应用上下文
- 中断恢复时的用户响应
这使得智能体不仅能“输出”,还能在执行中请求前端动作或人工介入。
与 MCP / A2A 的关系
- MCP 解决智能体如何访问工具与数据源。
- A2A 解决智能体之间如何通信与协作。
- AG-UI 解决智能体如何与最终用户及其界面交互。
三者可在同一系统中分层协作:智能体通过 MCP 使用工具、通过 A2A 协同其他智能体、通过 AG-UI 向用户呈现过程并接收反馈。
实现建议
- 后端/集成端:优先保证生命周期与消息流正确闭合,再逐步扩展工具、状态与中断能力。
- 客户端:以事件 ID 为键聚合流式增量,维护单一可信的会话状态源。
- 传输层:根据实时性与部署环境选择 SSE 或 WebSocket,并处理断线与重试。
- 兼容性:对未知事件类型保持前向兼容(记录/忽略但不中断主流程,视需求而定)。