Introduction
"Bring Agents into Frontend Applications."
This is the 262nd article in the "One Open Source Project a Day" series. Today's project is ag-ui-protocol's AG-UI.
Anyone who has built a chat interface has hit this snag: an agent is not a simple request and a single response. It streams its output token by token, calls a tool halfway through a reply, updates some shared state along the way, stops to wait for user confirmation, and may spin up subagents. Each agent framework handles these differently, so the frontend ends up with custom code for every framework.
What AG-UI wants to do is standardize this layer: the agent emits a typed event stream, and any frontend renders it by the same conventions. One agent can then reach a web page, a mobile app, a terminal, or even Slack without being wired up again each time.
This article follows the README and the repo's directory listing. I did not install it or run the commands in it.
What You Will Learn
- What problem AG-UI solves, and how it relates to MCP and A2A
- How the event stream is designed: what kinds of events appear in a single run
- How streaming chat, shared state, frontend tools, and human-in-the-loop map onto events
- How to stand up a minimal server and client in TypeScript and Python
- The project's limits, and the commercial background behind it
Prerequisites
- Basic knowledge of AI agents, and having used tool calling (function calling)
- A basic idea of SSE (Server-Sent Events) and streaming rendering on the frontend
- Optional: some familiarity with MCP and A2A
Project Background
What It Is
The README's definition: an open, lightweight, event-based protocol that standardizes how AI agents connect to user-facing applications. It is MIT-licensed, created by CopilotKit, and developed publicly with the community.
The current release is AG-UI 1.0. The README calls it a "stable, frozen specification" backed by a JSON Schema, and backward compatible in both directions: 0.x agents work with 1.0 clients and the reverse.
Project Stats
- ⭐ GitHub Stars: about 19,107
- 🍴 Forks: about 1,969
- 💻 Language: TypeScript (monorepo)
- 📅 Created: 2025-05-07; last pushed 2026-11-16; latest release tag
release/2026-11-13 - 📄 License: MIT
- 👤 Started by: CopilotKit, developed with the community
- 🌐 Website: ag-ui.com; docs: docs.ag-ui.com
What It Does
Relationship to MCP and A2A
The README places AG-UI in a set of three:
| Protocol | What it solves |
|---|---|
| MCP | Gives agents tools and context |
| A2A | Lets agents collaborate with other agents |
| AG-UI | Delivers agents to users |
The three are complementary. An agent often uses all of them, and AG-UI can sit in front of agents that speak MCP or A2A.
Its relation to A2UI needs separate explanation: A2UI, MCP Apps, and Open-JSON-UI are generative UI specs that describe "what interface the agent wants to show," while AG-UI is the runtime protocol that carries those payloads, and everything else, between the agent and the app. The former is "what to say," the latter is "how to carry it."
The Problem It Solves
Without a shared protocol:
Each agent framework has its own streaming, tool calls, and state sync
↑ the frontend needs custom wiring per framework, and switching frameworks means a rewrite
With AG-UI:
The agent emits a typed event stream → any compatible client can render it
↓ one agent can connect to the web, mobile, terminal, and Slack
↑ the frontend is decoupled from the agent frameworkCapabilities at a Glance
The README breaks capabilities into "building blocks." Each maps to a set of events and has an example in the Dojo demo site:
| Capability | Description |
|---|---|
| Streaming chat | Multi-turn token streaming, with cancel and resume |
| Generative UI | Typed components, or declarative UI through A2UI and MCP Apps |
| Shared state | A typed store both sides read and write, synced by snapshots and JSON Patch |
| Frontend tools | Tools executed in the app, with results returned to the agent |
| Human in the loop | A run ends with an interrupt outcome; the user approves, edits, or rejects, and the next run resumes from there |
| Reasoning | Live reasoning display, including encrypted round-trips |
| Subagents | Nested delegation, with events attributed to the subagent's run |
| Multimodal | Images, audio, video, and documents in input and tool results |
Quick Start
Option 1: scaffold. One command generates an app (CopilotKit on Next.js, or a terminal client):
npx create-ag-ui-app@latest
export OPENAI_API_KEY="sk-..."Option 2: minimal Python server
pip install ag-ui-protocol fastapi uvicorn
uvicorn server:app --port 8000The README describes a FastAPI endpoint that accepts RunAgentInput and streams events out with EventEncoder and StreamingResponse.
Option 3: minimal TypeScript client (needs Node.js 20+)
npm init -y && npm pkg set type=module
npm install @ag-ui/client tsx
npx tsx client.tsThe client uses HttpAgent and receives events through callbacks such as onRunStartedEvent and onTextMessageContentEvent.
SDKs
| Language | Install command |
|---|---|
| TypeScript | npm install @ag-ui/client (@ag-ui/core also exists) |
| Python | pip install ag-ui-protocol |
| .NET | dotnet add package AGUI.Client |
All three SDKs are generated from the spec. Community SDKs cover Kotlin, Go, Java, Dart, Rust, Ruby, C++, and Swift; I did not check how mature each one is.
A Deeper Look
The Event Stream: How One Run Plays Out
The core model is simple:
- The app sends a
RunAgentInput, carrying the conversation, frontend tools, shared state, and context - The agent answers with a typed event stream
- Only the "run lifecycle" events are mandatory, so a minimal agent can run by emitting just a few events and grow from there
The README says AG-UI 1.0 defines 31 event types in eight families:
| Family | Events |
|---|---|
| Runs and steps | RUN_STARTED RUN_FINISHED RUN_ERROR STEP_STARTED STEP_FINISHED |
| Text messages | TEXT_MESSAGE_START TEXT_MESSAGE_CONTENT TEXT_MESSAGE_END TEXT_MESSAGE_CHUNK |
| Tool calls | TOOL_CALL_START TOOL_CALL_ARGS TOOL_CALL_END TOOL_CALL_RESULT TOOL_CALL_CHUNK |
| State | STATE_SNAPSHOT STATE_DELTA (JSON Patch) MESSAGES_SNAPSHOT |
| Reasoning | REASONING_START REASONING_MESSAGE_* REASONING_ENCRYPTED_VALUE REASONING_END |
| Activity | ACTIVITY_SNAPSHOT ACTIVITY_DELTA |
| Subagents | SUBAGENT_STARTED SUBAGENT_FINISHED SUBAGENT_ERROR |
| Passthrough | RAW CUSTOM |
One detail I checked myself: apart from the REASONING_MESSAGE_* wildcard, the table lists 27 event names. The README gives the total as 31, which would mean the wildcard expands to 4, but the README does not list them one by one, so I have not written their names; check the official spec page if you need them.
To get a feel for the stream, take an agent that answers a question and calls a tool midway. The event order looks roughly like this (an illustration, not a real capture):
RUN_STARTED
TEXT_MESSAGE_START
TEXT_MESSAGE_CONTENT "Let me check..."
TEXT_MESSAGE_END
TOOL_CALL_START
TOOL_CALL_ARGS
TOOL_CALL_END
TOOL_CALL_RESULT
TEXT_MESSAGE_START
TEXT_MESSAGE_CONTENT "The result is..."
TEXT_MESSAGE_END
RUN_FINISHEDThe frontend does not need to know whether LangGraph or CrewAI is behind it. If it recognizes these events, it can show text as it arrives, draw a tool call as a card, and sync state changes into the UI.
State Sync With JSON Patch
Shared state is synced with two events: STATE_SNAPSHOT gives the full state, and STATE_DELTA sends only what changed, in JSON Patch format. Large state does not have to be re-sent whole each time, which is a practical design.
Human in the Loop: End the Run With an interrupt
The human-in-the-loop approach is interesting: rather than leaving the agent hanging while it waits, the run ends with an interrupt outcome, and after the user approves, edits, or rejects, a next run starts and picks up from there. The server does not have to hold a suspended connection for a long time.
Transport
AG-UI does not bind you to one transport. The spec defines two bindings: HTTP with SSE, and HTTP with Protobuf (binary). The README also says middleware can adapt events from any source, and mentions other transports such as WebSockets, but only SSE and Protobuf are listed as spec bindings.
Ecosystem and Integrations
The README says AG-UI is adopted by Google, Microsoft, Amazon, Oracle, and others, and is built into most agent frameworks:
- Partners: LangChain, CrewAI
- Built in: Microsoft Agent Framework, Google ADK, AWS Strands Agents, Mastra, Pydantic AI, Agno, LlamaIndex, AG2, and others
- More frameworks: Claude Agent SDK, IBM watsonx Orchestrate, Langroid, Spring AI, Cloudflare Agents, OpenAI Agents, and others
- Clients: CopilotKit (React, Angular, Vue, React Native), Slack and Teams, terminal, and more
The repo's integrations/ directory has matching subfolders, such as langgraph, crew-ai, mastra, microsoft-agent-framework, openai-agents, claude-agent-sdk, and vercel-ai-sdk. "Adopted" is the README's wording, and I did not verify how complete each integration is; check the docs in the relevant directory when you use one.
Repo Layout
sdks/:typescript,python,dotnet,communityintegrations/: the integration for each framework, plus two templates,server-starterandserver-starter-all-featuresmiddlewares/: middleware (MCP, A2UI, and a starter template)apps/dojo: the live demos (dojo.ag-ui.com)spec/anddocs/: the spec and documentation
Limits and Cautions
The README says little about limits, so here is my summary:
- Not every framework is natively integrated: the README says middleware can adapt unsupported sources, which itself suggests integration depth varies
- Spec bindings are only SSE and Protobuf: using WebSockets and the like means adapting it yourself
- The project was started by CopilotKit: many integration docs link to CopilotKit's docs. The protocol itself is MIT open source, but if you want a ready-made frontend scaffold, you will naturally land in the CopilotKit ecosystem, so keep that in mind when choosing
- 1.0 is frozen: stability is the benefit, and the cost is that new needs wait for a later draft spec; the README mentions a public roadmap and a draft spec but does not describe what is in them
Project Links and Resources
- 🌟 GitHub: https://github.com/ag-ui-protocol/ag-ui
- 🌐 Website: https://ag-ui.com
- 📚 Docs: docs.ag-ui.com (spec 1.0: docs.ag-ui.com/spec/1.0)
- 🎮 Live demos: dojo.ag-ui.com
- 💬 Community: Discord, GitHub Discussions, GitHub Issues
- 📄 License: MIT
Summary
Key Takeaways
- Positioning: MCP handles tools, A2A handles agent-to-agent, AG-UI handles agent-to-user, and the three are complementary
- Core design: a run emits one typed event stream, and only lifecycle events are mandatory, so it is easy to start and easy to extend
- Coverage: streaming text, tool calls, shared state, reasoning, human-in-the-loop, subagents, and multimodal
- Ecosystem: TypeScript, Python, and .NET SDKs, plus integrations with many frameworks
- Keep in mind: integration depth varies, and there is a CopilotKit commercial ecosystem behind it
Who This Is For
- Developers building frontends for agents who do not want to be tied to one framework
- Teams that want one agent to serve the web, terminal, and chat tools at once
- Anyone who wants to see how a frontend protocol for agent apps can be designed; this event model is worth studying
Suggested First Steps
Start at the Dojo demo site to see each capability in action, then read the event definitions in the spec. For hands-on work, use npx create-ag-ui-app@latest to get a scaffold, or follow the README to stand up a minimal FastAPI server, connect a TypeScript client, and print each event as it arrives, so you see the order of events in a run for yourself. Finally, look in integrations/ for the framework you use and check how complete its integration is.
Check out PrimeSkills — a curated marketplace of AI agents and skills that have been validated in real-world, enterprise-grade workflows. No fluff, just what actually works.
Find more useful knowledge and interesting products on my Homepage