AG-UI Turns "Waiting for Your Approval" Into a Real Agent State
An open protocol for the wire between an agent and the screen, where "waiting for your approval" is a real state instead of a guess.
Ask an agent to do something that takes two minutes and watch what most interfaces do. A spinner. Maybe some streamed text. Then either an answer or a vague error, and no way to tell which tool it was calling, whether it got stuck, or whether it was waiting for you the whole time.
That is not a model problem. It is a plumbing problem. The agent knows exactly what it is doing at every moment. The screen has no shared language to hear it.
AG-UI, the Agent-User Interaction Protocol, is an attempt to give it one. It is an open, event-based protocol for the connection between an agent's backend and the app a person is looking at. It was on Trendshift's daily board Sunday morning, sits at roughly 17,500 GitHub stars (from the repo page, so treat it as approximate), and published @ag-ui/langgraph 0.0.46 on November 13, the day after a larger batch of Python and TypeScript packages.
The interesting part is not that it streams. Lots of things stream. It is that the protocol forces every run into a shape with a beginning, an end, and a defined way to stop and ask a human. Once "the agent is waiting for you" is an event with a name, your frontend can stop guessing. The shift in one line: in AG-UI, pausing for a human is a result the run ends with, not a hang the screen has to paper over.
Where AG-UI sits
If you have been following agent protocols, the README's own framing is the quickest map. MCP gives agents tools. A2A lets agents talk to other agents. AG-UI brings agents into user-facing applications. MCP, the Model Context Protocol, is the common way agents call outside tools; A2A, short for Agent2Agent, covers agents handing work to each other. Three wires, three jobs.
AG-UI grew out of CopilotKit, a company that builds in-app copilots, and its README says it was "born from CopilotKit's initial partnership with LangChain and CrewAI." The integration list has grown well past that. LangGraph (LangChain's framework for agents built as step-by-step graphs) and CrewAI are partner integrations, and agent frameworks from Microsoft, Google, AWS and several open-source projects are listed as supported, each with docs and a demo. README integrations
It does not care how the bytes travel. The README says it works with "any event transport (SSE, WebSockets, webhooks, etc.)" and ships a reference HTTP implementation. (SSE, server-sent events, is the simple one-way stream a browser can open to a server.)
How it works, in plain terms
Think of an agent run as a parcel delivery with tracking. You do not get one message at the end saying "delivered." You get "picked up," "in transit," "out for delivery," and, sometimes, "waiting for your signature." AG-UI is that tracking feed for an agent.
Every message on the feed is an event with a type, plus optional extras like a timestamp and metadata (token usage or a trace id, for example). The docs group events by job: lifecycle, text messages, tool calls, state syncing, activity progress, subagents, and a few special ones. AG-UI events docs The README counts about 16 standard types.
Three groups do most of the work.
Lifecycle events are the bookends. A run starts with RunStarted, which carries a threadId (the conversation) and a runId (this attempt). It ends with either RunFinished or RunError. The docs call those boundaries mandatory. In between, optional StepStarted and StepFinished pairs mark phases, and a step name can simply be the name of the graph node or function that is running. Lifecycle events
That one rule fixes a whole class of frontend bugs. A loading state that knows it will always receive an end event, success or failure, never has to time out and hope.
Text arrives in pieces. A message opens with TextMessageStart, streams as a series of TextMessageContent events each carrying a delta (a chunk of text), and closes with TextMessageEnd. A shared messageId ties the pieces together, so the frontend just appends chunks in order.
Tool calls and state get their own events. Tool-call events let the screen show which tool the agent picked and what came back, instead of a silent pause. State events keep a shared piece of data, say a draft itinerary or a form, in sync between the agent and the UI. Subagent events tag output with a subagentRunId, so a parent agent and its helpers do not blur into one stream.
The part worth stealing: pausing is a result, not a hang
Here is the design choice that makes AG-UI more than a streaming format.
When an agent needs a human, say to approve a refund or choose between two drafts, the run does not sit there holding a connection open. It finishes. The docs describe RunFinished with an outcome field: success for a normal finish, or interrupt with a list of open interrupts (each one a question the agent needs a person to answer) when "the run paused for human input." (The field is optional so older agent backends still work; a missing outcome counts as a normal finish.) To continue, the client "resumes by starting a new run" whose input includes a resume array "addressing every open interrupt." RunFinished outcome
Read that slowly, because it changes how you build approval flows. "Waiting for approval" stops being a spinner the frontend invents. It becomes a recorded end state with a list of exactly what is pending, and the next run has to answer each item. Nothing has to stay half-alive in memory. If your backend saves thread history and the open interrupts, which is your job and not the protocol's, a user who closes the tab and comes back tomorrow finds the question still waiting.
The same thinking shows up elsewhere. RunStarted can carry a parentRunId, a pointer to an earlier run in the same thread, which the docs describe as a "git-like append-only log," meaning runs are only ever added, never rewritten. Runs pile up in order. You can branch from an old one. That is the shape you want if you ever plan to replay, audit or debug an agent session.
Put this into practice
The lowest-friction way in is the starter app from the README:
npx create-ag-ui-app my-agent-app
It scaffolds a project wired to an AG-UI backend. Note that an unversioned npx command fetches whatever the latest scaffolder is that day, so two people running it a week apart may get different starting points. Before writing anything, open the AG-UI Dojo, a gallery of small demos per framework (shared state, tool-based generative UI and so on). Pick the framework you already use and watch one feature work end to end. Ten minutes there saves an afternoon of reading.
Then try three things, in this order.
1. Log the raw events. Before you build any UI, print every event your agent emits to the console. You should see RunStarted first and RunFinished or RunError last on every run. If a run ever ends without one of those, you have found a bug in your integration before a user did.
2. Build one approval flow on interrupts. Pick the single most dangerous action your agent takes, like sending an email or spending money. Make that tool raise an interrupt. Render the interrupt list as a plain approve-or-reject card, and resume with a new run that answers it. This is the feature that justifies adopting the protocol at all.
3. Pin every @ag-ui package to an exact version. In package.json, drop the ^ in front of each @ag-ui version so you get exactly the versions you tested, and use == pins in Python requirements files. The next section explains why this is not optional.
What to expect: the starter and Dojo get you a streaming chat in minutes. A real interrupt flow wired to your own agent is more like a day, mostly spent deciding what the approval card should show.
Honest limitations
It moves fast, and it breaks things on purpose. The release log is a near-daily stream of package batches, and the breaking changes are labeled honestly. On November 12, the Python ag-ui-claude-sdk 0.2.4 stopped sending threadId and runId on text-message and tool-call events, which "the AG-UI 1.0 schema rejects," so consumers must read them from RUN_STARTED instead. On November 13, @ag-ui/langgraph 0.0.46 started requiring @ag-ui/client 1.0 or later. Releases Unpinned dependencies will bite you.
Many integrations are still 0.0.x. The core client has reached 1.0, but several framework adapters carry versions like 0.0.46 and 0.0.9. Treat those as early.
A busy issue tracker. At the time of writing the repo showed hundreds of open issues and pull requests. That signals a lot of use and a lot of unfinished edges at once.
Small paperwork mismatch. The README's license badge points at the copilotkit/copilotkit repo, not this one. The actual LICENSE file here is MIT. Read the file, not the badge.
A protocol does not make the agent honest. AG-UI tells the screen what the agent says it is doing. If the agent skips a step event or mislabels a tool, the screen will faithfully display the wrong thing. You still need tests on the backend.
You may not need it yet. If your agent is a single backend call that returns one answer in a few seconds, a plain request and response is fine, and a protocol is extra weight. AG-UI starts paying for itself when runs are long, call several tools, involve subagents, or need a person to approve something halfway through. That is a growing share of agent work, but it is not all of it.
Vendor gravity. The project grew out of CopilotKit and many docs links point at CopilotKit's site. The protocol is open and MIT-licensed, but expect the most polished paths to run through their tooling.
The wire matters more than the widget
Most agent frontends today are a chat box bolted onto a black box. AG-UI's bet is that the fix is not a prettier chat box. It is a contract: every run opens, every run closes, and a pause for a human is a written-down result the next run must answer.
You do not have to adopt the whole thing to use the idea. Even if you never install a package, make your own agent emit a start, an end, and an explicit "waiting on you" state. Your users will stop staring at spinners. And if you do install it, pin your versions first, then go build the approval card.
Sources: ag-ui-protocol/ag-ui README (main branch, read November 15, 2026) · AG-UI events documentation · AG-UI releases, 2026-11-12 and 2026-11-13 · LICENSE · AG-UI Dojo. Star count from the repo page, approximate, November 15, 2026.