AG-UI 协议深度解析:构建 AI Agent 与前端应用的实时交互桥梁
AG-UI:使每一次 AI Agent 与用户的接触,都自然、流畅且可控。
引言
在 AI Agent 爆发的当下,我们拥有了极其强大的智能后端——然而,怎样才能让这些 Agent 真正“融入”用户界面?传统的 REST API 和 GraphQL 在应对 Agent 的实时流式输出、不确定行为、多轮对话等特性时,显得力有不逮。
AG-UI(Agent-User Interaction Protocol) 由此诞生。它是一个开放、轻量、事件驱动的协议,将 AI Agent 与用户界面之间的连接方式进行标准化。
本文将从浅入深,详细介绍 AG-UI 协议的工作原理、核心概念及实际落地方式。

一、AG-UI 为何而生?
1.1 传统 API 遇到的瓶颈
在 AI Agent 亮相之前,前后端通信普遍采用请求-应答模式:
- 客户端发起请求
- 服务端返回数据
- 客户端渲染结果
- 一次交互结束
但 AI Agent 彻底打破了这种模式:
| 传统 API | AI Agent |
|---|---|
| 短连接,一次性返回 | 长时运行,持续输出 |
| 结果确定性高 | 行为不确定 |
| 单次交互 | 多轮会话 |
| 单一数据格式 | 混合 I/O (文本+工具调用+状态更新) |
| 线性流程 | 可暂停、可干预 |
这些特性使得传统 API 捉襟见肘。开发人员不得不自行处理:
- 流式输出的解析与渲染
- 多种事件类型的统一管理
- 用户中途干预的衔接
- 前后端状态的一致性同步
1.2 三项 Agentic 协议的定位
AG-UI 并非孤立存在,它与其他两项协议共同构成了完整的 Agentic 生态:
| 层级 | 协议 | 作用 |
|---|---|---|
| Agent ↔ 用户界面 | AG-UI | 连接 Agent 与前端应用 |
| Agent ↔ 工具/数据 | MCP (Model Context Protocol) | 使 Agent 接入外部系统和工具 |
| Agent ↔ Agent | A2A (Agent to Agent) | 支持多 Agent 协同工作 |
简而言之:
- MCP 为 Agent 装填“行动力”(连接工具与数据)
- A2A 使 Agent 之间“对话”(分摊任务并协作)
- AG-UI 让 Agent 与人类“互动”(在界面中展示并控制)
二、认识 AG-UI 协议
2.1 定义
AG-UI 是一款开放、轻量、事件驱动的协议,定义了:
- Agent 后端如何向前端应用发送事件
- 前端应用如何接收、处理和响应这些事件
- 用户如何干预、掌控 Agent 的执行过程
2.2 核心设计原则
1. 事件驱动
Agent 在运行过程中,不断发出“事件”。前端应用订阅事件流,实时更新界面。
Agent 执行 → 发出事件 → 前端接收 → 更新 UI
↑ ↓
←←← 用户输入 ←←←←←←←←←←←
2. 最小化约束
Agent 只需要:
- 发送与 AG-UI 兼容的事件
- 接收用户输入
仅此而已!无需完全贴合 AG-UI 格式,只需做到“兼容”即可。
3. 传输无关心
AG-UI 不限定传输方式,支持:
- SSE(Server-Sent Events)
- WebSocket
- Webhook
- 自定义传输层
2.3 用一句话概括
AG-UI 是 AI Agent 与用户界面之间的“通用翻译器”,让任何 Agent 都能驱动任何前端应用。
三、AG-UI 的事件系统
AG-UI 的核心是事件。理解事件,便能掌握 AG-UI。
3.1 事件一览
AG-UI 定义了一系列标准事件类型,可划分为如下几类:
| 类别 | 事件 | 用途 |
|---|---|---|
| 生命周期事件 | RUN_STARTED , RUN_FINISHED, RUN_ERROR, STEP_STARTED, STEP_FINISHED | 监视 Agent 执行进度 |
| 文本消息事件 | TEXT_MESSAGE_START , TEXT_MESSAGE_CONTENT, TEXT_MESSAGE_END | 流式输出文本 |
| 工具调用事件 | TOOL_CALL_START , TOOL_CALL_ARGS, TOOL_CALL_END, TOOL_CALL_RESULT | Agent 调用外部工具 |
| 状态管理事件 | STATE_SNAPSHOT , STATE_DELTA, MESSAGES_SNAPSHOT | 前后端状态同步 |
| 推理事件 | REASONING_START , REASONING_MESSAGE_START, REASONING_MESSAGE_*, REASONING_MESSAGE_END, REASONING_END | 展示思考过程 |
| 特殊事件 | RAW , CUSTOM | 扩展功能 |
3.2 生命周期事件:追踪 Agent 运行
当用户向 Agent 发送一条消息时,整个执行过程如下:
RUN_STARTED ← Agent 开始工作
↓
STEP_STARTED ← 进入某个步骤
↓ (Agent 正在执行)
STEP_FINISHED ← 步骤结束
↓
... (可能多个步骤)
↓
RUN_FINISHED 或 RUN_ERROR ← 成功或异常
前端可以这样呈现:
🤖 正在思考... [RUN_STARTED]
├─ 分析用户请求... ✓ [STEP_STARTED → STEP_FINISHED]
├─ 搜索相关信息... ✓ [STEP_STARTED → STEP_FINISHED]
└─ 生成回答... ✓ [STEP_STARTED → STEP_FINISHED]
✅ 完成 [RUN_FINISHED]
3.3 文本消息事件:流式输出
AG-UI 采用流式传输,使用户能够实时看到 Agent 的回复内容:
TEXT_MESSAGE_START ← 创建消息气泡
↓
TEXT_MESSAGE_CONTENT ← "你"
↓
TEXT_MESSAGE_CONTENT ← "好"
↓
TEXT_MESSAGE_CONTENT ← "!"
↓
TEXT_MESSAGE_END ← 消息完成
优势:
- 用户即时获得反馈,无需等待完整回复
- 对话体验更自然
- 接近 ChatGPT 的逐字输出效果
3.4 工具调用事件:Agent “动手做事”
当 Agent 需要调用工具(如网页搜索、代码执行)时:
TOOL_CALL_START ← 工具名称:search_web
↓
TOOL_CALL_ARGS ← 参数:{"query": "今天的天气"}
↓
TOOL_CALL_END ← 参数发送完毕
↓
TOOL_CALL_RESULT ← 结果:{"temperature": "25°C"}
前端展示效果:
🔍 正在搜索网络
查询: "今天的天气"
结果: 北京,晴,25°C
3.5 状态管理事件:前后端协同
AG-UI 提供快照-增量模式来同步状态:
STATE_SNAPSHOT ← 发送完整状态(初始化或重新同步)
↓
STATE_DELTA ← 只传输变化部分(增量更新)
↓
STATE_DELTA ← 继续增量更新
↓
... (定期发送快照确保一致性)
如此设计的原因:
- 快照:确保前端拥有完整的状态基准
- 增量:减少数据传输量,提高效率
这与 Git 的机制类似:快照相当于完整 commit,增量则是一次 diff。
四、AG-UI 架构详解
4.1 整体结构
┌─────────────────────────────────────────────────────────┐
│ 前端应用 │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ UI 组件 │←→│ AG-UI Client │ │
│ └─────────────┘ └──────┬──────┘ │
└───────────────────────────┼─────────────────────────────┘
│
AG-UI 协议(事件流)
│
┌───────────────────────────┼─────────────────────────────┐
│ 后端服务 │
│ ┌─────────────┐ ┌──────┴──────┐ ┌─────────────┐ │
│ │ Agent A │ │ AG-UI 中间件 │ │ Agent B │ │
│ │ (LangGraph) │ │ (可选) │ │ (CrewAI) │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────┘
4.2 主要组件
1. Agent(后端)
Agent 是“智能后端”,负责:
- 接收用户输入
- 执行 AI 推理
- 调用工具
- 发送事件流
Agent 只需实现一个核心接口:
run(input: RunAgentInput): Observable<BaseEvent>
2. AG-UI Client(前端客户端)
标准前端客户端,负责:
- 建立 Agent 连接
- 订阅事件流
- 解析与分发事件
const agent = new HttpAgent({
url: "https://your-agent.com/endpoint",
threadId: "conversation-123"
});
agent.runAgent({ tools: [...] }).subscribe({
next: (event) => handleEvent(event),
error: (err) => console.error(err),
complete: () => console.log("Done!")
});
3. 传输层
AG-UI 兼容多种传输方式:
| 传输方式 | 特点 | 适用场景 |
|---|---|---|
| HTTP SSE | 文本流,易于调试 | 大多数 Web 应用 |
| WebSocket | 双向实时 | 需要高频交互的场景 |
| Webhook | 事件推送 | 服务端回调 |
| HTTP Binary | 高效二进制 | 生产环境,对性能敏感 |
4.3 中间件层
AG-UI 提供灵活的中间件,保证兼容性:
事件格式适配:不同框架的事件格式可转换
传输抽象:上层代码无需关注传输细节
五、AG-UI 的核心能力
5.1 流式对话
实时流式输出,支持多轮对话,随时可暂停和恢复。
5.2 多模态支持
支持文件、图片、音频、视频等多种媒体类型。
5.3 生成式 UI
Agent 不仅能输出文字,还能“生成”界面组件:
// Agent 可返回 UI 组件定义
{
type: "GENERATIVE_UI",
component: "ProductCard",
props: { name: "商品A", price: 99, image: "..." }
}
前端渲染后,用户看到的是完整的商品卡片,而不仅是一段文本。
5.4 共享状态
Agent 与前端共享状态:
- 只读状态:前端展示 Agent 的内部状态
- 读写状态:前端可修改状态,Agent 可感知变化
5.5 前端工具调用
Agent 可以“请求”前端执行某些操作:
Agent: "我需要获取用户的位置"
↓
TOOL_CALL_START (tool: "get_user_location")
↓
前端执行 → 返回结果
↓
Agent 继续工作
5.6 人工介入(Human-in-the-Loop)
在关键节点暂停,等待人类确认:
Agent: 准备删除文件...
↓
INTERRUPT: "是否确认删除?"
↓
用户: 确认 / 取消
↓
Agent: 执行 / 跳过
5.7 思考过程可视化
展示 Agent 的推理过程,同时保护隐私:
REASONING_START
↓
REASONING_MESSAGE_CONTENT: "分析用户意图..."
↓
REASONING_MESSAGE_CONTENT: "匹配知识库..."
↓
REASONING_END
↓
TEXT_MESSAGE_START (正式回复)
六、生态与集成
AG-UI 已获得广泛支持:
6.1 Agent 框架集成
| 框架 | 状态 | 说明 |
|---|---|---|
| LangGraph | ✅ 支持 | LangChain 的 Agent 框架 |
| CrewAI | ✅ 支持 | 多 Agent 协作框架 |
| Google ADK | ✅ 支持 | Google Agent Development Kit |
| Microsoft Agent Framework | ✅ 支持 | 微软官方框架 |
| AWS Strands Agents | ✅ 支持 | AWS 的 Agent SDK |
| Pydantic AI | ✅ 支持 | 类型安全的 Agent 框架 |
| OpenAI Agent SDK | 🛠️ 开发中 | OpenAI 官方 SDK |
6.2 客户端支持
| 客户端 | 状态 |
|---|---|
| CopilotKit | ✅ 官方支持 |
| Terminal | ✅ 社区支持 |
| React Native | 🛠️ 开发中 |
6.3 多语言 SDK
- TypeScript/JavaScript(官方)
- Python(官方)
- Kotlin、Go、Rust、Java、Dart(社区)
七、实际应用案例
7.1 智能客服助手
用户: "帮我查一下订单状态"
↓
[TOOL_CALL] 查询订单系统
↓
[GENERATIVE_UI] 渲染订单卡片
↓
用户点击"取消订单"
↓
[INTERRUPT] 确认取消?
↓
完成操作
7.2 代码助手
用户: "帮我写一个登录页面"
↓
[REASONING] 分析需求...
↓
[TOOL_CALL] 生成代码
↓
[STATE_DELTA] 更新文件列表
↓
[GENERATIVE_UI] 显示代码预览
7.3 数据分析 Agent
用户: "分析这份销售数据"
↓
[STEP_STARTED] 数据预处理
[STEP_FINISHED]
↓
[STEP_STARTED] 生成图表
[STATE_DELTA] 进度: 50%
↓
[GENERATIVE_UI] 渲染图表组件
八、如何开始使用 AG-UI?
8.1 快速上手
创建 AG-UI 应用的步骤非常简单:
# 创建新项目
npx create-ag-ui-app my-agent-app
# 或安装核心包
npm install @ag-ui/core
8.2 定义 Agent
import { AbstractAgent, EventType } from '@ag-ui/core';
class MyAgent extends AbstractAgent {
run(input) {
const { threadId, runId } = input;
return from([
{ type: EventType.RUN_STARTED, threadId, runId },
{ type: EventType.TEXT_MESSAGE_START, messageId: 'msg-1' },
{ type: EventType.TEXT_MESSAGE_CONTENT, messageId: 'msg-1', delta: '你好!' },
{ type: EventType.TEXT_MESSAGE_END, messageId: 'msg-1' },
{ type: EventType.RUN_FINISHED, threadId, runId },
]);
}
}
8.3 前端集成
const agent = new HttpAgent({
url: '/api/agent',
threadId: 'my-conversation'
});
agent.runAgent({ messages: [...] }).subscribe({
next: (event) => {
switch (event.type) {
case EventType.TEXT_MESSAGE_CONTENT:
appendToChat(event.delta);
break;
case EventType.TOOL_CALL_START:
showToolCall(event.toolCallName);
break;
// ... 处理其他事件
}
}
});
九、总结
AG-UI 的核心价值
| 维度 | 传统方式 | AG-UI |
|---|---|---|
| 连接 | 各自实现 | 标准化协议 |
| 实时性 | 轮询或复杂 WebSocket | 事件流原生支持 |
| 状态管理 | 自行处理 | 快照+增量同步 |
| 用户体验 | 等待完整响应 | 流式实时反馈 |
| 开发效率 | 重复造轮子 | 开箱即用 |
AG-UI 的未来展望
AG-UI 正在快速迭代,未来将支持:
- 更多 Agent 框架的官方集成
- 更丰富的生成式 UI 组件
- 更完善的调试与监控工具
- 与 MCP、A2A 的深度整合
参考资源
- 📖 AG-UI 官方文档
- 💻 GitHub 仓库
- 🎮 AG-UI Dojo(在线演示)
- 💬 Discord 社区
- 🐦 Twitter/X