一文读懂 AG-UI 协议：AI Agent 与前端交互的新标准

三月 9, 2026 | 技术

在 AI Agent 应用开发中，如何让前端与后端 Agent 高效通信一直是个难题。AG-UI 协议的出现就是为了解决这个核心问题。本文将详细介绍 AG-UI 是什么、为什么这样设计，以及它与以往流式输出的区别。

什么是 AG-UI ？

AG-UI（Agent User Interaction Protocol）是一个开放、轻量级、基于事件的标准协议，用于规范 AI Agent 与前端应用之间的通信方式。

它由 CopilotKit 提出，来源于 LangGraph、CrewAI 等项目的生产实践经验，旨在解决 Agent 特有的交互模式问题。

核心定位

AG-UI 是构建在传统 Web 协议（HTTP、WebSocket）之上的抽象层，专为代理时代设计——桥接传统客户端-服务器架构与 AI Agent 的动态、状态ful 特性。

解决了什么问题？

1. 通信碎片化

在没有标准之前，每个 AI 应用都自己定义接口：

A 公司返回 text，B 公司返回 message
有的用 WebSocket，有的用 SSE，有的用轮询
前端无法知道 AI 正在"思考"还是"执行工具"

2. 传统模式的局限性

函数 vs Agent 的区别：

函数：输入→处理→输出，边界清晰
Agent：动态的、长时间运行、状态ful、需要多步执行

传统的请求-响应模式无法满足 Agent 的交互需求。

3. 前后端强耦合

每个 AI 应用都需要为特定后端定制前端，难以复用。

与以往流式数据的区别

以前的流式输出

以前确实有流式，但只是文本内容的流式，且格式混乱：

OpenAI o1:    {"choices":[{"delta":{"reasoning_content":"...思考..."}}]}
Claude:       {"choices":[{"delta":{"thinking":"...思考..."}}]}
某国产模型:   {"choices":[{"delta":{"thoughts":"...思考..."}}]}

问题：

每家格式不同，前端需要为每家写适配器
只能区分"文本"和"结束"，无法知道 AI 状态

AG-UI 的结构化事件

AG-UI 规范了统一的结构化事件：

// 推理过程
{ "type": "REASONING_START", "messageId": "..." }
{ "type": "REASONING_MESSAGE_CONTENT", "delta": "..." }
{ "type": "REASONING_END" }

// 工具调用
{ "type": "TOOL_CALL_START", "toolCallId": "...", "toolCallName": "search" }
{ "type": "TOOL_CALL_ARGS", "delta": "{\"query\":\"...\"}" }
{ "type": "TOOL_CALL_RESULT", "toolCallId": "...", "result": "..." }

// 步骤执行
{ "type": "STEP_STARTED", "stepName": "analyze" }
{ "type": "STEP_FINISHED", "stepName": "analyze" }

// 最终回复
{ "type": "TEXT_MESSAGE_CONTENT", "delta": "..." }
{ "type": "TEXT_MESSAGE_END" }

对比表

维度	以前	AG-UI
思考内容	各家自定义格式	统一 REASONING_* 事件
工具调用	没有/自己定义	统一 TOOL_CALL_* 事件
元数据	无	timestamp, messageId, runId
状态追踪	无	STATE_SNAPSHOT / STATE_DELTA
前端适配	每家写一套	一次开发，到处运行

核心事件类型

AG-UI 定义了丰富的事件类型，完整覆盖 Agent 交互场景：

生命周期事件

RUN_STARTED / RUN_FINISHED / RUN_ERROR

步骤事件

STEP_STARTED / STEP_FINISHED

文本消息事件

TEXT_MESSAGE_START / TEXT_MESSAGE_CONTENT / TEXT_MESSAGE_END

推理事件

REASONING_START / REASONING_MESSAGE_CONTENT / REASONING_END

工具调用事件

TOOL_CALL_START / TOOL_CALL_ARGS / TOOL_CALL_END / TOOL_CALL_RESULT

状态管理事件

STATE_SNAPSHOT / STATE_DELTA

为什么这样设计？

1. 实时透明

用户不再盲目等待，而是能清楚看到 AI 的思考过程、工具调用、步骤执行。这大大提升了用户体验和信任度。

2. 可观测性

每个事件都包含 timestamp、messageId、runId 等元数据，形成了完整的审计追踪。这对于调试和监控至关重要。

3. 解耦

后端可以换模型、换 Agent，前端无需改动。实现了"前端只写一次，连接任何 Agent"的理想。

4. 生态互通

结合 MCP（工具集成）和 A2A（Agent 通信），共同构成了 Agent 时代的协议栈：

MCP → Agent 与工具/数据源
A2A → Agent 与 Agent
AG-UI → Agent 与 UI

这三个协议各司其职，共同构建完整的 Agent 应用生态：

┌─────────────────────────────────────────┐
│              用户 (你)                   │
└─────────────────┬───────────────────────┘
                  │ AG-UI (Agent ↔ 用户)
                  ▼
┌─────────────────────────────────────────┐
│           前端 UI (网页/App)            │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────┴───────────────────────┐
│              Agent (AI 大脑)             │
│  - 理解用户意图                         │
│  - 规划任务步骤                         │
└────┬────────────────────┬───────────────┘
     │                    │
  MCP│                 A2A│
     ▼                    ▼
┌─────────┐         ┌─────────┐
│  工具们  │         │ 其他Agent│
│(搜索/   │         │         │
│ 数据库/ │         │         │
│ API等)  │         │         │
└─────────┘         └─────────┘

协议	作用	比喻
MCP	Agent 用什么工具	手（操作外部世界）
A2A	Agent 之间怎么沟通	语言（与其他 Agent 对话）
AG-UI	Agent 怎么跟用户对话	脸（展示给用户看）

总结

AG-UI 协议的核心价值在于：

标准化 —— 统一 Agent 与前端的通信格式
实时透明 —— 让用户看到 AI 的每一步
可观测 —— 完整的事件日志便于调试
解耦 —— 前端后端独立演进

简单来说：以前是"点一下等结果"，现在是"看着 AI 干活"。AG-UI 让 AI Agent 的交互从黑箱变成了透明、可控的体验。

参考资料：