<?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/en/tags/ag-ui/</link><description>Recent content in AG-UI on Trevor's Blog</description><generator>Hugo</generator><language>en-US</language><lastBuildDate>Wed, 18 Nov 2026 16:00:00 +0800</lastBuildDate><atom:link href="https://hitrevor.com/en/tags/ag-ui/index.xml" rel="self" type="application/rss+xml"/><item><title>AG-UI 1.0: 31 Event Types, and a Client That Validates None of Them by Default</title><link>https://hitrevor.com/en/posts/agui/</link><pubDate>Wed, 18 Nov 2026 16:00:00 +0800</pubDate><guid>https://hitrevor.com/en/posts/agui/</guid><description>Five scenarios against the official client 1.0.5: three spec violations, all silently accepted. The fatal checks in the spec only fire once you wire in enforceEvents yourself.</description><content:encoded><![CDATA[<p>I wired an agent up to a front end. The endpoint answered, every event arrived, the text was right, everything looked fine. Then I deliberately pushed a type that does not exist in the protocol at all into the stream. The front end said nothing and swallowed it whole.</p>
<p>That one move made me read the AG-UI client code from top to bottom.</p>
<h2 id="first-which-layer-ag-ui-sits-in">First, which layer AG-UI sits in</h2>
<p>The agent ecosystem has three protocols now, each owning one segment. MCP handles the connection between an agent and its tools and data. A2A handles how agents split work among themselves. AG-UI handles the third segment, the stream between the agent and the user interface.</p>
<p>That three way split is a table the project itself lays out in its docs. I have written about MCP, and about A2UI, the one where the agent draws the interface. AG-UI was the cell I had never touched.</p>
<p>A2UI and AG-UI need separating first, the names are too close. The docs keep a dedicated sentence for it, and the original says: A2UI is a generative UI spec, letting an agent deliver UI components; AG-UI is the Agent and User interaction protocol, wiring an agent front end to any agent backend. One governs what the interface looks like, the other governs how data flows back and forth.</p>
<p><img alt="Three protocol layers, with AG-UI filling the segment between agent and interface" loading="lazy" src="/images/agui/fig1.png"></p>
<h2 id="10-landed-at-the-end-of-september-not-today">1.0 landed at the end of September, not today</h2>
<p>On GitHub the repo now has 20,085 stars and 2,071 forks, is written in TypeScript, and is MIT licensed. It was created on 2025-05-07, and the last push was at 4am on 2026-11-18.</p>
<p>I found the official 1.0 announcement on the project blog, dated 2026-09-30.</p>
<p><code>@ag-ui/client</code> has published 83 versions on npm in total, and the current latest is 1.0.5, which is what I installed. So this is not something that appeared in the last couple of days. It is a stable spec that has been running for a month and a half.</p>
<h2 id="the-docs-say-sixteen-the-sdk-has-thirty-one">The docs say sixteen, the SDK has thirty one</h2>
<p>I dumped the event type enum first. The architecture page of the docs says, verbatim, that during execution an agent needs to emit any of these 16 standard event types.</p>
<p>But in the SDK, <code>EventType</code> comes to 31 entries after dedup.</p>
<p>Counting by the project&rsquo;s own categories: 3 lifecycle, 4 text message, 5 tool call, 2 state management, 2 activity progress, 3 sub agent, 7 in the reasoning family, 2 step, and the remaining 3 are custom, raw data and message snapshot.</p>
<p>The surplus is mostly those 7 reasoning events, 22.6% of all 31. The 1.0 changelog says the whole THINKING family from the 0.x era is retired and replaced by the reasoning family. The retired shapes get translated in the compatibility layer rather than simply cut off.</p>
<p>Sixteen is probably a leftover from the 0.x era, and that docs page never caught up. Not serious on its own, but it is the reason I decided to run it myself.</p>
<p><img alt="The 31 event types counted against the official categories" loading="lazy" src="/images/agui/fig2.png"></p>
<h2 id="i-ran-five-scenarios-against-the-official-client">I ran five scenarios against the official client</h2>
<p>With <code>@ag-ui/client</code> 1.0.5 installed, I stood up a local SSE server and fed it events from the other direction. Five scenarios, results below.</p>
<p>Scenario one, 6 fully legal events, 6 received, text assembled into &ldquo;Hello, this is AG-UI.&rdquo; All normal.</p>
<p>Scenario two, drop a <code>TOTALLY_UNKNOWN_EVENT</code> that does not exist in the protocol into the middle. The client received 6, and the unknown event turned up in the subscription callback as is, neither dropped nor warned about.</p>
<p>Scenario three, the first <code>TEXT_MESSAGE_CONTENT</code> chunk arrives without a <code>messageId</code>. The spec says the first chunk must carry one. The client took it, assembled the text, not a character missing.</p>
<p>Scenario four, the second chunk switches to a different <code>messageId</code>. In the spec that is a value conflict, and it is fatal. The client merged the two chunks into one, the former overwritten by the content of the latter, and the output became &ldquo;the first chunk changed its id&rdquo;.</p>
<p>Scenario five, only <code>RUN_STARTED</code> with no <code>RUN_FINISHED</code>. The stream ended and that was that, no notice at all.</p>
<p>Three of the five broke the spec, and the client stopped none of them.</p>
<p><img alt="Five scenarios measured on the default run() path" loading="lazy" src="/images/agui/fig3.png"></p>
<h2 id="that-validation-is-something-you-wire-up-yourself">That validation is something you wire up yourself</h2>
<p>The problem is not that the SDK never implemented it. It did, and the function sits in the export list under the name <code>enforceEvents</code>.</p>
<p>The problem is that by default it is not on this path. <code>run()</code> takes the SSE stream, parses it, translates it, pushes it to subscribers, and nowhere along that chain is there a mandatory validation step.</p>
<p>Send the same batch of events through <code>enforceEvents({})</code> and the conclusions flip immediately.</p>
<p>Unknown events get dropped, with a warning line alongside: the protocol describes no such event, and no middleware translated it.</p>
<p>A first chunk missing <code>messageId</code> throws ZodError outright, and the error points straight at <code>path: [&quot;messageId&quot;]</code>, expecting a string. Passing a number for <code>delta</code> instead of a string also throws ZodError, pointing at <code>path: [&quot;delta&quot;]</code>.</p>
<p>One extra field outside the spec gets stripped, with a note: removed unrecognized content on RUN_STARTED.</p>
<p>The legal batch of 5 all passed.</p>
<p><img alt="The same batch of events with enforceEvents attached, side by side" loading="lazy" src="/images/agui/fig4.png"></p>
<h2 id="unknown-and-malformed-get-different-treatment">Unknown and malformed get different treatment</h2>
<p>What I most want to copy from this behavior is how it separates the two kinds of error.</p>
<p>Something unrecognized gets dropped, but with a warning only, no abort. The reasoning is practical: the protocol moves forward, and an old client meeting a new event is normal. Interrupting the whole stream over one unknown type would tie every client to a protocol version.</p>
<p>A known type with wrong content throws. There is no second reading of that. <code>messageId</code> should be a string and you sent a number, which means the sender is already broken, and carrying on only buries the error deeper.</p>
<p>The project wrote that line into the spec changelog as a normative clause, in BCP 14 wording.</p>
<p><img alt="The two handlings, unknown events and malformed ones" loading="lazy" src="/images/agui/fig5.png"></p>
<h2 id="why-the-validation-is-off-by-default">Why the validation is off by default</h2>
<p>I went back and thought it over, and the default is not wrong.</p>
<p><code>run()</code> is for the case of &ldquo;I just want to see text quickly&rdquo;. Plug it in and it renders, no protocol details required. The moment you really need strictness is when you write the client yourself and take someone else&rsquo;s agent as the input source, because then dirty data turns straight into a garbled interface.</p>
<p>The project left you the switch, and marked its position clearly, but it will not press it for you.</p>
<h2 id="what-i-do-now">What I do now</h2>
<p>When wiring up AG-UI, I attach <code>enforceEvents</code> explicitly on the client side, even if it costs a few extra log lines.</p>
<p>The reason is simple: the agent backend can be swapped. LangChain, Mastra, Claude&rsquo;s hosted agents, any of them can plug in as long as what they emit is AG-UI events. Quality across those backends varies, and the front end is the only place that can apply one consistent gate. Events let through end up as strange interfaces the user sees.</p>
<p>One detail along the way: this SDK also implements a binary channel, HTTP plus Protobuf, frames with a 4 byte length prefix, generated from the same schema. SSE is enough for text, and it starts to matter at volume.</p>
<h2 id="onto-your-own-case">Onto your own case</h2>
<p>If your agent only talks to your own backend, with events written by your own team, the loose default path is enough, and when something breaks you can fix both sides together.</p>
<p>But the moment you plan to let someone else&rsquo;s agent plug in, or you want to keep this front end around for a third and fourth backend, that validation should be on. It is not a security measure. It moves the question of what the protocol allows out of the docs and into code.</p>
<p>Your agent front end today: does it parse the stream itself, or does it use this protocol? And if it uses it, is that enforce switch on?</p>
]]></content:encoded></item></channel></rss>