每天一个开源项目#158 AG-UI:让Agent事件流接上前端状态

日期:2026-11-16 GitHub Trending 排名:第 2 名;快照采集时间:16:00(UTC+08:00)

给聊天页面接一个流式接口,往往只需要不断往气泡里追加文字。给业务系统接 Agent 就麻烦多了:订单卡片要更新,工具调用要显示进度,用户还可能在执行中途修改条件。后端吐出一段"处理好了",前端却不知道到底哪个对象变了,更不知道这次操作是否真的完成。

AG-UI 想规范的就是这段接口。后端把执行过程表达成有类型的事件,客户端据此维护消息和共享状态。它没有替你实现订单系统,也不负责挑选模型,但能让"换一个 Agent 后端"少牵动一些前端业务代码。

值得细看的地方在客户端内部:收到合法 JSON,只是进入这条处理链的第一步。兼容转换、字段约束、事件顺序检查和状态归并,各自负责不同的问题。把它们混成一个"支持流式输出"的标签,会漏掉不少真实的失败行为。

📋 项目概览

项目 内容
主仓库 ag-ui-protocol/ag-ui
定位 Agent 与面向用户的应用之间的事件协议及 SDK
许可证 MIT,分发时需保留版权及许可声明
协议版本 本文示例采用 1.0 协议形状
TypeScript 包版本 @ag-ui/core、@ag-ui/client 为 1.0.4
Python 包版本 ag-ui-protocol 为 1.0.0;要求 Python ≥3.9
快照 Stars / Forks 18,185 / 1,878
GitHub open_issues 计数 594;该接口计数含开放 PR,不能直接当作缺陷数
阅读重点 HTTP 事件流、客户端校验链、JSON Patch、工具及中断边界

协议号和包版本不是一回事。服务端声明自己讲哪种协议,解决的是事件语义兼容;客户端发布一个修复版本,解决的可能只是实现问题。接入时应分别固定,不能看见双方都叫 AG-UI 就认定所有行为一致。

🔥 为什么值得关注

一个客服助手查询订单时,前端通常同时维护几种信息:聊天记录、查询中的加载状态、订单详情、待确认的操作。这些信息的生命周期并不一样。

消息内容适合增量追加;订单详情适合用结构化状态表达;工具参数可能还没接收完整;某一步需要人工确认时,当前执行需要结束或暂停,不能让页面一直误以为网络还在加载。AG-UI 用不同事件承载这些变化,让它们不用挤进一条自定义字符串。

例如,后端先发 STATE_SNAPSHOT 给出订单草稿,再发 STATE_DELTA 把 /order/status 改为 ready。页面可以更新订单卡片,而不必从"订单已就绪"这句话里提取状态。聊天文字仍然有用,只是不再承担数据库协议的工作。

这个划分对有多个后端框架的团队尤其实际。前端需要了解消息、状态、工具交互的共同形状;某个后端怎样规划任务、调用模型,由适配器处理。但适配器得把本来不同的执行语义翻译正确,协议本身不会自动抹平差异。

它与 MCP 的关注点也不同:MCP 侧重模型和工具、资源的连接,AG-UI 侧重 Agent 执行如何呈现给用户。后端完全可以一边调用 MCP 工具,一边向前端发送 AG-UI 事件。页面里的按钮权限、工具授权和服务端租户隔离,仍然需要应用实现。

🏗️ 核心特性

消息有身份,也有开始和结束

典型文本流由 TEXT_MESSAGE_START、若干 TEXT_MESSAGE_CONTENT、TEXT_MESSAGE_END 组成,内容片段通过 messageId 找到所属消息。这样,客户端不用把整个连接期间收到的文字无条件拼到最后一个气泡。

运行层还有 threadId 和 runId。线程标识会话,运行标识其中一次执行。重试一次执行、继续一个会话、打开一条新消息,是不同动作;如果应用把这些 ID 全部当成随机请求号,后续追踪和恢复会很难做。

这里的 ID 关联是协议与客户端的数据约定,不是安全凭证。用户拿到一个线程 ID,不应因此获得该线程的访问权限。

共享状态有全量和增量两条路

STATE_SNAPSHOT 表达完整状态;STATE_DELTA 表达 RFC 6902 风格的 JSON Patch。比如:

json 复制代码
{
  "type": "STATE_DELTA",
  "delta": [
    { "op": "replace", "path": "/order/status", "value": "ready" }
  ]
}

这条补丁依赖当前文档已经有 /order/status。它不是"无论原来是什么,都帮我合并成这样"的深度合并操作。replace 指向不存在的路径会失败,add、remove 等操作也各有前提。

因此,全量快照适合建立基线,增量适合后续细小修改。哪一份状态是权威版本、断线后从哪里取新快照、用户本地编辑怎样与后端变化协调,需要应用和后端一起约定。JSON Patch 本身不是多人协同算法。

工具调用流描述过程,不等于执行工具

工具事件包括 TOOL_CALL_START、TOOL_CALL_ARGS、TOOL_CALL_END 和 TOOL_CALL_RESULT。参数流在 toolCallId 下归并,结果再关联对应调用。

TOOL_CALL_END 只说明参数流结束,不足以证明业务操作执行成功。前端展示一个工具卡片,与真正执行"确认订单"是两件事。由谁执行、何时允许执行、怎么回传失败,都属于工具执行层的责任。

客户端归并参数时会尝试用 untruncate-json 提供部分参数对象,方便流式界面展示。但一个暂时能解析的对象,不代表参数已经完整,更不代表可以提前触发有副作用的操作。支付、删除、发消息等动作尤其不能跟着参数片段就执行。

人工介入是显式结果,不必伪装成连接未结束

1.0 形状下,RUN_FINISHED 可以携带中断结果,而不仅是成功结束。TypeScript 客户端保存 pendingInterrupts,后续 runAgent 初始化会检查 resume 是否覆盖待处理中断。

这让"等用户回答"有了自己的身份。过期中断也不是无限卡住线程:客户端允许用 status: "cancelled" 的恢复项解除它,但不再允许把过期问题作为普通答案提交。

客户端维护这个检查,并不意味着后端已经有持久化检查点。刷新页面后能否继续、另一个设备能否接手、原始任务是否还存在,都取决于服务端适配器和存储设计。

🔬 技术架构深度解析

从 POST 到状态更新,中间经过了什么

下面对应 TypeScript HttpAgent 的主执行路径,不把协议描述、传输和 UI 渲染画成同一层:

text 复制代码
应用:messages / state / tools / context / resume
               |
       prepareRunAgentInput
               |
     出站约束 enforceOutgoingInput
               |
  HTTP POST:RunAgentInput -> Agent 服务端
               |
  响应头 + Uint8Array 字节块
               |
  transformHttpEventStream
        /                  \
  SSE JSON               Protobuf
        \                  /
       兼容边界 + 应用中间件
               |
       enforceEvents:字段与结构
               |
       transformChunks:展开简写事件
               |
       verifyEvents:运行/消息/工具顺序
               |
       defaultApplyEvents:串行归并
               |
       messages / state mutation
               |
     订阅回调 -> 应用自行渲染 UI

agent/http.ts 的 requestInit 默认使用 POST,发送 JSON,声明 Accept: text/event-stream,并把当前 AbortController.signal 放进请求。它并不是浏览器 EventSource 的简单封装:请求需要携带消息历史和状态,使用的是 fetch 加流式读取。

run/http-request.ts 将 HTTP 结果拆成响应头事件和数据事件。非成功状态码会读取错误响应,构建带有 status、payload 的错误;拿不到响应体 reader 也会失败。取消订阅时,它会尝试取消尚未结束的 reader,避免消费者已经放弃后,传输层还在继续读取。

SSE 拆包必须跨越网络分块边界

一个网络块不等于一个事件,更不等于一条消息。UTF-8 汉字可能跨块,某个块也可能包含多个事件。

transform/sse.ts 使用流式 TextDecoder,把解码后的文本累积到 buffer,再按双换行拆出完整事件,保留未完成尾段。每个事件中只收集 data: 行,多行数据用换行连接后执行 JSON.parse。

有两个细节值得接入方记住。

第一,解析器忽略 event、id、retry 等 SSE 字段。不能因为服务端写了 SSE 的 id:,就认为这个客户端已经实现断线续传游标或自动重放。

第二,未闭合尾段的限制是 10 * 1024 * 1024 个解码后字符,不是整个会话的 10MB 网络预算,也不是精确的 UTF-8 字节上限。它主要防止服务端长期不发送边界,让字符串尾段无限积累。完整事件会在拆包后移出这个尾段,但单次大块带来的瞬时内存和消息历史内存,仍需另算。

实现按 \n\n 拆帧,服务端最稳妥的输出就是下面示例采用的 LF 双换行。不要仅凭"使用 SSE"就推定所有边界写法、重连策略都自动兼容。

宽容转换和严格校验为什么分开

transform/http.ts 在 SSE JSON 层只要求帧是非数组对象,并且有非空字符串 type。它没有在此时执行完整事件 schema 校验。

这给兼容中间件留下空间:旧形状或后端自定义形状可以先被翻译,再进入标准约束。主运行路径接下来按顺序执行 enforceEvents、transformChunks、verifyEvents。先约束原始 chunk,再展开它,避免一个错误字段在展开时被丢掉,反而看起来像合法消息。

enforce/enforce.ts 的容错不是"什么都接受":

输入情况 当前 TypeScript 处理方式
中间件仍未翻译的未知事件类型 发出警告并丢弃
已知事件中不被 schema 接受的额外材料 按 schema 剥离并警告
协议明确描述的字段类型不合法 失败,进入运行错误路径
事件结构超过配置的条目预算 以约束限制错误终止

不是所有额外键都会被删。比如协议允许开放内容的对象、JSON Patch 操作中的扩展成员,与封闭事件外壳的规则不同。把整个机制写成"自动清洗一切未知字段"并不准确。

约束也不是业务授权。一个完全符合 schema 的 delete_order 调用,依然可能没有权限。服务端必须单独验证用户身份、资源归属和操作条件。

verifyEvents 检查时序,但不替你证明业务完成

verify/verify.ts 为运行、消息、工具、步骤和子代理维护状态。文本内容事件必须找到已开始的消息,工具参数必须找到已开始的调用。RUN_FINISHED 到来时,尚未关闭的文本流、工具参数流或步骤会导致错误。

这些检查能抓住适配器常见的问题,例如先发内容后发开始事件,或者忘记结束一条消息就宣布运行完成。它们解决的是事件生命周期一致性。

工具还有另一个阶段:参数流关闭后,结果可能尚未返回。客户端会在成功结束时向订阅者提供 pendingToolCallIds;生产者给出的非空列表优先,否则按本轮开始过而未收到结果的调用推导。于是,运行结束并不等于所有前端工具都已经执行完毕,界面不能只监听 RUN_FINISHED 就把所有工具卡片标成成功。

同理,验证器没有给订单系统增加事务,也没有证明数据库提交成功。后端发出事件之前,应该明确它表达的是"准备执行""已发送请求",还是"业务存储已确认"。

状态归并的失败语义比接口名字更重要

apply/default.ts 用串行归并处理事件。收到状态快照时,它复制快照并替换归并器内部状态;收到 delta 时,先复制补丁,再调用:

typescript 复制代码
jsonpatch.applyPatch(state, structuredClone_(delta), true, false)

后两个参数分别启用操作校验和关闭原地修改。传入补丁的值也被复制,避免事件对象、归并器状态和应用拿到的对象意外共享可变引用。状态发生变化后,再复制输出给应用。

这不是免费操作。大状态频繁更新,会产生整份状态复制成本;很长的聊天历史也会持续占据客户端内存。减少线上补丁体积,不等于消除了客户端的 CPU 和内存消耗。应把需要共享的业务状态限制在页面实际用到的范围内,别把整个后端工作区直接放进去。

补丁失败时,默认实现捕获异常并 console.warn,没有把它直接抛成整次运行失败。失败补丁不会产出其预期的新状态;此前订阅者产生的修改则可能仍然存在。若业务对状态一致性敏感,不能只看网络正常、Promise 正常结束,还应检测状态版本或在异常后重新请求权威快照。

Promise 完成和 Agent 成功不能画等号

这里有一个很容易写错的接口细节:runAgent() 返回 Promise,不是拿来直接 .subscribe() 的 Observable。底层 run(input) 才是事件流接口。应用接收逐事件通知,通常使用 runAgent 的第二个订阅者参数。

生产者发送 RUN_ERROR 时,默认归并器触发 onRunErrorEvent,但这条协议事件本身不会使 runAgent() 的 Promise reject。HTTP 失败、解析异常等传输或客户端错误则走另一条异常路径。源码测试专门区分了这两种情况。

因此,页面不能只写一个 try/catch 就认为覆盖了所有 Agent 失败。业务错误需要监听事件,传输异常需要捕获 Promise;已经显示的部分文字也不应因为后续断网而无条件清空。

停止连接也有边界。HttpAgent.abortRun() 会中止本地请求,但服务端副作用有没有停止,需要服务端自己处理断开与取消。即使页面不再接收事件,已经发给外部系统的订单操作也可能继续完成。

📖 README 核心内容摘要

README 把 AG-UI 定位成面向应用的轻量事件协议,并提供 HTTP 参考实现、客户端和多种框架接入。阅读时可以把材料分开看:

  • 协议和核心类型回答事件长什么样、各字段表达什么。
  • @ag-ui/client 回答如何收流、校验、归并以及通知应用。
  • 各框架集成回答后端原有执行事件如何映射过来。
  • Dojo 示例展示聊天、共享状态、前端工具等交互,不能直接替代你的生产权限和持久化方案。

仓库列出的集成同时有 Supported 和 In Progress 状态,不能把名字出现在列表中当作全部能力已经可用。选框架时应拿自己的关键流程验证:有无状态快照、工具结果怎样关联、人工中断怎样恢复,以及框架异常怎样映射。

传输无关也需要具体到实现。TypeScript HTTP 客户端根据响应 content-type 选择 Protobuf 解析器或 SSE 路径;Python 的 EventEncoder 在这个版本中即使接收 accept 参数,仍然输出 SSE。一个 SDK 有二进制支持,不能推导所有 SDK 都已具备相同的协商和编码能力。

至于生成式 UI,协议可以承载工具调用、活动或结构化内容,但浏览器里最终呈现什么组件,仍然需要 UI 层解释与渲染。AG-UI 不会因为收到一个 JSON,就自动知道你项目里订单卡片的样式、校验规则和按钮权限。

🚀 快速上手

先做一个不连接模型、没有业务副作用的本地实验。目标是看清楚事件怎样进入真实客户端,最终变成消息和状态,而不是一开始就安装完整 Agent 平台。

用真实 TypeScript 客户端消费固定 SSE

准备有原生 fetch 和 Response 的现代 Node 环境,下面以 Node 20 或更新版本为前提。建立单独目录,并固定包版本:

bash 复制代码
mkdir ag-ui-demo
cd ag-ui-demo
npm init -y
npm install --ignore-scripts @ag-ui/client@1.0.4 @ag-ui/core@1.0.4 zod@3.25.76

将下面内容保存为 demo.mjs。这里注入本地固定响应,URL 只是接口配置,代码不会向该地址发网络请求。fetch 替身模拟的是传输输入,事件解析、校验和归并仍由真实 SDK 完成。

javascript 复制代码
import assert from "node:assert/strict";
import { HttpAgent } from "@ag-ui/client";

const events = [
  { type: "RUN_STARTED", threadId: "demo-thread", runId: "demo-run", protocolVersion: "1.0" },
  { type: "STATE_SNAPSHOT", snapshot: { order: { status: "draft" } } },
  { type: "STATE_DELTA", delta: [{ op: "replace", path: "/order/status", value: "ready" }] },
  { type: "TEXT_MESSAGE_START", messageId: "m1", role: "assistant" },
  { type: "TEXT_MESSAGE_CONTENT", messageId: "m1", delta: "订单已就绪" },
  { type: "TEXT_MESSAGE_END", messageId: "m1" },
  { type: "RUN_FINISHED", threadId: "demo-thread", runId: "demo-run" },
];
const sse = events.map(e => `data: ${JSON.stringify(e)}\n\n`).join("");
const agent = new HttpAgent({
  url: "http://localhost:8000/agent",
  threadId: "demo-thread",
  fetch: async (_url, init) => {
    const input = JSON.parse(init.body);
    assert.equal(input.runId, "demo-run");
    assert.equal(init.method, "POST");
    return new Response(sse, { headers: { "Content-Type": "text/event-stream" } });
  },
});
let output = "";
await agent.runAgent({ runId: "demo-run" }, {
  onTextMessageContentEvent({ event }) { output += event.delta; },
});
assert.equal(output, "订单已就绪");
assert.equal(agent.state.order.status, "ready");
assert.equal(agent.messages.find(m => m.id === "m1").content, output);
console.log(JSON.stringify({ output, state: agent.state, messageCount: agent.messages.length }));

运行:

bash 复制代码
node demo.mjs

这个固定输入示例的实际输出是:

json 复制代码
{"output":"订单已就绪","state":{"order":{"status":"ready"}},"messageCount":1}

它验证的是固定事件流经过客户端后的文本和状态结果,不涉及模型质量、真实服务端性能或业务订单系统。接真实接口时,去掉自定义 fetch,把 url 改为自己的 Agent 服务地址,再处理鉴权、跨域和异常。

Python 服务端怎样编码同样的事件

Python 包适合在服务端构造事件模型,避免手写线上的 camelCase 字段。另建虚拟环境后安装固定版本:

bash 复制代码
python3 -m venv .venv
source .venv/bin/activate
python -m pip install 'ag-ui-protocol==1.0.0' 'pydantic==2.12.3'

下面是可直接放进 encode_demo.py 的编码示例,不是一个已启动的 HTTP 服务:

python 复制代码
import json
from ag_ui.core import TextMessageContentEvent, StateDeltaEvent
from ag_ui.encoder import EventEncoder

encoder = EventEncoder()
event = TextMessageContentEvent(message_id="m1", delta="订单已就绪")
frame = encoder.encode(event)
assert frame.startswith("data: ") and frame.endswith("\n\n")
assert json.loads(frame[6:])["messageId"] == "m1"
print(frame, end="")

patch = StateDeltaEvent(delta=[
    {"op": "add", "path": "/note", "value": None}
])
wire = json.loads(encoder.encode(patch)[6:])
assert wire["delta"][0]["value"] is None
bash 复制代码
python encode_demo.py

模型使用 message_id,线上输出则使用 messageId。可选字段缺省值与业务 JSON 中的空值也不能混为一谈:可选的空字段可以省略,补丁里明确设置的 value: null 却是业务数据,必须保留。服务端把编码结果放进流式 HTTP 响应时,还需要发送对应的运行开始、消息开始和结束等事件;单独一条内容事件不能构成合法的完整运行。

后续接入时,建议先补两种错误用例:让服务端返回 HTTP 错误,确认 Promise 异常处理;再返回协议里的 RUN_ERROR,确认界面确实读取了 onRunErrorEvent。这两种失败如果只验证其中一种,用户很容易遇到"按钮停了,但页面还显示成功"的情况。

📊 增长速度与社区热度

本次快照中,AG-UI 位列第 2,Stars 为 18,185,Forks 为 1,878。这说明它已有一定关注度,但单个时点的总量不能推出当天涨了多少,也不能拿总星数除以仓库年龄当成近期增长速度。

对这种协议项目,更值得观察的是适配器能否正确处理相同的交互:同一条消息怎样关闭、状态补丁失败后怎样恢复、中断怎样继续。集成名称多只是一个入口,真正的互操作质量要看这些细节。仓库中的客户端测试已经覆盖生产者错误、约束边界、待处理工具调用和状态更新等不同路径,比一段"支持所有框架"的宣传更有参考价值。

以下是 2026-11-16 采集到的完整日榜,顺序与该次快照一致:

排名 仓库
1 dream-num/univer
2 ag-ui-protocol/ag-ui
3 google-labs-code/stitch-skills
4 backnotprop/plannotator
5 ChromeDevTools/chrome-devtools-mcp
6 alibaba/open-code-review
7 Tencent/LoopForge
8 ggml-org/ggml
9 elementalsouls/Claude-BugHunter
10 GoogleChrome/modern-web-guidance-src
11 tradermonty/claude-trading-skills
12 NVIDIA/SkillEvaluator

🎯 适用场景

已有一个业务前端,准备同时接入几种 Agent 后端,可以把 AG-UI 放在后端适配层和页面之间。前端围绕标准消息、状态变化和工具事件写交互,后端框架变化集中在适配器。收益取决于你的交互是否真的能映射到这套语义,而不只是把自定义事件换个名字。

有订单、工单、表单或编辑器状态的助手,也比较适合。让 Agent 更新一个明确的结构化状态,通常比要求前端从自然语言里提取业务字段可靠。不过,提交表单仍应走业务接口,状态事件最好表达已确认事实或待确认建议,不要把聊天状态当成最终交易凭证。

需要人工确认的长任务可以利用中断及恢复机制。前提是服务端保存任务和检查点,并为用户回答建立访问控制。客户端的待处理中断列表只是流程的一部分。

如果页面只是显示一段流式摘要,没有工具、共享状态或复杂生命周期,直接使用简单的流式接口可能更省维护。引入 AG-UI 意味着需要理解和测试事件顺序、兼容行为以及版本组合,复杂度不是零。

它也不适合被当作现成的多用户协同引擎。JSON Patch 不提供冲突消解;本地请求取消不保证远端操作撤回;消息 ID 不提供幂等事务。对财务、订单等关键写操作,应在业务层维护幂等键、权限与执行回执,页面事件只负责呈现这些事实。

💡 总结

AG-UI 提供了一条可读懂、可实现的 Agent 到前端的事件接口。它把消息、工具参数、共享状态和中断拆开表达,客户端再用独立阶段处理兼容、约束、时序和归并。

接入前最需要想清楚的,是你的应用怎样区分"流结束""运行结束""工具执行完毕"和"业务写入成功"。AG-UI 能帮助表达这些边界,但不能替业务系统决定它们。先用一个真实页面跑通状态变化和失败恢复,再扩展到更多框架,会比仅比较集成数量更有用。

相关推荐
吴长建先生重名了1 小时前
一个任务调度系统崩溃 Bug 从性能压测中暴露的真相
github
一条Go4 小时前
Webhook 签名:钉钉、企业微信、飞书的四种算法差异
后端·架构·github
一条Go5 小时前
开源新生代雷达 · 第 12 期
github
徐小夕6 小时前
CADViewer-Skill:让 Agent 原生支持 DWG 解析、可视化图统计、图纸导出
前端·vue.js·github
怕浪猫16 小时前
这个十几个agent 协作项目值得关注
人工智能·面试·github
wflynn1 天前
GitHub 今日推荐|Stela:在 PC 上直接启动 macOS 的翻译层
rust·开源·github
wflynn1 天前
GitHub 日榜趋势速报 | 2026-11-14
开源·github
一条Go1 天前
接收方合并去重:同一个人为什么只该收到一次通知
后端·架构·github