Agent 已在后台调用天气工具,前端却只有一个转圈动画,直到最后才一次性显示答案。问题通常不在模型,而在前后端仍沿用“请求—响应”:Agent 的文本、工具调用与状态变化没有持续送到界面。AG-UI 把执行过程转换为带类型的 JSON 事件流,前端订阅后逐条消费,于是这些变化可以被实时渲染。
ag-ui-protocol/ag-ui 是 GitHub 上的趋势项目,统一 Agent 后端与前端之间的实时通信,并未再造一套 Agent 运行时。AG-UI 管 Agent 到 UI 的事件流,MCP 管工具和数据,A2A 管 Agent 间协作。工程上需要处理三件事:事件建模、流式通道选择和前端消费。
AG-UI 与 MCP、A2A 分别管什么
AG-UI(Agent-User Interaction Protocol)是面向 Agent 与用户前端交互的开放、轻量、事件驱动协议。MCP 解决 Agent 如何接入工具和数据,A2A 解决多个 Agent 如何协作,AG-UI 负责 Agent 如何把执行过程交给界面。三者职责互补,互不替代。
它的边界明确:AG-UI 约定消息、工具调用和状态变化等事件如何流动,不规定卡片、表单或聊天框长什么样;它只解决事件“怎么送”,不解决界面“怎么设计”。
一条事件流如何从 Agent 到达浏览器
常见做法是前端用 HTTP POST 提交一次运行。SSE 实现会在这条 HTTP 响应中持续返回事件;WebSocket 实现则在连接上传递同一类事件。服务端持续推送带类型的 JSON 事件,前端消费到 RUN_FINISHED 或 RUN_ERROR 后结束本轮状态处理。其中,threadId 表示完整会话,runId 表示会话中的一次运行,两者不能混用。
Web 场景通常先用 SSE,因为它直接复用 HTTP 响应流;需要更明确的双向控制时再考虑 WebSocket,事件语义本身不变。由于发起运行常用 POST,原生只支持 GET 的 EventSource 不够用,应使用 fetch 流式读取,或项目提供的连接器。
一条教学用时序可以写成:
RUN_STARTED → TOOL_CALL_START → TOOL_CALL_ARGS → TOOL_CALL_RESULT
→ TEXT_MESSAGE_START → TEXT_MESSAGE_CONTENT(可重复)→ TEXT_MESSAGE_END → RUN_FINISHED
这不是强制文法。实际流程可能插入 STEP_*、TOOL_CALL_END、推理事件,也可能因异常转入 RUN_ERROR;前端应按状态机或 reducer 消费,而不是写死一条固定路径。
事件大体分为生命周期、文本消息、工具调用、状态管理、推理和特殊扩展几类。STATE_SNAPSHOT 可初始化共享状态,STATE_DELTA 用于传递增量,MESSAGES_SNAPSHOT 可用于恢复消息列表。资料对事件总数有“十多种”“约 27 种”“约 16 种”等不同口径,因此不应写死数量,以 GitHub 当前规范为准。
前端怎样处理文本、工具与状态事件
优先使用官方 SDK、参考 HTTP 实现或默认连接器;如果自行接入,可以把 SSE 的 data: 帧解析为 JSON,再交给统一的事件归约器。以下代码只保留消费骨架,events 可来自 SDK 连接器,applyDelta 则按当前规范处理状态增量:
async function consume(events: AsyncIterable<any>, render: (s: any) => void) {
const s = { messages: {}, tools: {}, state: {}, loading: true };
for await (const e of events) {
if (e.type === "TEXT_MESSAGE_START") s.messages[e.messageId] = { text: "" };
if (e.type === "TEXT_MESSAGE_CONTENT") s.messages[e.messageId].text += e.delta;
if (e.type === "TEXT_MESSAGE_END") s.messages[e.messageId].closed = true;
if (e.type === "TOOL_CALL_START") s.tools[e.toolCallId] = { name: e.toolCallName, status: "running" };
if (e.type === "TOOL_CALL_ARGS") s.tools[e.toolCallId].args = (s.tools[e.toolCallId].args ?? "") + e.delta;
if (e.type === "TOOL_CALL_END") s.tools[e.toolCallId].argsDone = true;
if (e.type === "TOOL_CALL_RESULT") Object.assign(s.tools[e.toolCallId], { status: "done", result: e.content });
if (e.type === "STATE_SNAPSHOT") s.state = e.snapshot;
if (e.type === "STATE_DELTA") s.state = applyDelta(s.state, e.delta);
if (e.type === "RUN_FINISHED" || e.type === "RUN_ERROR") s.loading = false;
render(s);
}
}
更新事件时,文本内容应追加而非覆盖;工具调用按开始、参数、结束、结果切换状态;快照替换基线,增量在基线上应用。SDK 的连接器名称、事件类型和字段类型仍应以当前 GitHub 文档为准。
前端还可通过 INTERRUPT 在运行中提交补充信息或人工确认,但暂停、恢复与持久化仍由应用后端负责。
上线前再检查五件事:断线重连、重复或乱序事件、代理缓冲、鉴权和版本兼容。框架接入与前端渲染要解耦,否则每换一个 Agent 框架,前端通信层仍会重写。
AG-UI 不能替代具体应用对暂停、持久化、恢复和权限控制的实现。接入时,先以 GitHub 当前规范 核对事件名称、字段和版本,再决定使用 SDK 还是自定义连接器;这比照搬旧文章里的事件数量更可靠。
[email protected]
。
我们承诺在核实信息后,将第一时间删除相关内容或断开链接。
























暂无评论内容