2026 年，AI Agent 已经能查数据库、调接口、发邮件，但很多团队卡在同一个地方：怎么让用户实时看到 Agent 在做什么、做到哪一步、需要什么确认。自己写一套 SSE（Server-Sent Events）推送当然能跑，但每个 Agent 框架、每个前端页面都要重复对接一次，消息含义全靠约定。AG-UI（Agent-User Interaction Protocol）要解决的正是这「最后一公里」——为 Agent 和用户界面之间定义一套标准化的事件语言。
一、为什么自造 SSE 不够：管道有了，语义没有
很多团队会问：SSE 不就是推送吗，为什么要再引入一个协议？关键区别在于，SSE 解决的是「数据怎么传」，AG-UI 解决的是「传过来的数据是什么意思」。这两者的关系，类似 TCP 与 HTTP：TCP 保证可靠传输，HTTP 才规定 GET、POST、状态码与消息语义。
如果每个团队都自定义事件格式，会带来三个现实问题：
- N×M 集成爆炸：N 个 Agent 框架（LangGraph、CrewAI、ADK……）× M 个前端应用，每对组合都要单独适配；
- 语义不可复用：同样是「工具调用开始」，不同后端字段名各不相同，前端无法沉淀通用组件；
- 高级交互缺失：流式文本之外的步骤进度、状态增量、人工审批中断等，往往没有统一表达方式。
AG-UI 的定位就是把这层语义标准化：Agent 运行时发生的一切——开始、思考、调工具、改状态、结束——都以类型化事件的形式流向前端。
二、AG-UI 是什么：Agent 协议栈的第三根支柱
AG-UI 由 CopilotKit 团队于 2025 年 5 月发起，是一个开放、轻量、事件驱动的协议，定义了 Agent 后端与面向用户的应用之间的双向连接方式。行业通常把它与 MCP、A2A 并列，称为 Agent 协议栈的「第三根支柱」：
1.0 是一个重要节点：规范冻结、向后兼容，事件模型从早期版本的 16 种事件扩展为 31 种事件、8 个类别，并新增了子 Agent、推理与活动事件、元数据、多模态工具结果、人机中断（human-in-the-loop）、token 用量上报等能力。对企业的意义在于，AG-UI 从「CopilotKit 的配套协议」变成了可以放心纳入架构图的稳定标准。
三、事件模型：8 类 31 种事件覆盖完整生命周期
AG-UI 把 Agent 运行过程拆成类型化事件，前端按事件类型决定渲染方式。1.0 共定义 31 种事件、8 个类别，主要类别如下：
| 事件类别 | 代表事件 | 前端如何使用 |
|---|---|---|
| 运行与步骤 | RUN_STARTED / RUN_FINISHED / RUN_ERROR / STEP_STARTED / STEP_FINISHED | 控制加载态、进度指示与错误提示 |
| 文本消息 | TEXT_MESSAGE_START / CONTENT / END | 逐字流式渲染回复，支持多段消息 |
| 工具调用 | TOOL_CALL_START / ARGS / END / RESULT | 展示「正在查询订单」等过程卡片与工具结果 |
| 推理过程 | REASONING_START / REASONING_MESSAGE_CONTENT / REASONING_END | 独立展示思维链，不混入回答正文 |
| 状态同步 | STATE_SNAPSHOT / STATE_DELTA / MESSAGES_SNAPSHOT | 快照 + JSON Patch 增量，双向同步界面状态 |
| 活动日志 | ACTIVITY_SNAPSHOT / ACTIVITY_DELTA | 展示文件访问、API 尝试等运行活动 |
| 子 Agent | 子 Agent 生命周期事件（1.0 新增） | 可视化多智能体的委派与执行状态 |
| 自定义与原始 | CUSTOM / RAW | 承载业务自定义事件，或透传框架原始数据 |
一次典型运行的事件流大致如下（简化示意，字段以官方 JSON Schema 为准）：
data: {"type":"RUN_STARTED","threadId":"t-1","runId":"r-1"}
data: {"type":"TOOL_CALL_START","toolCallId":"c-1","toolCallName":"query_orders"}
data: {"type":"TOOL_CALL_ARGS","toolCallId":"c-1","delta":"{\"range\":\"30d\"}"}
data: {"type":"STATE_DELTA","delta":[{"op":"replace","path":"/filter","value":"异常"}]}
data: {"type":"TEXT_MESSAGE_START","messageId":"m-1"}
data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"m-1","delta":"已找到 12 条异常订单"}
data: {"type":"RUN_FINISHED","threadId":"t-1","runId":"r-1"}注意其中的顺序与语义：前端不需要理解业务，只要按事件类型渲染——工具卡片、状态更新、流式文本各归其位。这就是「事件总线」的价值：协议负责语义，应用负责体验。
四、双向交互：不只是推送，更是协作
AG-UI 不是单向通知，它定义了完整的双向协作能力：
Agent 可以调用前端注册的函数，例如「打开订单 #4821」「跳转到结算页」，让智能体真正驱动应用内操作，而不只是输出文字。
遇到退款、下单、删除等敏感操作时，Agent 可暂停运行并请求确认；前端弹出审批界面，用户同意后恢复执行。1.0 将中断/恢复纳入稳定规范。
Agent 可以读写前端状态：读取当前页面、选中项，也可以写入状态触发界面更新。快照用于恢复，增量用于高频同步，断线后也能快速对齐。
子 Agent 的运行状态、随事件下发的元数据、多模态工具结果（图片、文件）以及 token 用量上报，让复杂多智能体系统的可观测性更强。
五、传输与架构：协议不挑管道
AG-UI 是传输无关的：主流实现基于 SSE，也支持 WebSocket，以及面向高性能场景的二进制 protobuf 传输。架构上通常分为三层：
- Agent 层：LangGraph、CrewAI、Google ADK 等运行时，通过官方适配器把执行过程转换为 AG-UI 事件；
- 协议层：客户端通过 HTTP POST 提交统一的 RunAgentInput，服务端以 text/event-stream 流式返回类型化事件；
- 客户端层：CopilotKit 或自研客户端消费事件，完成状态应用、消息历史管理与组件渲染。
这意味着企业不需要推翻现有基础设施：AG-UI 是消息契约，不是新的网关。原有的鉴权、限流、日志体系仍然适用，只是消息体从「自定义 JSON」变成了标准事件。
六、生态：15+ 框架，前端开箱即用
AG-UI 的生态是它最现实的竞争力。后端侧，官方集成覆盖 LangGraph（Python/TypeScript）、CrewAI、Mastra、Agno、Google ADK、AWS Strands、PydanticAI、LlamaIndex、Claude Agent SDK 等 15+ 主流框架；前端侧，CopilotKit 提供 React、Angular、Vue、React Native 客户端，并可延伸到 Slack、Teams、WhatsApp、Telegram、Discord 等渠道。官方还维护了 AG-UI Dojo，用 30 个在线示例演示不同框架下的 Agent 交互能力。
对企业的直接好处是：Agent 框架可以换，前端交互协议不用换。今天用 LangGraph 原型验证，明天切换到自研运行时，前端的事件处理与交互组件都能复用。
七、AG-UI 在协议版图中的位置
把四个协议放进同一张图，分工一目了然：
| 协议 | 连接的双方 | 核心职责 |
|---|---|---|
| MCP | Agent ↔ 工具 / 数据 | 让 Agent 能调用外部能力、读取上下文 |
| A2A | Agent ↔ Agent | 任务发现、委托与协作 |
| AG-UI | Agent ↔ 用户应用 | 事件流、状态同步、人机协同 |
| A2UI | Agent → 界面 | 用声明式 JSON 描述要渲染的 UI |
行业里有一个好记的比喻：AG-UI 是管道，A2UI 是载荷。A2UI 官方把 AG-UI 列为标准传输绑定之一；Oracle 在集成方案中也把 AG-UI 描述为「自定义前端可选的事件传输层」。也就是说，两者不是二选一，而是天然可以组合：AG-UI 负责把消息送到前端，A2UI 负责告诉前端渲染什么。详细对比可以阅读《A2UI 和 AG-UI 有什么区别》。
八、落地建议：什么时候该用 AG-UI
如果你们的 Agent 应用符合以下任意两条，就值得引入 AG-UI：需要流式输出与步骤进度；需要把工具调用过程可视化；需要 Agent 与页面状态双向同步；需要人工审批中断；需要支持多个 Agent 框架或多种前端。反之，如果只是一个单轮问答接口，自建 SSE 也够用，不必为协议而协议。
从零落地可以按这条路径走：
- 先对齐事件语义：把现有自定义事件映射到 AG-UI 生命周期、文本、工具、状态四类事件，理清顺序与幂等性；
- 保留 CUSTOM 通道：业务特有事件先走
CUSTOM，不要急着扩展协议，保持与标准的兼容； - 状态用「快照 + 增量」：初次连接发快照，后续只发 JSON Patch 增量，既省带宽也便于断线恢复；
- 把 HITL 设计进流程：敏感动作默认中断确认，明确「Agent 提议、用户授权」的权限边界；
- 锁定 1.0 并建立回归用例：用官方 Schema 校验事件，升级前跑一遍事件序列回归，避免协议演进带来的隐性破坏。
常见问题
Q1：AG-UI 和 A2UI 是竞争关系吗？
不是。AG-UI 是管道，负责 Agent 与前端之间的事件流与语义；A2UI 是载荷，负责描述界面长什么样。两者互补：可以由 AG-UI 传输 A2UI 消息，前端渲染器再把界面画出来。一个管「怎么传」，一个管「传什么」。
Q2：使用 AG-UI 必须搭配 CopilotKit 吗？
不必。AG-UI 是开放协议，规范、JSON Schema 与多语言 SDK 均公开，任何前端技术栈都可以实现客户端。CopilotKit 提供的是开箱即用的 React/Angular/Vue/React Native 客户端与组件，负责事件应用、状态管理和消息历史，适合快速落地。
Q3：AG-UI 1.0 与早期版本兼容吗？
兼容。AG-UI 1.0 于 2026 年 9 月 30 日发布，官方明确向后兼容，并提供迁移指南。1.0 在原有事件模型上新增了子 Agent、元数据、多模态工具结果、人机中断与 token 用量上报等能力，已有 Agent 与前端可以按原方式继续运行。
AG-UI 解决的是 Agent 产品的「体验基础设施」：让用户看得见、控得住、接得上。它与 A2UI 组合，前者传输、后者描述，构成了 Agent 驱动界面的完整链路。想理解 Agent 本身如何规划与执行，可以继续阅读《什么是 AI Agent（智能体）》和《什么是 Agent Skills》。鲸点无疑的 FDE 团队正在帮助客户把这些协议落到真实业务系统中——了解我们的 AI 落地服务。