AG-UI (Agent-User Interaction Protocol)

AG-UI defines two roles: a producer that emits an event stream (an agent, proxy or bridge) and a consumer that reads it (a client SDK, UI or recorder). In the reference architecture the application owns the user, renders the stream, executes the tools it advertised and decides what needs consent; the client SDK sends the run input and runs a processing pipeline (compatibility translation, middleware, enforcement, verification); on the agent side a framework bridge translates native framework events into protocol events and an endpoint speaks a transport binding.

Each exchange is a run: one RunAgentInput (thread, run ID, messages, tools, state, resume answers) in, one ordered stream out. Streams use three patterns: open-content-close for streamed text and tool arguments, snapshot and JSON Patch delta for state and activity, and interrupt and resume for anything the run needs from outside. There is no mid-run channel from the consumer, so a waiting run ends and a new run continues it. Multi-agent systems appear through subagent events that attribute output to a subagent run; the protocol does not orchestrate agents itself.

State is not stored by the protocol: the agent sends state snapshots and deltas, the application keeps them, and they return with the next run input, alongside the message history. The JSON Schema is authoritative for structure and the 1.0 specification for behaviour; SDK types are generated from the schema. The official site names no foundation or steering body; the project grew out of CopilotKit, which runs the public working group and sells optional production support.

Human input is a first-class pattern. When a run needs an approval, credential or choice it ends with RUN_FINISHED carrying an interrupt outcome; each interrupt has an ID, a reason, a human-readable message, optionally the toolCallId the approval concerns and a responseSchema the application can turn into a form. The next run sends resume entries that answer each interrupt by ID. Frontend tools give a second path: the agent proposes a call, the application executes it (for example after asking the user), and the answer rides the next run's messages. The spec asks applications to get explicit consent before side-effectful tool calls and never to mark an action as user-approved when it was not, while noting that the protocol cannot enforce this on the wire.

pip install ag-ui-protocol

# Python SDK (AG-UI 1.0). Also: pip install fastapi uvicorn; run: uvicorn main:app
import uuid
from fastapi import FastAPI, Request
from fastapi.responses import StreamingResponse
from ag_ui.core import (RunAgentInput, RunStartedEvent, RunFinishedEvent,
    TextMessageStartEvent, TextMessageContentEvent, TextMessageEndEvent)
from ag_ui.encoder import EventEncoder

app = FastAPI()
@app.post("/")
async def run(inp: RunAgentInput, request: Request):
    enc, mid = EventEncoder(accept=request.headers.get("accept")), str(uuid.uuid4())
    last = inp.messages[-1].content if inp.messages else ""
    events = [RunStartedEvent(thread_id=inp.thread_id, run_id=inp.run_id),
        TextMessageStartEvent(message_id=mid, role="assistant"),
        TextMessageContentEvent(message_id=mid, delta=f"You said: {last}"),
        TextMessageEndEvent(message_id=mid),
        RunFinishedEvent(thread_id=inp.thread_id, run_id=inp.run_id)]
    return StreamingResponse((enc.encode(e) for e in events), media_type=enc.get_content_type())

• The example uses the Python SDK, which is producer-side; frontends normally use the TypeScript client (@ag-ui/client). The server quickstart lists Python 3.12 or later.
• In SDK 1.0, single-value fields such as an event's type default automatically, absent fields are omitted rather than sent as null (from ag-ui-protocol 0.1.20), and JSON Patch entries parse to typed objects (patch.path, not patch["path"]).
• 1.0 retires the THINKING_* events in favour of REASONING_* and renames content parts (TextInputContent to TextPart and so on); the TypeScript client translates old streams, but the shims are set to expire about twelve months after they were written.
• Every run must open with RUN_STARTED and close with RUN_FINISHED or RUN_ERROR; a run that is waiting for input must end with an interrupt outcome, not success.
• Authentication is not part of the protocol; secure the HTTP endpoint yourself.

The specification is at 1.0, the first release with normative behavioural rules; the 1.0.0 TypeScript packages were published in the release/2026-09-17 monorepo release. SDK packages ship in dated monorepo releases with tags of the form release/YYYY-MM-DD.

The AG-UI docs describe the three as complementary: MCP connects agents to tools, A2A connects agents to agents, and AG-UI connects agents to users. AG-UI's repository ships middleware that fronts MCP servers and an experimental A2A bridge.

The project originated at CopilotKit, which runs its public working group and offers optional paid production support. The official site does not name a foundation or steering committee.

Yes. The protocol and SDKs are MIT-licensed. The only paid offering on the official site is optional engineering support from CopilotKit.

No. The docs describe A2UI as a generative UI specification for UI widgets an agent sends, while AG-UI is the event protocol that can carry such content between agent and application.