Building with AG-UI: Events, Shared State and Human Approval

Our introduction to AG-UI covered what the protocol is. This post covers how a frontend actually consumes it, and where teams get stuck. If you are new to the idea, start with What Is AG-UI?.

The event stream

An AG-UI run is a stream of typed events from the agent to the app. The main families are:

• Lifecycle: a run starts, may report steps, then finishes or errors.
• Text messages: a message starts, streams content in chunks, then ends.
• Tool calls: a call starts, its arguments stream in, then it ends, and a result is reported.
• State: a full snapshot of shared state, or small deltas applied on top.

sequenceDiagram
    participant UI as Frontend
    participant AG as Agent
    UI->>AG: Start run (messages, state)
    AG-->>UI: Run started
    AG-->>UI: Text chunks
    AG-->>UI: Tool call start and args
    AG-->>UI: State delta
    AG-->>UI: Run finished

The frontend keeps a small reducer: every event updates messages, tool-call status or state, and the UI renders from that state. Build it as a pure function of the event list and it becomes easy to test and replay.

Shared state without overwriting the user

State events let an agent and a user edit the same object, such as a plan or a form. Two habits prevent bugs:

1. Send a snapshot first, then deltas. Deltas are small patches, so the stream stays light.
2. Decide who wins on conflict. If the user edits a field while the agent is updating it, the app should keep the user’s value and tell the agent.

Human approval as a tool call

A clean way to add approval is to model it as a frontend tool. The agent calls something like confirm_action with the details. The UI renders a confirmation card and returns the user’s answer as the tool result. The agent resumes with that answer.

Rules worth following:

• Show exactly what will happen, with real values, not a vague summary.
• Make “reject” an equal choice and pass the reason back to the agent.
• Record who approved and when.
• Time out. A pending approval should not hold a run open forever.

Failure cases to plan for

• Dropped connection. Support reconnecting, and replay or re-snapshot state so the UI does not drift.
• Malformed tool arguments. They arrive in pieces. Parse only when the call ends, and show a placeholder meanwhile.
• Long runs. Show progress steps so the user can tell it is working, and offer cancel.
• Errors. Surface a readable message and keep partial results visible.

Production checklist

1. Reducer tested with recorded event streams.
2. Reconnect and state resync handled.
3. Approval flows for every risky tool.
4. Authentication on the agent endpoint, not just the page.
5. Sensitive data stripped from events before they reach the browser.
6. Trace IDs linking UI events to backend logs.

The takeaway

AG-UI is simple to start and unforgiving at the edges. Treat the event stream as the source of truth, build a testable reducer, and design approvals and reconnection from the first week.