# AG-UI (Agent-User Interaction Protocol): features, protocols, quickstart

## TL;DR

AG-UI is an open, MIT-licensed protocol for connecting an agent backend to a user-facing application: the app sends one run request and receives an ordered stream of typed events for text, tool calls, state and progress. It originated at CopilotKit, reached a normative 1.0 specification in September 2026, and suits teams building agent UIs.

## Key facts

| Field | Value |
| --- | --- |
| Type | Protocol |
| Languages / SDKs | TypeScript, Python, C#, Kotlin, Go, Java, Rust, Ruby, Dart, C++ |
| License | MIT |
| Pricing model | Open source, free |
| Orchestration pattern | Other |
| GitHub stars | 16,121 (as of 2026-09-30) |
| GitHub forks | 1,461 |
| Last push | 2026-09-30 |
| Latest release | release/2026-09-30 |
| Repository | [ag-ui-protocol/ag-ui](https://github.com/ag-ui-protocol/ag-ui) |
| Website | [ag-ui.com](https://ag-ui.com/) |
| Documentation | [docs.ag-ui.com](https://docs.ag-ui.com/introduction) |
| Last verified | 2026-09-30 |

## Key features

- A run is the unit of interaction: the application sends one RunAgentInput, and the agent endpoint answers with one ordered stream of typed events; nothing travels on a side channel. ([source](https://docs.ag-ui.com/spec/1.0/architecture))
- Version 1.0 defines 31 event types in eight families: runs and steps, text messages, tool calls, reasoning, state, activity, subagents, and raw/custom passthrough. Only the run lifecycle is mandatory for producers. ([source](https://docs.ag-ui.com/spec/1.0/events))
- Shared state travels as STATE_SNAPSHOT replacements and STATE_DELTA JSON Patch (RFC 6902) amendments, and round-trips through the application on every run. ([source](https://docs.ag-ui.com/spec/1.0/events/state))
- Tool calls are streamed by the agent and can be frontend tools that the application executes; the run then finishes and the answer rides the next run's input. ([source](https://docs.ag-ui.com/spec/1.0/events/tool-calls))
- A run that needs an approval, credential or choice ends with an interrupt outcome listing what it waits for (with an optional response schema), and the next run carries resume entries. ([source](https://docs.ag-ui.com/spec/1.0/basic/patterns/interrupt-resume))
- Subagent events and a subagentRunId field attribute delegated work to the subagent that produced it, with rules for nesting, parallel runs and termination. ([source](https://docs.ag-ui.com/spec/1.0/events/subagents))
- Two standard HTTP bindings share the same POST request: Server-Sent Events carrying JSON (required for HTTP implementations) and an optional length-prefixed Protobuf stream. ([source](https://docs.ag-ui.com/spec/1.0/basic/transports))
- Middleware in the AG-UI repository connects runs to MCP servers (tool injection and execution) and, experimentally, to A2A agents. ([source](https://github.com/ag-ui-protocol/ag-ui/blob/main/middlewares/mcp-middleware/README.md))

## Architecture and orchestration pattern

Pattern: Other.

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 in the loop

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.

## Protocols

| Protocol | Support | Evidence | Note |
| --- | --- | --- | --- |
| MCP | Yes (checked 2026-09-30) | [link](https://github.com/ag-ui-protocol/ag-ui/blob/main/middlewares/mcp-middleware/README.md) | Bridge in AG-UI's own repository: @ag-ui/mcp-middleware (0.0.x pre-release) lists MCP server tools, injects them into a run and executes the calls; @ag-ui/mcp-apps-middleware adds MCP Apps UI tools, and the docs describe these as handshakes with MCP. |
| A2A | Partial (checked 2026-09-30) | [link](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/a2a/typescript/README.md) | Bridge in AG-UI's own repository, labelled Experimental: @ag-ui/a2a converts AG-UI conversations to A2A requests through the official A2A SDK and replays A2A messages, task updates and artifacts as AG-UI events. |
| AG-UI | Yes (checked 2026-09-30) | [link](https://docs.ag-ui.com/spec/1.0) | This is the AG-UI specification itself; current version 1.0. |

## Best for

- Streaming agent text, tool calls and shared state into a web app through the first-party TypeScript client. ([shortlist](https://multiagentguide.top/best/typescript.md))
- Approval steps that pause an agent run and resume it with the user's answer.
- Showing which subagent produced which output in a multi-agent run.
- Putting one frontend in front of agents built on different frameworks through bridges.

## Not for

- Agent-to-agent delegation across services; the AG-UI docs assign that layer to A2A.
- Connecting an agent to tools and data sources on its own; that is MCP's layer, which AG-UI reaches only through middleware.
- Transports that cannot deliver events in order and completely without an extra layer; the binding contract requires both.

## Quickstart

```sh
pip install ag-ui-protocol
```

Install verified 2026-09-30 (uv venv, Python 3.12.13, macOS arm64: `uv pip install ag-ui-protocol` ok, `import ag_ui.core` ok, ag-ui-protocol 1.0.0. Packages came from the mirrors.aliyun.com mirror, so the version is the one that mirror served on this date. Install and import check only; not a functional test.).

```python
# 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())
```

### Common pitfalls

- 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.

Official quickstart: https://docs.ag-ui.com/sdk/python/core/overview

## Pros

- 1.0 is the first release with a normative specification, and every SDK's types are generated from one JSON Schema. ([source](https://docs.ag-ui.com/migrating-to-1-0))
- Compatibility runs both ways: 0.x agents work with 1.0 clients and 1.0 agents work with 0.x clients. ([source](https://docs.ag-ui.com/migrating-to-1-0))
- Approvals and other human input are part of the protocol through the interrupt and resume pattern. ([source](https://docs.ag-ui.com/spec/1.0/basic/patterns/interrupt-resume))
- The protocol's README lists integrations for many agent frameworks, including LangChain, CrewAI, Microsoft Agent Framework, Google ADK, Mastra and Pydantic AI. ([source](https://github.com/ag-ui-protocol/ag-ui/blob/main/README.md))
- An optional binary Protobuf binding is specified alongside JSON over SSE. ([source](https://docs.ag-ui.com/spec/1.0/changelog))

## Cons

- Compatibility shims for retired 0.x shapes have provisional expiry dates, after which old streams stop working. ([source](https://docs.ag-ui.com/migrating-to-1-0))
- There is no mid-run channel from the application to the agent; answering an interrupt always starts a new run. ([source](https://docs.ag-ui.com/spec/1.0/basic/patterns/interrupt-resume))
- The protocol defines no authentication; security is left to the transport binding and the application. ([source](https://docs.ag-ui.com/spec/1.0/basic/transports))
- The A2A bridge is marked Experimental and its APIs may change. ([source](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/a2a/typescript/README.md))
- Most SDKs beyond TypeScript and Python (Kotlin, Go, Java, Rust, Ruby, Dart, C++, .NET) are listed as community-maintained. ([source](https://github.com/ag-ui-protocol/ag-ui/blob/main/README.md))

## Alternatives

- [Model Context Protocol (MCP)](https://multiagentguide.top/tools/mcp.md)
- [Agent2Agent (A2A) Protocol](https://multiagentguide.top/tools/a2a.md)
- [CopilotKit](https://multiagentguide.top/tools/copilotkit.md)
- [Microsoft Agent Framework](https://multiagentguide.top/tools/microsoft-agent-framework.md)
- [Pydantic AI](https://multiagentguide.top/tools/pydantic-ai.md)

## FAQ

### What version is AG-UI?

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.

### How does AG-UI relate to MCP and A2A?

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.

### Who maintains AG-UI?

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.

### Is AG-UI free?

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

### Is AG-UI the same as A2UI?

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.

## Sources

- [AG-UI GitHub repository](https://github.com/ag-ui-protocol/ag-ui)
- [AG-UI homepage](https://ag-ui.com/)
- [AG-UI documentation](https://docs.ag-ui.com/introduction)
- [README](https://github.com/ag-ui-protocol/ag-ui/blob/main/README.md)
- [LICENSE (MIT)](https://github.com/ag-ui-protocol/ag-ui/blob/main/LICENSE)
- [Specification 1.0](https://docs.ag-ui.com/spec/1.0)
- [Key changes in 1.0](https://docs.ag-ui.com/spec/1.0/changelog)
- [Architecture](https://docs.ag-ui.com/spec/1.0/architecture)
- [Event streams](https://docs.ag-ui.com/spec/1.0/events)
- [State events](https://docs.ag-ui.com/spec/1.0/events/state)
- [Tool call events](https://docs.ag-ui.com/spec/1.0/events/tool-calls)
- [Subagent events](https://docs.ag-ui.com/spec/1.0/events/subagents)
- [Interrupts and resume](https://docs.ag-ui.com/spec/1.0/basic/patterns/interrupt-resume)
- [Transports](https://docs.ag-ui.com/spec/1.0/basic/transports)
- [MCP, A2A, and AG-UI](https://docs.ag-ui.com/agentic-protocols)
- [Migrating to 1.0](https://docs.ag-ui.com/migrating-to-1-0)
- [Python SDK overview](https://docs.ag-ui.com/sdk/python/core/overview)
- [Server quickstart](https://docs.ag-ui.com/quickstart/server)
- [Production support](https://docs.ag-ui.com/talk-to-us)
- [MCP middleware README](https://github.com/ag-ui-protocol/ag-ui/blob/main/middlewares/mcp-middleware/README.md)
- [@ag-ui/a2a integration README](https://github.com/ag-ui-protocol/ag-ui/blob/main/integrations/a2a/typescript/README.md)
- [Release 2026-09-17 (@ag-ui/core 1.0.0)](https://github.com/ag-ui-protocol/ag-ui/releases/tag/release/2026-09-17)

Corrections or removal requests: support@multiagentguide.top

---

Data as of 2026-09-30. Not affiliated with listed projects. HTML version: https://multiagentguide.top/tools/ag-ui