What Makes Agent Frontends Hard: an Event Protocol and Your First Stream in the Browser

Today's Goals

1. Name the three things that make agent interfaces hard, with a concrete failure for each that costs you the user's trust
2. Read the AG-UI event groups and explain what the run, message, and tool layers each solve
3. Read an event stream with plain fetch and ReadableStream, and explain why EventSource does not work here

No interface work today. First the foundation: a protocol, and a decoder that turns bytes into events. When you finish, scroll back up and tick the three goals off.

Plain-Language Walkthrough

The simultaneous interpreter's booth: why speaking while listening is the hard part

Have you sat in a conference with simultaneous interpretation? The speaker talks, and from a soundproof booth the interpreter renders it almost at the same moment. What reaches your headset is a sentence taking shape in real time.

The difficulty is not vocabulary. It is that the interpreter has to start speaking while the information is still incomplete. The speaker says "this proposal, we have decided to", and the interpreter is already committed, without yet knowing whether the ending is "adopt" or "abandon". Hence the particular awkwardness of live interpretation: realizing mid-sentence that you went the wrong way and having to double back, listeners left holding half a clause, a sudden piece of jargon that stalls everything.

An agent interface is that booth. The model emits one word at a time, and your interface has to display a sentence before it exists in full. This is nothing like traditional frontend work, where you get a complete API response and render it once, deterministically. An agent frontend gets a stream with no promised ending. It might finish normally, it might error out halfway, it might stop to ask you a question, or it might still be running three minutes later.

So the position this course takes is: consuming a stream is easy; keeping the interface from falling apart once the stream arrives is the hard part. The next seven days are all about the second half of that sentence.

Three specific difficulties: uncertainty, long tasks, trust

Break "hard" apart and you get three concrete problems. Each has a signature failure, and each of those failures costs you the user's trust directly.

Uncertainty. You do not know how long the answer will be, whether it will call a tool, or whether it will fail. A traditional frontend can draw an accurate progress bar; you cannot, because you do not even know the total. The failure looks like this: a spinner turns for forty seconds, the user cannot tell whether the agent is thinking, calling a tool, or dead, and they reload the page and lose everything.

Long tasks. An agent running for several minutes is normal. A traditional frontend's request timeout sits around thirty seconds, and here the concept barely applies. The failure: the user switches to another tab to get on with work, comes back to find the stream died, and the interface shows half a sentence with no explanation and no way to recover.

Trust. Models are wrong and models invent things. If the interface presents nothing but a confidently written paragraph, the user has no way to judge it. The failure: the agent claims it deleted the files, and the user cannot see what it actually called, with what arguments, or what came back. All they can do is believe it or not.

Why a protocol: what AG-UI covers and what MCP covers

If the frontend is going to show what the agent is thinking, which tool it is calling, and how far along it is, the backend has to send all of that in a shape both sides agreed on beforehand. That agreement is a protocol.

Three protocols have appeared in the agent ecosystem over the last couple of years, each covering a different link:

Only the third one concerns us. AG-UI, the Agent-User Interaction Protocol, is an open protocol under the MIT license. What it does is unglamorous: it specifies the shape of every event the backend sends the frontend.

A decision worth explaining here. This course uses no agent frontend SDK at all; we write the client ourselves. But we do not invent the protocol — we align with AG-UI. The reasoning: invent a teaching protocol and all you learn is the one the instructor made up, whereas aligning with an open standard means the decoder you write and your grasp of the event layering transfer to any AG-UI backend. What you hand-write is a client for a real standard, not a reinvented wheel.

The event groups: six of them, one layer each

AG-UI groups events by responsibility. This course uses eighteen of them; today we meet three groups.

The run group marks the boundaries of one execution. RUN_STARTED opens with a threadId and a runId, RUN_FINISHED closes, and RUN_ERROR covers failure. This layer is what tells the interface whether anything is currently running, which in turn drives the stop button and the disabled input.

The text message group covers the generation of one reply, in three parts:

• TEXT_MESSAGE_START carries messageId and role, announcing "a message is about to begin"
• TEXT_MESSAGE_CONTENT carries messageId and delta, one small piece of text each
• TEXT_MESSAGE_END carries messageId, announcing the message is complete

Why three events instead of one complete message? Because streaming means displaying before the sentence exists. START lets the interface build the bubble first, CONTENT fills it in, and END tells the interface it can wrap up: apply syntax highlighting, begin screen reader announcement, reveal the copy button. Explicit start and end are what let the frontend distinguish "still talking" from "done" — a distinction that matters for rendering optimization on day two and for accessible announcement on day seven.

The tool group covers the lifecycle of a tool call (TOOL_CALL_START / TOOL_CALL_ARGS / TOOL_CALL_END / TOOL_CALL_RESULT), which is day three's subject. The reasoning, state, and subagent groups belong to days four and six.

data: {"choices":[{"delta":{"content":"Hi"}}]}
data: {"choices":[{"delta":{"content":" there"}}]}
data: [DONE]

(empty)

Three ways to read a stream: EventSource, WebSocket, or fetch

With the protocol settled, the question is how to get the stream into the browser. Three candidates.

EventSource is the browser's built-in SSE client, with automatic reconnection, and looks purpose-built for this. WebSocket is a full-duplex connection and sounds more capable. fetch with ReadableStream is manual transmission: you write everything yourself.

The answer is the third, and the first two are not merely worse — one is unusable and the other is overkill. The next section covers why the first one is out.

As for WebSocket: an agent interaction is "the user sends a request, the server streams back a series of events". That is request-response, not bidirectional realtime. Using a WebSocket means owning connection lifecycle, heartbeats, reconnection, and then layering request-response semantics on top of a persistent connection — a pile of state introduced for a fundamentally one-way scenario. Unless you genuinely need server-initiated push, such as multiplayer collaboration, it does not pay for itself.

Why fetch: EventSource's three hard limits

EventSource is genuinely pleasant to use:

// Looks lovely, and fails at step one in an agent scenario
const es = new EventSource('/api/agent')
es.onmessage = (e) => console.log(JSON.parse(e.data))

The trouble is three limits you cannot work around:

1. GET only. But you need to send an entire conversation history, tens to hundreds of kilobytes of JSON. Stuffing it into a query string blows past length limits and writes the user's conversation into server access logs.
2. No request body. The direct consequence of the above.
3. No custom headers. No Authorization, so you fall back to cookie auth, which gets painful across origins.

So: fetch. It can POST, carry a body, and set headers, at the cost of writing SSE parsing, reconnection, and error handling yourself. Day six adds reconnection; today we get parsing working.

// One POST, then read the response body as a stream of bytes
const res = await fetch('/api/agent', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ threadId, runId, messages }),
  signal, // day six uses this for stopping
})
 
if (!res.body) throw new Error('response has no readable body')
 
const reader = res.body.pipeThrough(new TextDecoderStream()).getReader()

res.body is a ReadableStream of raw bytes. TextDecoderStream turns bytes into strings — and do not substitute your own TextDecoder decoding chunk by chunk, because a multi-byte character can land across a chunk boundary and per-chunk decoding will produce garbage there. TextDecoderStream holds the partial character over to the next chunk.

Passthrough and forward compatibility: handling events you do not recognize

One last design question, and a frequent interview one: your decoder receives an event type the protocol does not define. What should it do?

Three options: throw, silently ignore, or pass it up.

AG-UI's own schema answers this — its base event is passthrough, meaning unknown fields are preserved rather than rejected. The reasoning is forward compatibility: the protocol is still evolving and new events land regularly. If your frontend dies on anything new, then every backend release breaks every client that has not caught up.

So the right behavior is: ignore unknown event types rather than throwing, but log them in development.

function handleEvent(event: AgentEvent, ui: UiState) {
  switch (event.type) {
    case 'TEXT_MESSAGE_START':
      return ui.beginMessage(event.messageId, event.role)
    case 'TEXT_MESSAGE_CONTENT':
      return ui.appendDelta(event.messageId, event.delta)
    case 'TEXT_MESSAGE_END':
      return ui.endMessage(event.messageId)
    case 'RUN_ERROR':
      return ui.fail(event.message, event.code)
    default:
      // The point: skip what you do not recognize, do not throw
      if (process.env.NODE_ENV !== 'production') {
        console.debug('[agent] unhandled event type', event.type)
      }
  }
}

Source Reading

Hands-On Lab

Three of the files you write today get copied verbatim into the next six days, so they are worth doing carefully: the event types, the decoder, and the offline script. Confirm you are on Node 22 or later, then run pnpm install --ignore-workspace. If you get stuck, every key function in solution/ carries a comment explaining why it is written that way.

1. Scaffold a Next.js app and write a route that emits events over SSE, verifying with curl first
2. Define the event types this course uses, plus a type guard that keeps unknown types out
3. Write the decoding iterator with fetch, ReadableStream, and TextDecoderStream, splitting on blank lines
4. Accumulate TEXT_MESSAGE_CONTENT deltas into one message and render it
5. Inject a RUN_ERROR and make the interface show an error state rather than hanging

Interview Questions

Three questions below, focused on choosing a streaming transport in the browser, the layering of an event protocol, and forward-compatible field handling. Open each one and read the analysis before the answer points — practicing the derivation beats memorizing bullets. The "common in China / common globally" tags let you filter by target market.

Checklist and Tomorrow

• Name the three things that make agent interfaces hard, with a concrete failure for each that costs you the user's trust
• Read the AG-UI event groups and explain what the run, message, and tool layers each solve
• Read an event stream with plain fetch and ReadableStream, and explain why EventSource does not work here
• Explain why decoding needs TextDecoderStream rather than per-chunk decoding
• All 5 lab acceptance criteria pass
• Answer at least 2 of the 3 interview questions without looking at the answer points

Tomorrow (D2) we put this minimal page under realistic load. When a model emits dozens to hundreds of deltas per second, today's approach of updating state on every delta sends React into a re-render frenzy, the page starts dropping frames, and even the input the user is typing into gets dragged down. Getting the protocol and decoder working first is deliberate: optimization has to start from a baseline you can measure, and without today's working version there is nothing to measure.