Companion to the hands-on tutorial: Stream any agent into your app with the AG-UI protocol on Cui.Guru. The tutorial shows how to use it. This post explains why it is built this way.
ag-ui-protocol/ag-ui (about 19k stars per the GitHub API on 2026-11-17, MIT, core, client, encoder and proto at version 1.0.4) describes itself as “an open, lightweight, event-based protocol that standardizes how AI agents connect to user-facing applications”. I read the TypeScript SDK in sdks/typescript/packages/ from a fresh clone. The interesting part is not the transport; it is how much discipline the client puts between the wire and your UI.
The workflow in motion
Architecture
The SDK is split into core (event types and schemas, generated from the JSON Schema in spec/1.0), encoder (SSE or Protobuf framing), client (the HttpAgent, the event pipeline and the subscriber API), plus proto and a CLI. Integrations and middlewares live outside the SDK in integrations/ and middlewares/.
The core design idea
One request shape, one event vocabulary, any producer. The generated EventType enum in core/src/generated/types.ts lists every event the protocol knows: text messages, tool calls, state, activity, reasoning, run and step lifecycle, subagents, plus RAW and CUSTOM as escape hatches. Because everything a client needs arrives as one of these events, the client does not care which framework produced them.
// core/src/generated/types.ts
export enum EventType {
TEXT_MESSAGE_START = "TEXT_MESSAGE_START",
TEXT_MESSAGE_CONTENT = "TEXT_MESSAGE_CONTENT",
TEXT_MESSAGE_END = "TEXT_MESSAGE_END",
TOOL_CALL_START = "TOOL_CALL_START",
// ...
STATE_SNAPSHOT = "STATE_SNAPSHOT",
STATE_DELTA = "STATE_DELTA",
// ...
}
The second half of the idea is that the client is strict. AbstractAgent.runAgent builds a pipeline in client/src/agent/agent.ts. The source comments explain the ordering: enforcement runs before chunk expansion so a malformed chunk is as fatal as a malformed plain event, and verification runs after expansion because start/content/end pairing only exists once a chunk has been expanded.
// client/src/agent/agent.ts
enforceEvents(this.debugLogger, { maxEntries: this.maxEnforcedEntries }),
transformChunks(this.debugLogger),
verifyEvents(this.debugLogger),
verifyEvents in client/src/verify/verify.ts tracks open text messages, tool calls and reasoning spans in sets, and keeps per-kind owner maps for subagent attribution, so a continuation event for an entity nobody opened is caught instead of silently rendered. client/src/enforce/limits.ts adds a default budget of 1,000,000 enforced entries per event or outgoing input, to stop a payload large enough to tie up the process.
Source excerpts
The request. HttpAgent.requestInit in client/src/agent/http.ts posts JSON and asks for an event stream. Before sending, sanitizeOutgoingInput removes a null subagentRunId, because the source comment says a null tag on the wire is schema-invalid and kills the run on the receiving side.
// client/src/agent/http.ts
method: "POST",
headers: {
...this.headers,
"Content-Type": "application/json",
Accept: "text/event-stream",
},
body: JSON.stringify(sanitizeOutgoingInput(input)),
The framing. The server-side EventEncoder in encoder/src/encoder.ts frames each event as an SSE data: line with encode(); only encodeBinary() switches to Protobuf, and only when the Accept header asks for it.
// encoder/src/encoder.ts
encodeSSE(event: BaseEvent): string {
return `data: ${JSON.stringify(omitOptionalNulls(event, "Event"))}\n\n`;
}
The state patch. For STATE_DELTA, client/src/apply/default.ts applies JSON Patch operations with fast-json-patch. The comment notes that the library inserts patch values by reference, so the patch is cloned first; a failed patch logs a warning instead of crashing the stream.
// client/src/apply/default.ts
const result = jsonpatch.applyPatch(state, structuredClone_(delta), true, false);
state = result.newDocument;
applyMutation({ state });
Takeaways
- A protocol that is “only the run lifecycle is required” keeps adoption cheap; richer features are additive event families.
- Generating SDKs from one JSON Schema keeps TypeScript, Python and .NET aligned.
- Strict enforcement and verification on the client turns a loose stream into something a UI can trust.
- Copy semantics (cloned state, cloned patches) are a deliberate defence against shared-object bugs.
Want an agent UI wired to your own framework? Get in touch.
Click to load Disqus comments