ai, agents, deep dive,

Deep Dive: How AG-UI Turns Every Agent into One Typed Event Stream

Cui Cui Follow Nov 17, 2026 · 5 mins read
Deep Dive: How AG-UI Turns Every Agent into One Typed Event Stream
Share this

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

Animated workflow: the app packs a RunAgentInput, posts it to any agent endpoint, the agent emits typed events through an encoder, the client pipeline enforces and verifies them, and subscriber callbacks update messages and state

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.

Join Newsletter
Get the latest news right in your inbox. We never spam!
Cui
Written by Cui Follow
Hi, I am Z, the coder for cuizhanming.com!

Click to load Disqus comments