跳到主要内容

核心架构

深入理解 AG-UI 的客户端-服务端模型、事件驱动通信、传输层与协议分层。

AG-UI 定义了智能体后端与用户应用之间的标准交互架构:通过事件流输出执行过程,通过兼容输入接收用户与应用侧信息。

架构概览

典型部署中,AG-UI 连接以下组件:

  • 应用(Application):面向用户的界面,如 Web 聊天、Copilot 面板、终端或聊天平台机器人。
  • AG-UI 客户端(Client):负责协议通信的组件/SDK(如 HTTP Agent 客户端或特定集成客户端)。
  • 智能体后端(Agent / Server):执行推理与工具调用的服务,可由框架实现或自研。
  • 安全代理/网关(可选):用于鉴权、路由、多智能体接入或协议转换。

通信方向是双向的:客户端向智能体发送运行输入;智能体向客户端持续推送事件流。

设计原则

  1. 事件驱动通信:智能体在执行期间发出标准化事件,客户端按事件更新 UI 与状态。
  2. 双向交互:支持用户输入、前端工具结果、审批与中断响应等回传。
  3. 轻量与低约束:协议尽量减少对实现细节的强制要求,便于适配多种框架。
  4. 传输灵活:同一语义可承载于 SSE、WebSocket、Webhook 等不同传输方式。
  5. 可兼容与可扩展:支持宽松格式匹配、原生事件转换,以及 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,并处理断线与重试。
  • 兼容性:对未知事件类型保持前向兼容(记录/忽略但不中断主流程,视需求而定)。

Type to search…

↑↓ navigate↵ selectEsc close