<?xml version="1.0" encoding="utf-8" standalone="yes"?><rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/"><channel><title>AG-UI on Trevor's Blog</title><link>https://hitrevor.com/tags/ag-ui/</link><description>Recent content in AG-UI on Trevor's Blog</description><generator>Hugo</generator><language>zh-CN</language><lastBuildDate>Wed, 18 Nov 2026 16:00:00 +0800</lastBuildDate><atom:link href="https://hitrevor.com/tags/ag-ui/index.xml" rel="self" type="application/rss+xml"/><item><title>AG-UI 1.0：31 种事件，客户端默认一条都不校验</title><link>https://hitrevor.com/posts/agui/</link><pubDate>Wed, 18 Nov 2026 16:00:00 +0800</pubDate><guid>https://hitrevor.com/posts/agui/</guid><description>用官方 client 1.0.5 跑了五个场景，三条违反规范的输入全被静默放过。spec 里的 fatal，要自己接 enforceEvents 才生效。</description><content:encoded><![CDATA[<p>我给一个 agent 接前端，接口跑通了，事件一个不少，文本也对，看上去一切正常。然后我故意往流里塞了一个协议里根本不存在的类型，前端没吭声，照单全收。</p>
<p>这件事让我把 AG-UI 的客户端代码从头翻了一遍。</p>
<h2 id="先说清-ag-ui-站在哪一层">先说清 AG-UI 站在哪一层</h2>
<p>agent 生态里现在有三个协议，各管一段。MCP 管 agent 和工具、数据之间的连接。A2A 管 agent 和 agent 之间怎么分工。AG-UI 管的是第三段，agent 和用户界面之间那条流。</p>
<p>这三段的划分是官方自己在文档里排的表。我写过 MCP，也写过 A2UI 那个「agent 画界面」的东西，AG-UI 是我一直没碰的那一格。</p>
<p>需要先把 A2UI 和 AG-UI 分开，名字太像。官方文档专门放了一句解释，原文写道：A2UI 是生成式 UI 规范，让 agent 交付 UI 组件；AG-UI 是 Agent 与 User 的交互协议，把 agent 前端接到任意 agent 后端。一个管界面长什么样，一个管数据怎么来回流。</p>
<p><img alt="三个协议分层：AG-UI 补的是 agent 与界面之间那一段" loading="lazy" src="/images/agui/fig1.png"></p>
<h2 id="10-是九月底的事不是今天">1.0 是九月底的事，不是今天</h2>
<p>GitHub 上这个仓库现在 20,085 个 star，2,071 个 fork，TypeScript 写的，MIT。仓库建在 2025 年 5 月 7 日，末次 push 是 2026 年 11 月 18 日凌晨四点。</p>
<p>1.0 的正式公告我在官方博客上找到，日期是 2026 年 9 月 30 日。</p>
<p>npm 上 <code>@ag-ui/client</code> 累计发过 83 个版本，当前 latest 是 1.0.5，我装的就是这个。所以它不是这两天才出的东西，是一份已经跑了一个半月的稳定规范。</p>
<h2 id="文档说十六种sdk-里是三十一个">文档说十六种，SDK 里是三十一个</h2>
<p>我先把事件类型枚举打出来。官方文档的架构页原话是：agent 在执行期间需要发出这 16 种标准事件类型中的任意一种。</p>
<p>但 SDK 里 <code>EventType</code> 去重之后是 31 个。</p>
<p>按官方文档自己分的类数一遍：生命周期 3 个，文本消息 4 个，工具调用 5 个，状态管理 2 个，活动进度 2 个，子 agent 3 个，reasoning 家族 7 个，步骤 2 个，其余 3 个是自定义、原始数据和消息快照。</p>
<p>多出来的主要是 reasoning 那 7 个，占全部 31 的 22.6%。1.0 的变更日志里写着，0.x 时代的 THINKING 那一族事件全部退役，换成 reasoning 这一族。退役的形状在兼容层做翻译，不是直接砍掉。</p>
<p>十六这个数字大概是 0.x 时代留下的，文档那一页没跟上。这件事本身不严重，但它是我决定自己跑一遍的起点。</p>
<p><img alt="31 种事件按官方分类清点" loading="lazy" src="/images/agui/fig2.png"></p>
<h2 id="我用官方客户端跑了五个场景">我用官方客户端跑了五个场景</h2>
<p>装了 <code>@ag-ui/client</code> 1.0.5，起一个本地 SSE 服务反过来给它喂事件，五个场景，结果如下。</p>
<p>第一个场景，6 条全合法的事件，收到 6 条，文本拼成「你好，这是 AG-UI。」，正常。</p>
<p>第二个，在中间插一条协议里不存在的 <code>TOTALLY_UNKNOWN_EVENT</code>。客户端收到 6 条，那条未知事件原样出现在订阅回调里，既没丢，也没警告。</p>
<p>第三个，首块 <code>TEXT_MESSAGE_CONTENT</code> 不带 <code>messageId</code>。规范写着首块必须带。客户端收下，文本照拼，一个字没少。</p>
<p>第四个，第二块换了一个 <code>messageId</code>。规范里这属于值冲突，是致命的。客户端把两块拼成了一条，前者被后者的内容覆盖，输出变成「第一块换了 id」。</p>
<p>第五个，只发 <code>RUN_STARTED</code> 不开 <code>RUN_FINISHED</code>。流结束就结束了，没有任何提示。</p>
<p>五条里三条违规，客户端一条都没拦。</p>
<p><img alt="五个场景在默认 run() 路径上的实测结果" loading="lazy" src="/images/agui/fig3.png"></p>
<h2 id="那道校验要自己接">那道校验要自己接</h2>
<p>问题不在 SDK 没实现。它实现了，函数就在导出的列表里，叫 <code>enforceEvents</code>。</p>
<p>问题在于它默认不在这条路上。<code>run()</code> 拿到 SSE 流，解析、翻译、推给订阅者，整条链上没有强制校验这一环。</p>
<p>把同一批事件改走 <code>enforceEvents({})</code>，结论立刻反过来了。</p>
<p>未知事件被丢掉，同时打一行警告：协议里没有描述这个事件，也没有任何 middleware 翻译过它。</p>
<p>首块缺 <code>messageId</code>，直接抛 ZodError，报错里明确指到 <code>path: [&quot;messageId&quot;]</code>，期望是字符串。<code>delta</code> 传数字而不是字符串，同样抛 ZodError，指到 <code>path: [&quot;delta&quot;]</code>。</p>
<p>多塞一个规范外的字段，字段被剥掉，附一句「在 RUN_STARTED 上移除了无法识别的内容」。</p>
<p>合法的那批 5 条，全过。</p>
<p><img alt="同一批事件挂上 enforceEvents 之后的对照" loading="lazy" src="/images/agui/fig4.png"></p>
<h2 id="未知和格式错误分寸不一样">未知和格式错误，分寸不一样</h2>
<p>这套行为里我最想抄的是它对两种错误的区分。</p>
<p>不认识的东西，丢，但只警告，不中断。理由很实在：协议会往前走，老客户端碰到新事件是常态，因为一个不认识的类型就把整条流打断，等于让所有客户端和协议版本死绑。</p>
<p>认识的类型但内容不对，抛。因为这个没有第二种解释，<code>messageId</code> 该是字符串你给了数字，说明发送端已经坏了，继续往下走只会把错误藏得更深。</p>
<p>这条分寸官方在 spec 的变更日志里写成了 normative 条款，用的是 BCP 14 那套措辞。</p>
<p><img alt="未知事件与格式错误的两种处理" loading="lazy" src="/images/agui/fig5.png"></p>
<h2 id="为什么默认不接这道校验">为什么默认不接这道校验</h2>
<p>我倒回去想了一下，这个默认值不算错。</p>
<p><code>run()</code> 是给「我就想快点看到字」的场景用的，接上就能显示，不用管协议细节。真正需要严格的时候，是你自己写客户端、拿别人的 agent 当输入源，这时候脏数据会直接变成 UI 上的错乱。</p>
<p>官方把开关留给了你，位置也标得清楚，但它不会替你按下去。</p>
<h2 id="我现在的做法">我现在的做法</h2>
<p>接 AG-UI 的时候，客户端这一侧我会显式挂上 <code>enforceEvents</code>，哪怕日志多几行。</p>
<p>理由很直接：agent 后端的实现可以换，LangChain、Mastra、Claude 的托管 agent 都能接上来，只要它吐的是 AG-UI 事件。而这批后端的质量参差，前端是唯一能统一把关的地方。放过去的事件，到头来都变成用户看见的怪界面。</p>
<p>顺带一个细节，这套 SDK 的二进制通道也实现了，HTTP 加 Protobuf，4 字节长度前缀的帧，从同一份 schema 生成。文本走 SSE 够用，量大了就有意义。</p>
<h2 id="落到你的场景上">落到你的场景上</h2>
<p>如果你的 agent 只接自家后端、自家人写的事件，默认那条松路就够，出问题也能两边一起改。</p>
<p>但只要你打算让别人家的 agent 接进来，或者你想把这份前端留着接第三个、第四个后端，那道校验就该开。它不是安全措施，是把「协议允许什么」这件事从文档搬进代码。</p>
<p>你现在的 agent 前端，是自己解析流还是用了这套协议？如果用了，那道 enforce 你开了没有。</p>
]]></content:encoded></item></channel></rss>