返回文章

用 AG-UI 把 Agent 接入前端:以工程可研报告为例

用一张投资估算表理解 AG-UI 的事件模型,看前端怎样展示工具进度、更新报告数据,并在关键参数需要确认时把决定交给用户。

假设你让 AI 根据项目资料起草一份建筑工程可行性研究报告。编到投资估算时,它发现项目建议书写的建筑面积是 10,000 平方米,设计说明写的却是 12,000 平方米。如果界面只有一个逐字输出的聊天框,你得从一段长文里找出这处分歧,再解释一遍要改哪个数字。更顺手的做法是让估算表停在这一行,列出两个数值及其来源,请你选定后再计算。

要做出这样的界面,前端得知道工具查到了什么、哪一项数据发生了变化,以及现在轮到谁操作。AG-UI(Agent–User Interaction Protocol)是一种开放的事件协议,约定了前端怎样向 Agent 发起运行,以及 Agent 怎样把这些信息实时传回界面。AG-UI 官网 · 协议仓库

AG-UI、MCP 和 A2A 各管哪一段

工作台用 React 展示报告,后端的报告 Agent 负责调用模型、检索资料和编排任务。用户点击「生成报告」时,请求沿 AG-UI 连线到达后端,随后工具进度、报告正文和估算数据沿同一条连线回到工作台。

报告工作台的协议关系
建筑工程工作台
报告 Agent
法规检索工具
独立造价 Agent

沿着左边的分支看一次法规检索。报告 Agent 通过 MCP(Model Context Protocol)向检索工具查询条文,通过 AG-UI 发出 TOOL_CALL_START,让工作台显示「正在检索」。工具返回结果后,工作台按 toolCallId 将 TOOL_CALL_RESULT 中的条文和出处放回同一张卡片。MCP 官方介绍

右边的分支适用于造价工作由独立的 Agent 承接的情况。报告 Agent 可以用 A2A(Agent2Agent Protocol)委派任务、接收估算结果。两条分支可以独立使用,用户始终在原来的工作台看进度。A2A 官方介绍

一次面积确认,为什么需要两次运行?

第一次运行以 RUN_STARTED 开始。后端可以用 STEP_STARTED 和 STEP_FINISHED 标出资料读取的起止,再用 STATE_SNAPSHOT 发送估算表的完整状态。此时两份资料都已读完,建筑面积这一行却只能标为「待确认」。

一次面积确认,跨越两次运行
  1. 运行 1
    核对建筑面积
    项目建议书
    10,000 m²
    设计说明
    12,000 m²
    RUN_FINISHED · interrupt两份资料的面积不同,等待用户确认
  2. 用户确认
    采用设计说明的面积
    工作台在新请求的 resume 字段中提交这个选择。
  3. 运行 2
    按确认值重算
    沿用 threadId,使用新的 runId。
    STATE_DELTA
    估算表面积更新为 12,000 m²
    RUN_FINISHED · success
    报告完成

图中出现了两次 RUN_FINISHED。第一次结束的是等待前的那次运行。 后端将 outcome.type 设为 interrupt,工作台保留两份资料的来源,请用户确认。用户选定设计说明后,前端沿用 threadId,用新的 runId 发起请求,在 resume 中带上中断 ID 和答案。中断与恢复

第二次结束时,报告才完成。 服务端先核验用户权限、记录所选依据,再按确认值计算。工作台通过 STATE_DELTA 更新估算表,通过 TEXT_MESSAGE_CONTENT 分段显示报告正文。运行成功结束后,页面显示「报告完成」。如果运行失败,工作台收到的是 RUN_ERROR。

事件怎样变成界面上的变化

AG-UI 1.0 按用途组织事件。前后端可以按场景选用相应能力。例如,负责法规检索的子 Agent 可以单独报告进度,工作台能据此标明每条结果的来源。AG-UI 1.0 事件模型

界面要回答的问题对应事件前端如何使用
正文写到哪里了?TEXT_MESSAGE_START、TEXT_MESSAGE_CONTENT、TEXT_MESSAGE_END按 messageId 将片段追加到同一段回复
工具查完了吗?TOOL_CALL_START、TOOL_CALL_ARGS、TOOL_CALL_END、TOOL_CALL_RESULTEND 表示调用参数已传完,拿到 RESULT 才能显示查询结果
估算表哪一行变了?STATE_SNAPSHOT、STATE_DELTA用快照建立完整状态,再按顺序应用 JSON Patch 增量
哪个子任务在运行?SUBAGENT_STARTED、SUBAGENT_FINISHED、SUBAGENT_ERROR单独标记子 Agent 的执行状态,将其输出归到对应任务

例如,假设前一次快照里已有 estimate.floorAreaM2 字段。用户确认采用 12,000 平方米后,后端可以发出下面这条事件。字段名和面积单位由报告应用约定,协议规定的是修改状态的表达方式。状态与事件

{
  "type": "STATE_DELTA",
  "delta": [{ "op": "replace", "path": "/estimate/floorAreaM2", "value": 12000 }]
}

工作台据此更新面积单元格。估算金额要等计算服务给出结果后再更新。这样,即使回复正文里同时引用了旧面积,表格也始终显示用户确认的计算口径。规范还定义了活动和推理事件,具体展示哪些进度信息,可以根据后端提供的能力和界面的用途决定。

在 TanStack Start 中接入有什么价值

TanStack AI 的客户端可以发送 AG-UI 的 RunAgentInput,服务端也能输出 AG-UI 事件。React 端可以用 useChat 接收消息。浏览器常用的传输方式是 SSE,TanStack AI 也提供按行传输 JSON 的 HTTP 流和 WebSocket 适配器。客户端与服务端要选用匹配的传输格式,估算表消费的仍是同一套事件。TanStack AI 协议说明 · 传输方式

即使估算 Agent 用 Python 实现,前端仍可沿用现有的 React 表格和报告视图。两端需要约定请求格式、传输方式、实际支持的事件,以及 floorAreaM2 这样的业务字段。计算公式、谁有权确认面积、任务如何排队、报告和审批记录保存在哪里,则由应用和 Agent 运行时负责。

对工程报告工作台,采用 AG-UI 的理由就在那个有分歧的面积单元格里。用户能看见 Agent 查到了哪两份资料,在需要判断的地方给出答案,再看到这次决定怎样改变估算结果。

参考资料

  1. AG-UI 官网
  2. 协议仓库
  3. MCP 官方介绍
  4. A2A 官方介绍
  5. 中断与恢复
  6. AG-UI 1.0 事件模型
  7. 状态与事件
  8. TanStack AI 协议说明
  9. 传输方式