30秒快速回答: AG-UI(Agent User Interaction Protocol)是一个开放、轻量、事件驱动的协议,专门标准化 AI Agent 后端与前端应用之间的通信。它把 Agent 运行时产生的东西——文本增量、工具调用、状态变化、人类审批中断——统一成一串有类型的事件,通过 SSE 推给前端。它是继 MCP(Agent↔工具)、A2A(Agent↔Agent)之后的第三条缝:Agent↔用户界面。
核心价值一句话: 前端不该去适配每个 Agent 框架的私有流式格式,AG-UI 让”换后端不改前端”成为可能。
一、三个协议各管一段,别指望一个协议包打天下
Agent 应用里其实有三种连接,过去大家习惯各写一套 WebSocket 胶水代码。AG-UI 补齐的正是最靠近用户的那一段。
| 协议 | 连接的两端 | 解决什么 | 典型产物 |
|---|---|---|---|
| MCP | Agent ↔ 工具/资源 | 工具怎么被发现、描述、调用 | 一个 MCP Server |
| A2A | Agent ↔ Agent | 对等智能体怎么派活、回报、鉴权 | 一份 Agent Card |
| AG-UI | Agent ↔ 前端界面 | 界面怎么实时看到 Agent 在想什么、做什么、要不要人确认 | 一串标准事件流 |
关键判断:MCP 和 A2A 都在 Agent 内部层面,用户看不见;AG-UI 是唯一面向人那一侧的协议。 一个完整的 Agent 产品三层都要,缺了第三层,前端就只能自己解析各家框架的私有 SSE 格式——换个后端,前端重写一遍。
值得注意的细节:AG-UI 描述的是事件流,不是渲染目标。所以消费端不一定得是网页,终端、移动 App、聊天平台都可以是 AG-UI 客户端。
二、事件流长什么样:8 类事件就够表达一个 Agent
AG-UI 的全部表达力都收在事件类型里。线上传输时事件类型是大写下划线常量(如 RUN_STARTED),文档里常写成 RunStarted 的形式。
| 分类 | 事件 | 用途 |
|---|---|---|
| 生命周期 | RUN_STARTED / RUN_FINISHED / RUN_ERROR |
标记一次运行的开始与结束,前端据此切加载态 |
| 阶段 | STEP_STARTED / STEP_FINISHED |
可选,标记子任务或节点粒度进度 |
| 文本消息 | TEXT_MESSAGE_START / _CONTENT / _END |
delta 字段按顺序拼接成完整回复 |
| 工具调用 | TOOL_CALL_START / _ARGS / _END / _RESULT |
参数也是流式的,前端可实时显示”正在查订单…” |
| 状态 | STATE_SNAPSHOT / STATE_DELTA / MESSAGES_SNAPSHOT |
快照打底,JSON Patch 增量更新 |
| 活动 | ACTIVITY_SNAPSHOT / ACTIVITY_DELTA |
消息之间插入结构化进度块(如步骤条) |
| 推理 | REASONING_* |
展示思维摘要或加密推理项,兼顾可解释与隐私 |
| 特殊 | RAW / CUSTOM |
包裹外部系统事件、扩协议未定义能力 |
规律很统一:成对事件包住流式内容,messageId / toolCallId 负责关联,所有事件共享可选 metadata(token 用量、trace id 都能塞进去)。 这套设计让日志本身就是可回放的时间线。
三、最小可跑:30 行服务端 + 20 行前端
服务端只要吐标准事件流即可。这里用 FastAPI 手写,不依赖任何框架集成:
# pip install fastapi uvicorn
import json, uuid
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
app = FastAPI()
def ev(t, **kw):
return f"data: {json.dumps({'type': t, **kw}, ensure_ascii=False)}\n\n"
@app.post("/agui")
async def agui():
run_id, msg_id = str(uuid.uuid4()), str(uuid.uuid4())
def gen():
yield ev("RUN_STARTED", runId=run_id, threadId="t-1")
yield ev("TEXT_MESSAGE_START", messageId=msg_id, role="assistant")
for chunk in ["订单 #1024 ", "已发货,", "预计明天送达。"]:
yield ev("TEXT_MESSAGE_CONTENT", messageId=msg_id, delta=chunk)
yield ev("TEXT_MESSAGE_END", messageId=msg_id)
yield ev("RUN_FINISHED", runId=run_id,
outcome={"type": "success"})
return StreamingResponse(gen(), media_type="text/event-stream")
前端用原生 fetch 解析 SSE,不装 SDK 也能跑通:
const res = await fetch("/agui", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ threadId: "t-1", messages: [] }),
});
const reader = res.body.getReader();
const dec = new TextDecoder();
let buf = "", text = "";
while (true) {
const { value, done } = await reader.read();
if (done) break;
buf += dec.decode(value, { stream: true });
const frames = buf.split("\n\n");
buf = frames.pop(); // 留住半帧
for (const f of frames) {
const line = f.split("\n").find(l => l.startsWith("data:"));
if (!line) continue;
const e = JSON.parse(line.slice(5).trim());
if (e.type === "TEXT_MESSAGE_CONTENT") { text += e.delta; render(text); }
}
}
两个容易踩的位置已经藏在代码里:必须保留 buf 里的半帧(SSE 帧会被网络切碎),以及必须用 { stream: true } 解码(否则中文多字节字符会在分片处乱码)。
四、状态同步与人机中断:AG-UI 最值钱的两块
Agent 不是无状态问答,它有会变的工作记忆。AG-UI 用”快照 + 增量”解决同步:
# 连接初期/重连后发全量,之后只发 JSON Patch
yield ev("STATE_SNAPSHOT", snapshot={"step": "search", "results": []})
yield ev("STATE_DELTA", delta=[
{"op": "replace", "path": "/step", "value": "book"},
{"op": "add", "path": "/results/-", "value": {"sku": "A1"}},
])
前端收到 SNAPSHOT 应当整体替换而非合并;收到 DELTA 按序应用补丁,一旦发现版本不一致就请求重新快照。这条纪律能省掉大量”界面数据和 Agent 数据对不上”的奇怪 bug。
第二块是中断(Interrupts),也就是人类审批。运行不是以”成功”结束,而是以”暂停等你点确认”结束:
yield ev("RUN_FINISHED", runId=run_id, outcome={
"type": "interrupt",
"interrupts": [{"id": "ap-1", "reason": "即将执行退款 ¥299,请确认"}],
})
前端渲染确认卡片,用户点”同意”后带着 resume 数组再次调用同一端点,Agent 从断点继续。把审批写进协议层和写进 prompt 是两回事——协议层的暂停是可拦截、可审计、可做权限校验的。
还有一项是 Generative UI:Agent 可以声明”这里该渲染一个按钮/表单”,由前端映射到自己的组件库。它和 STATE_DELTA 一样是”意图传递”,最终长什么样由前端决定,这一点别搞反。
五、什么时候该用,什么时候别用
| 场景 | 建议 |
|---|---|
| 你在做多框架兼容的 Agent 产品前端 | 用 AG-UI,一次对接,后端随便换 |
| 需要人类审批 / 长时任务的进度可视化 | 用 AG-UI 的 Interrupts + Activity 事件 |
| 单后端、单前端、内部 demo | 直接 WebSocket 更省事,别为了协议而协议 |
| 前端是纯命令行脚本 | 可以只解析 TEXT_MESSAGE_* 三类事件,按需扩展 |
五个上线前值得先踩平的坑:
- 事件顺序不能乱:
TEXT_MESSAGE_CONTENT出现在START之前,前端状态机直接崩,务必在服务端用状态机守住。 - id 空间要唯一:文本、推理、活动消息共用同一 id 空间,重复 id 会导致渲染互相覆盖。
- SSE 断线要能续:约定
threadId,重连先要MESSAGES_SNAPSHOT补全历史,不要从头重跑 Agent。 - 鉴权放在流之外:SSE 难改 header,用一次性 ticket 换流式连接,别把 key 拼在 query 上。
- 元数据别滥用:
metadata适合放 token 用量、trace id,别把业务大对象塞进去——同 key 后写覆盖,很容易悄悄丢数据。
总结要点
- AG-UI 补的是 Agent↔前端 这一段,和 MCP(工具)、A2A(Agent 间)是三件不同的事。
- 全部表达力收在 8 类事件里,模式统一:成对事件包流式内容,id 负责关联。
- 服务端只要吐标准 SSE;前端必须处理好半帧缓冲与流式解码。
- 状态同步记一条铁律:快照整体替换、增量按序打补丁。
- Interrupts 把人类审批变成协议能力,生成式 UI 只传意图、不传像素。
- 协议不是越多越好——单栈内部 demo 用 WebSocket 就行。
延伸阅读建议:本博客《什么是 MCP 协议?一文读懂 AI 的 USB 接口标准》补齐工具侧,《什么是 A2A 协议?Agent 之间的 TCP/IP 标准全解析》补齐 Agent 协作侧,《什么是 Agent 编排模式?管道式/辩论式/分层式/市场式全面对比》(guide-134)讲清后端怎么组队,《什么是 MCP Apps?AI Agent 的可视化界面新标准全解析》则从另一个角度切 UI 层,可与本文对读。