我给一个 agent 接前端,接口跑通了,事件一个不少,文本也对,看上去一切正常。然后我故意往流里塞了一个协议里根本不存在的类型,前端没吭声,照单全收。

这件事让我把 AG-UI 的客户端代码从头翻了一遍。

先说清 AG-UI 站在哪一层

agent 生态里现在有三个协议,各管一段。MCP 管 agent 和工具、数据之间的连接。A2A 管 agent 和 agent 之间怎么分工。AG-UI 管的是第三段,agent 和用户界面之间那条流。

这三段的划分是官方自己在文档里排的表。我写过 MCP,也写过 A2UI 那个「agent 画界面」的东西,AG-UI 是我一直没碰的那一格。

需要先把 A2UI 和 AG-UI 分开,名字太像。官方文档专门放了一句解释,原文写道:A2UI 是生成式 UI 规范,让 agent 交付 UI 组件;AG-UI 是 Agent 与 User 的交互协议,把 agent 前端接到任意 agent 后端。一个管界面长什么样,一个管数据怎么来回流。

三个协议分层:AG-UI 补的是 agent 与界面之间那一段

1.0 是九月底的事,不是今天

GitHub 上这个仓库现在 20,085 个 star,2,071 个 fork,TypeScript 写的,MIT。仓库建在 2025 年 5 月 7 日,末次 push 是 2026 年 11 月 18 日凌晨四点。

1.0 的正式公告我在官方博客上找到,日期是 2026 年 9 月 30 日。

npm 上 @ag-ui/client 累计发过 83 个版本,当前 latest 是 1.0.5,我装的就是这个。所以它不是这两天才出的东西,是一份已经跑了一个半月的稳定规范。

文档说十六种,SDK 里是三十一个

我先把事件类型枚举打出来。官方文档的架构页原话是:agent 在执行期间需要发出这 16 种标准事件类型中的任意一种。

但 SDK 里 EventType 去重之后是 31 个。

按官方文档自己分的类数一遍:生命周期 3 个,文本消息 4 个,工具调用 5 个,状态管理 2 个,活动进度 2 个,子 agent 3 个,reasoning 家族 7 个,步骤 2 个,其余 3 个是自定义、原始数据和消息快照。

多出来的主要是 reasoning 那 7 个,占全部 31 的 22.6%。1.0 的变更日志里写着,0.x 时代的 THINKING 那一族事件全部退役,换成 reasoning 这一族。退役的形状在兼容层做翻译,不是直接砍掉。

十六这个数字大概是 0.x 时代留下的,文档那一页没跟上。这件事本身不严重,但它是我决定自己跑一遍的起点。

31 种事件按官方分类清点

我用官方客户端跑了五个场景

装了 @ag-ui/client 1.0.5,起一个本地 SSE 服务反过来给它喂事件,五个场景,结果如下。

第一个场景,6 条全合法的事件,收到 6 条,文本拼成「你好,这是 AG-UI。」,正常。

第二个,在中间插一条协议里不存在的 TOTALLY_UNKNOWN_EVENT。客户端收到 6 条,那条未知事件原样出现在订阅回调里,既没丢,也没警告。

第三个,首块 TEXT_MESSAGE_CONTENT 不带 messageId。规范写着首块必须带。客户端收下,文本照拼,一个字没少。

第四个,第二块换了一个 messageId。规范里这属于值冲突,是致命的。客户端把两块拼成了一条,前者被后者的内容覆盖,输出变成「第一块换了 id」。

第五个,只发 RUN_STARTED 不开 RUN_FINISHED。流结束就结束了,没有任何提示。

五条里三条违规,客户端一条都没拦。

五个场景在默认 run() 路径上的实测结果

那道校验要自己接

问题不在 SDK 没实现。它实现了,函数就在导出的列表里,叫 enforceEvents。

问题在于它默认不在这条路上。run() 拿到 SSE 流,解析、翻译、推给订阅者,整条链上没有强制校验这一环。

把同一批事件改走 enforceEvents({}),结论立刻反过来了。

未知事件被丢掉,同时打一行警告:协议里没有描述这个事件,也没有任何 middleware 翻译过它。

首块缺 messageId,直接抛 ZodError,报错里明确指到 path: ["messageId"],期望是字符串。delta 传数字而不是字符串,同样抛 ZodError,指到 path: ["delta"]。

多塞一个规范外的字段,字段被剥掉,附一句「在 RUN_STARTED 上移除了无法识别的内容」。

合法的那批 5 条,全过。

同一批事件挂上 enforceEvents 之后的对照

未知和格式错误,分寸不一样

这套行为里我最想抄的是它对两种错误的区分。

不认识的东西,丢,但只警告,不中断。理由很实在:协议会往前走,老客户端碰到新事件是常态,因为一个不认识的类型就把整条流打断,等于让所有客户端和协议版本死绑。

认识的类型但内容不对,抛。因为这个没有第二种解释,messageId 该是字符串你给了数字,说明发送端已经坏了,继续往下走只会把错误藏得更深。

这条分寸官方在 spec 的变更日志里写成了 normative 条款,用的是 BCP 14 那套措辞。

未知事件与格式错误的两种处理

为什么默认不接这道校验

我倒回去想了一下,这个默认值不算错。

run() 是给「我就想快点看到字」的场景用的,接上就能显示,不用管协议细节。真正需要严格的时候,是你自己写客户端、拿别人的 agent 当输入源,这时候脏数据会直接变成 UI 上的错乱。

官方把开关留给了你,位置也标得清楚,但它不会替你按下去。

我现在的做法

接 AG-UI 的时候,客户端这一侧我会显式挂上 enforceEvents,哪怕日志多几行。

理由很直接:agent 后端的实现可以换,LangChain、Mastra、Claude 的托管 agent 都能接上来,只要它吐的是 AG-UI 事件。而这批后端的质量参差,前端是唯一能统一把关的地方。放过去的事件,到头来都变成用户看见的怪界面。

顺带一个细节,这套 SDK 的二进制通道也实现了,HTTP 加 Protobuf,4 字节长度前缀的帧,从同一份 schema 生成。文本走 SSE 够用,量大了就有意义。

落到你的场景上

如果你的 agent 只接自家后端、自家人写的事件,默认那条松路就够,出问题也能两边一起改。

但只要你打算让别人家的 agent 接进来,或者你想把这份前端留着接第三个、第四个后端,那道校验就该开。它不是安全措施,是把「协议允许什么」这件事从文档搬进代码。

你现在的 agent 前端,是自己解析流还是用了这套协议?如果用了,那道 enforce 你开了没有。