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_* 三类事件,按需扩展

五个上线前值得先踩平的坑:

  1. 事件顺序不能乱:TEXT_MESSAGE_CONTENT 出现在 START 之前,前端状态机直接崩,务必在服务端用状态机守住。
  2. id 空间要唯一:文本、推理、活动消息共用同一 id 空间,重复 id 会导致渲染互相覆盖。
  3. SSE 断线要能续:约定 threadId,重连先要 MESSAGES_SNAPSHOT 补全历史,不要从头重跑 Agent。
  4. 鉴权放在流之外:SSE 难改 header,用一次性 ticket 换流式连接,别把 key 拼在 query 上。
  5. 元数据别滥用:metadata 适合放 token 用量、trace id,别把业务大对象塞进去——同 key 后写覆盖,很容易悄悄丢数据。

总结要点

  1. AG-UI 补的是 Agent↔前端 这一段,和 MCP(工具)、A2A(Agent 间)是三件不同的事。
  2. 全部表达力收在 8 类事件里,模式统一:成对事件包流式内容,id 负责关联。
  3. 服务端只要吐标准 SSE;前端必须处理好半帧缓冲与流式解码。
  4. 状态同步记一条铁律:快照整体替换、增量按序打补丁。
  5. Interrupts 把人类审批变成协议能力,生成式 UI 只传意图、不传像素。
  6. 协议不是越多越好——单栈内部 demo 用 WebSocket 就行。

延伸阅读建议:本博客《什么是 MCP 协议?一文读懂 AI 的 USB 接口标准》补齐工具侧,《什么是 A2A 协议?Agent 之间的 TCP/IP 标准全解析》补齐 Agent 协作侧,《什么是 Agent 编排模式?管道式/辩论式/分层式/市场式全面对比》(guide-134)讲清后端怎么组队,《什么是 MCP Apps?AI Agent 的可视化界面新标准全解析》则从另一个角度切 UI 层,可与本文对读。