AG-UI 1.0 Audited: 31 Event Types, 68 Conformance Streams — and Two First-Party SDKs the Corpus Never Reaches

AG-UI 1.0 ships a 94,359-byte schema and 68 conformance streams. Its published TypeScript client passes all 68; the .NET client diverges on 38.

Most “open protocols” for AI agents are a README, a logo, and a TypeScript package that happens to talk to its own server. AG-UI is not that. It ships a 94,359-byte JSON Schema as the normative contract, 219 fixture documents, 68 recorded event streams with machine-readable expectations, and a harness that asserts the corpus cannot quietly shrink.

That makes it auditable in a way almost nothing else in this space is. So I audited it: cloned the repo at main, installed the published packages from npm and PyPI rather than the monorepo source, and ran the protocol’s own conformance corpus through a replay harness I wrote against the shipped client. Then I checked the parts the corpus says it does not cover.

The result is not a takedown. The TypeScript client passed all 68 streams. The interesting findings are at the edges the project documents in its own files — and one of them is a MUST violation in a SDK the spec calls first-party.

What AG-UI 1.0 actually ships

ItemValue
Repositoryag-ui-protocol/ag-ui, MIT, created 2025-05-07
Stars / watchers / forks18,970 / 102 (0.54%) / 1,964 (10.4%)
Open issues591
Event types in the 1.0 schema31, in eight families
Schema94,359 bytes, 98 definitions, $id = https://ag-ui.com/spec/1.0/schema.json
Conformance streams (1.0 / draft)68 / 71
Fixture documents219 — 135 valid, 84 invalid
Harness code3,314 lines under spec/harness/
Published packages@ag-ui/core 1.0.4 (2026-11-05), ag-ui-protocol 1.0.0 (2026-09-17 18:31 UTC)
First-party SDKs the spec claims3 — TypeScript, Python, .NET
Lanes the corpus actually runs2 — TypeScript and .NET

The schema is not decorative. https://ag-ui.com/spec/1.0/schema.json returns 200 with a sha256 prefix of 4b5c93226838a0e7 and 94,359 bytes — byte-identical to spec/1.0/schema.json in the repo. Its own description states the design position plainly:

Objects are exact: this file defines what exists in this version of the protocol, so a property it does not declare fails validation.

And the prose spec is explicit about which document wins where:

The schema is authoritative for structure. […] This document is authoritative for behaviour. Ordering, lifecycle, attribution, error handling, compatibility. The schema cannot express any of it. If an implementation disagrees with a rule here, the implementation has a bug.

A protocol that writes that sentence invites exactly the test I ran.

Test one: the published client, replayed through its own corpus

The repo’s TypeScript lane serves each fixture’s recorded stream over real HTTP as SSE frames into an HttpAgent, then asserts the expectation block. I rebuilt that loop in plain Node against @ag-ui/client@1.0.4 from npm — not the workspace source — with a 40-line http.createServer standing in for the project’s mock server:

const server = http.createServer((req, res) => {
  let raw = "";
  req.on("data", (c) => (raw += c));
  req.on("end", () => {
    requestBody = JSON.parse(raw);
    res.writeHead(200, { "content-type": "text/event-stream" });
    for (const ev of fixture.stream) res.write(`data: ${JSON.stringify(ev)}\n\n`);
    res.end();
  });
});
// pinned peers install the era shims; that is what fixture.client.maxProtocolVersion is for
class FixtureAgent extends HttpAgent {
  get maxProtocolVersion() { return pinned ?? super.maxProtocolVersion; }
}

Then the expectations are asserted exactly as the fixture states them: outcome, eventTypes in order, eventPaths, eventAbsentPaths, warnings, messageCount, subset-matched messages/state/request, and absence paths.

Result: 68 of 68 pass. Not “mostly” — every fixture, including the ones that require the client to reject a stream (first-tool-chunk-missing-name-fatal, run-finished-with-active-subagent-fatal), the ones that require it to stay quiet on a conformant run (conformant-run-is-quiet), and the compatibility fixtures that pin the 0.0.39 and 0.0.57 downgrade paths.

Two details worth knowing for anyone integrating:

  • The client stamps protocolVersion: "1.0" into RunAgentInput on every run. I captured the outgoing body: {"threadId":"…","runId":"…","protocolVersion":"1.0","state":{},"messages":[],"tools":[],"context":[],"forwardedProps":{}}. The versioning page requires that declaration, so this is one rule that is enforced in practice.
  • @ag-ui/core@1.0.4 exports 12 runtime symbols and has zero dependencies. It is types, an EventType enum, PROTOCOL_VERSION, and a few helpers — there is no validator in it. Validation lives in @ag-ui/client (zod). If you install “the core” expecting to validate a document against the protocol, you get nothing; the conformance behaviour is in the client package.

That is the state of the reference implementation on the day of writing, and it is better than most. The rest of this article is about what the corpus cannot see.

The corpus has no Python lane, and says so

spec/1.0/conformance/README.md opens by describing what the suite is:

It is a regression suite for the first-party clients, and it asserts two different kinds of thing.

A few sections later, under “What does not belong here”:

Python. There is no Python client to hold to this.

So the honest position inside the repo is that the corpus covers two clients. The public position is different. The published spec says:

AG-UI is maintained with three first-party SDKs — TypeScript, Python and .NET — and every rule here applies to all of them equally.

Both sentences are true in their own terms — Python gets no client lane because there is no Python client to test — but they cannot both be the whole story, because a Python agent backend is the single most common way this protocol gets used. pip install ag-ui-protocol is the documented server path. If the Python side is exempt from behavioural conformance by construction, “every rule applies to all of them equally” is a statement about ambition, not about verification.

So I tested the thing the corpus does not: whether the Python SDK’s models agree with the schema on the 219 documents the schema ships.

Twenty-two documents the schema rejects, and what Python does with them

Method: for each of the 42 fixture definitions, load fixtures/<Def>/{valid,invalid}/*.json, validate against that definition’s anchor in schema.json with a stock JSON Schema validator to establish the baseline, then feed the same document into the corresponding pydantic model from ag-ui-protocol==1.0.0.

Baseline first: all 135 valid documents validate, all 84 invalid documents are rejected. The corpus is self-consistent — the schema says what its fixtures say it says.

Then the SDK:

OutcomeDocumentsShare
Rejected at parse (agrees with the schema)6274%
Accepted, then normalised into a valid document1417%
Accepted and re-emitted still invalid810%
Spec-rejected documents the SDK accepts2226%

Zero false rejections: every document the schema accepts, Python accepts. The gap is all in one direction — Python is more permissive than the contract, in four recurring shapes:

  1. A described field carrying null. metadata: null on TEXT_MESSAGE_CONTENT, rawEvent: null on TEXT_MESSAGE_END, code: null on SUBAGENT_ERROR, parentMessageId: null on TOOL_CALL_START. The schema declares these as strings/objects; a present-but-null value fails it. Pydantic reads str | None = None and drops the key on the way back out.
  2. A missing required discriminator. REASONING_MESSAGE_START without role is rejected by the schema and accepted by the SDK, which fills the Literal default.
  3. A union member carrying a key from a different member. {"type":"interrupt","interrupts":[…],"pendingToolCallIds":[…]} on RUN_FINISHED. The schema’s per-member objects are closed; extra="allow" keeps the stray key and puts it back on the wire.
  4. Unknown properties. {"type":"TEXT_MESSAGE_END","messageId":"msg_1","somethingNewer":true} round-trips unchanged, as does the retired subAgents key and a FileSource.reference field the schema does not define.

Shape 3 and 4 are the ones that leave the process. Feed an invalid document in, dump the model, validate again — eight documents come back out still invalid:

RunFinishedEvent/outcome-interrupt-carrying-pending-tool-call-ids.json
RunFinishedEvent/outcome-cancelled-carrying-interrupts.json
SubagentFinishedEvent/outcome-success-carrying-interrupt-ids.json
TextMessageEndEvent/unknown-property.json
MultiAgentCapabilities/old-subagents-key.json
FileSource/reference-record.json
…

The MUST this breaks, in the spec’s own words

The processing model page is unusually direct for a protocol document:

Unrecognised material is not an error. A malformed known value is.

  • A property that is not described on an event MUST NOT abort the run.
  • A field the protocol DOES describe, carrying a value the schema rejects, MUST be fatal: the consumer MUST fail the run rather than repair, coerce or ignore the value.

Shapes 1 and 2 are squarely the second rule — metadata: null is a described field holding a value the schema rejects, and pydantic’s job is to coerce and ignore. The Python SDK’s own generated base model admits as much:

Coercion is pydantic’s default: the strict contract is the specification’s validation corpus, not this class.

That sentence is honest and, read against the MUST above, it is also a confession. It is generated from spec/generator/python.ts, so it is a protocol-level choice rather than a bug someone forgot to fix: the models are deliberately a permissive parsing surface, and the conformance corpus is declared the strict one. In TypeScript the division works — the client enforces, the corpus proves it. In Python the corpus is not wired to the SDK at all, so the strict half exists as JSON files nobody runs against the package that ships to PyPI.

Meanwhile unknown material does survive in Python, with no warning at all — I grepped the installed package for any warning mechanism and found none outside capabilities.py. That is the other half of an internal inconsistency in the spec’s prose:

  • spec/1.0/schema.json’s own README: an SDK boundary tolerates fields it does not recognise — stripping them with a warning rather than rejecting the stream.
  • The processing model page: unrecognised material survives.

Strip-with-warning and survive-silently are different behaviours. The TypeScript client does the first (verified: unknown-property-stripped and open-metadata-preserved both pass). The Python models do the second. Both can cite a sentence from the specification.

Test two: the .NET lane exists, but not on the same rules

.NET is the third first-party SDK, and it is the only second lane in the corpus. It does not pass the corpus the way TypeScript does. It passes its own version of it.

38 of the 68 fixtures — 56% — carry an expectOverrides.dotnet block that replaces the assertion for that lane. The overridden keys, counted:

Overridden expectationFixtures
messages19
messageCount15
errorContains11
outcome10
warnings9
eventTypes9
noWarnings8
eventPaths5
request4
eventAbsentPaths2
eventTypesAbsent1
requestAbsentPaths1

The override format requires a written reason, and the reasons are the most useful documentation in the repo. Many are legitimate platform differences — .NET assembles history through Microsoft.Extensions.AI, keeps no state store, and has no activity reducer. But nine of them are not differences at all. They are labelled, in the project’s own words:

GAP, not a design difference: EventStreamConverter has no case for TEXT_MESSAGE_CHUNK or TOOL_CALL_CHUNK, so a chunk stream falls through to the pass-through branch. Nothing is expanded into a message and none of the chunk-stream rules are enforced. Pinned here so the gap cannot widen or close unnoticed; alignment tracked separately.

Nine fixtures — the entire chunk-stream family — assert the opposite of the rule in the .NET lane, because the .NET converter never implemented chunk expansion. The consequences are spelled out per fixture: first-chunk-missing-id-fatal says “the stream is accepted instead of rejected”; chunk-expansion-assembles says “the two chunks assemble into nothing at all”.

There is a second, structural version of the same problem in the generator. spec/generator/dotnet-models.ts writes C# classes from the schema, but the list of classes is hand-maintained, and the file says what that costs:

the class list below is written by hand, so a definition the schema gains and nobody adds to it is simply absent from .NET — while TypeScript and Python emit it, and the drift gate, which compares the generator only against its own output, stays green.

The guard against that is a hardcoded NOT_IN_DOTNET set with seven entries, all JSON Patch operations, each with a reason. So the drift is caught only where someone remembered to enumerate it, and the gate that is supposed to catch the rest compares the generator to its own output rather than to the schema.

Three documents, two answers on who maintains .NET

This is the part that matters more than any engineering detail, because it determines what you can expect to be fixed.

DocumentWhat it says about .NET
spec/1.0/… (published spec)One of “three first-party SDKs”, where “every rule here applies to all of them equally”
docs/introduction.mdx SDK tableStatus: Supported. Integrations: Community
CONTRIBUTING.md“All community integrations (ie, .NET, Golang SDK, etc.) will need to be maintained by the community member who made the contribution.”
Directory layoutsdks/dotnet — not sdks/community/dotnet
Conformance corpusA lane of its own, described as being for “the first-party clients”

The same package is first-party when the spec needs to claim uniformity and community when someone asks who fixes it. That is not a conspiracy — it is what happens when a project grows a formal specification faster than its governance catches up — but for an adopter it has a concrete consequence: the SDK with 56% of its assertions overridden is the one with no stated maintainer obligation. If you build on .NET, you are the maintainer of your conformance.

The claim I expected to break, and didn’t

spec/RECONCILIATION.md opens with a number that reads like a typo:

0 fields where TypeScript and Python disagree with the schema about required-ness.

I tried to falsify it. Comparing each definition’s required array in the schema against pydantic’s is_required() across 75 definitions gives 53 disagreements — which looks like a clean hit until you read the document’s own caveat: a fixed discriminator written Literal[X] = X always serialises, so calling it optional “would be the same false claim”. Apply that rule and 51 of the 53 evaporate; the two that remain are on RunAgentInput, which the document names itself (tools and context read optional because the schema gives them defaults).

Recomputed with the stated method: 0. The number holds. A project that publishes a reconciliation table and is right about it deserves the credit, and it is the reason I trusted the rest of its self-reported gaps.

What actually moved between 1.0 and the draft

The schema is described as “stable, frozen” at 1.0, with a draft running ahead of it. Diffing spec/1.0/schema.json against the served spec/draft/schema.json:

  • 98 definitions in both; no definition added or removed.
  • 6 definitions changed, and every change is one added optional property.
  • New: encryptedValueType on BaseMessage, ReasoningMessage, ToolCall, ToolMessage, ReasoningEncryptedValueEvent; and error on ToolCallResultEvent.
  • Event union: 31 in both.

That is a genuinely conservative evolution rate for a two-month window, and it is the strongest argument in the protocol’s favour: the surface you integrate against today is not being rewritten under you. The corpus grew from 68 streams to 71 in the same period.

Repository health, honestly

18,970 stars with 102 watchers is a 0.54% watch rate — people bookmark this, they do not track it. The 2025-05-13 “Show HN” post that launched it scored 36 points and 5 comments. Forks are 10.4% of stars, which is normal for something people integrate rather than vendor.

Commit concentration is the other signal. GitHub reports 182 contributors; among the top 100, ranst91 accounts for 1,282 of 5,077 commits (25.3%), with contextablemark at 735 and mme at 724. ranst91 is Atai Barkai, CopilotKit’s CEO, and mme is the Python SDK’s author. The protocol is MIT and lives in its own GitHub org, but its centre of gravity is one company — whose product is also the recommended production client. That is not a criticism; it is the same structure as React and Meta, and it is the thing to price in when you decide how much of your architecture to hang on it.

What the protocol gets right, and worth copying

Three things here are better than the norm and cost nothing to imitate:

  1. The schema answers at its own $id. https://ag-ui.com/spec/1.0/schema.json serves the exact bytes the repo commits, so a validator can be pointed at the spec rather than at a copy that drifts.
  2. The corpus is pinned twice. streams/MANIFEST.txt asserts the directory listing in both directions, and every fixture must state a kill: “the single-line change to the implementation that must make this fail.” A fixture that cannot fail is worse than no fixture, and this is the only suite I have read that says so in the format itself.
  3. Deprecations have expiry dates and a registry. DEPRECATIONS.md records each retired shape, its replacement, the shim that handles it, and a date twelve months out. I checked the release claim: npm published 1.0.0 on 2026-09-17 at 18:27:36 UTC and PyPI at 18:31:18 — four minutes apart, which is what “shipped together” should look like.

FAQ

Is AG-UI a real protocol or a vendor wrapper? Real, in the sense that matters: a normative JSON Schema served at its $id, 68 recorded streams with written expectations, and a client that passes them. It is also a CopilotKit-centred project — the spec’s own scope section, the recommended production client, and 25% of the top-100 commits all point that way. Both facts are true and neither cancels the other.

Does the TypeScript client actually conform? In my replay of all 68 fixtures against @ag-ui/client@1.0.4 from npm, yes — every assertion, including the strips, the warnings, and the fatal cases. I did not build or run the .NET lane (no dotnet in this environment), so its 38 overrides are read from the fixtures rather than observed.

Why does Python accept 22 documents the schema rejects? Because the generated pydantic base model reads extra="allow" and trusts pydantic’s coercion — deliberately, and stated in the generated docstring. The strict contract is the JSON corpus, which is not run against the Python package. If you need producer-side strictness in Python, validate with the schema before encoding.

Does pip install ag-ui-protocol give me a client? No. The 1.0.0 package contains core, encoder and _generated — event models, an encoder, and types. There is no agent runtime and no client, and the conformance README states plainly that there is no Python client to hold to the corpus. The 30-line agent in the README is FastAPI plus this encoder.

Where do I pin versions? @ag-ui/client and @ag-ui/core at 1.0.4, ag-ui-protocol at 1.0.0, and treat 1.0.1–1.0.4 as patch releases of the protocol — the client’s maxProtocolVersion returns 1.0.4 while the wire declaration is 1.0. Consume protocolVersion from the stream and do not infer capabilities from the patch number.

Should I adopt it? If you are building an agent UI and were going to invent an event stream, use this one: 31 event types, a schema you can validate against, and a real reference client. If you are building a Python-only backend that talks to a JS frontend, use it and keep the schema in your test suite, because nothing else in the stack will catch a non-conforming event before your users do.

What to verify yourself before adopting

  1. Validate your own producers against the schema, in CI, not against the SDK. jsonschema or zod, the 94,359-byte file, and a job that fails on rejection. The Python models will not do this for you.
  2. Run the corpus against whatever client you ship. The fixtures are plain JSON with declarative expectations; a replay harness is 100 lines, as above. The repo says nothing does this for third-party clients yet.
  3. If you ship .NET, read the 38 overrides first. They are your specification of what that client does not do — chunk expansion above all.
  4. Pin a protocolVersion and assert what you receive. The client sends 1.0; make your agent check it rather than assume it.
  5. Treat tool calls as untrusted twice. The spec says the protocol “cannot enforce” consent, validation, or rendering isolation, and it is right — those are your obligations, and they are the ones that decide whether a prompt injection becomes an action.
  6. Read RECONCILIATION.md before writing your own compatibility layer. It is the only place that admits where the SDKs and the schema drift, and it is accurate.

Bottom line

AG-UI 1.0 is the most verifiable agent protocol shipped so far, and its verifiability is not marketing: the schema is byte-identical to what the repo commits, the published TypeScript client passes all 68 of the project’s own streams, and the reconciliation table survives an attempted falsification.

The gaps are equally specific. The corpus tests two clients out of the three the spec calls first-party, and no verifier in this space can see a Python producer’s stream before it leaves the process. The .NET client diverges on 56% of the corpus, nine of those by the project’s own admission of a missing feature, and three different documents disagree about whether that client is first-party. If you are choosing an event protocol this year, this is the one to choose — with the schema in your test suite, and with a clear-eyed answer to the question of who maintains the SDK you are not using.

Related reading: the MCP TypeScript SDK audit for the same measure-the-package approach on a different protocol, the A2A protocol overview for how the agent-to-agent layer compares, and CopilotKit’s frontend agent stack — the vendor behind AG-UI — for what sits above this layer.