AG-UI 1.0: A Frozen, Open Protocol For Streaming AI Agents to Any Frontend
One Open Source Project a Day (No. 262): AG-UI — an open protocol that brings AI agents into frontend applications, the third piece alongside MCP and A2A
Introduction
"Bring Agents into Frontend Applications."
This is the 262nd entry in the "One Open Source Project a Day" series. Today's project is AG-UI from the ag-ui-protocol organization.
Anyone who has built a chat interface has hit the problem: an agent is not a single request, a single response. It streams output token by token, stops midway to call a tool, updates some shared state mid-stream, pauses to wait for user confirmation, and may even spawn subagents. Every agent framework handles these in its own way, so a frontend has to write custom integration code for each framework.
AG-UI aims to standardize that layer: the agent emits a typed event stream, and any frontend can render it following the same conventions. The same agent can then be plugged into a web page, a mobile app, a terminal, or even Slack, without re-integrating.
This article is based on the README and repo structure; I have not installed or actually run the commands.
What you will learn
- What problem AG-UI solves and how it relates to MCP and A2A
- How the "event stream" is designed: which event types appear in a single run
- How capabilities such as streaming chat, shared state, frontend tools, and human intervention map to events
- How to spin up a minimal server and client in TypeScript and Python
- The project's boundaries and its commercial background
Prerequisites
- Basic understanding of AI agents and experience with function calling
- Basic familiarity with SSE (Server-Sent Events) and frontend streaming rendering
- Optional: understanding of MCP and A2A
Project Background
Project Intro
The README defines it as: an open, lightweight, event-based protocol that connects AI agents to user-facing applications. It is MIT-licensed, created by CopilotKit, and developed openly with the community.
The current version is AG-UI 1.0. The README calls it a "stable, frozen specification" with JSON Schema support and bidirectional backward compatibility: 0.x agents can work with 1.0 clients, and vice versa.
Project Data
- ⭐ GitHub Stars: about 19,107
- 🍴 Forks: about 1,969
- 💻 Language: TypeScript (Monorepo)
- 📅 Created: 2025-05-07, last push on 2026-11-16, latest release tag
release/2026-11-13 - 📄 License: MIT
- 👤 Initiated by: CopilotKit, community co-development
- 🌐 Website: ag-ui.com; Docs: docs.ag-ui.com
Main Features
Relationship with MCP and A2A
The README places AG-UI in a trio:
| Protocol | What it solves |
|---|---|
| MCP | Provides tools and context to agents |
| A2A | Lets agents collaborate with other agents |
| AG-UI | Delivers the agent to the user |
The three are complementary, and an agent often uses all three. AG-UI can also sit in front of agents that speak MCP or A2A.
Its relationship with A2UI needs to be clarified: A2UI, MCP Apps, and Open-JSON-UI are generative UI specifications that describe "what interface the agent wants to show"; AG-UI is a runtime protocol that transports these (and everything else) between agent and application. The former is "what to say," the latter is "how to transmit."
The Problem It Solves
Without a unified protocol:
Each agent framework has its own streaming, tool calls, and state sync
↑ Frontend has to write custom integration for each framework; changing frameworks means rewriting
With AG-UI:
Agent emits typed event stream → any compatible client can render it
↓ The same agent can plug into web, mobile, terminal, Slack
↑ Frontend decouples from agent frameworks
Capability Overview
The README breaks capabilities into several "building blocks," each corresponding to a set of events, with demos in the Dojo playground:
| Capability | Description |
|---|---|
| Streaming Chat | Multi-turn token streaming, with cancel and resume |
| Generative UI | Typed components, or declarative UI via A2UI, MCP Apps |
| Shared State | Typed storage read/written by both sides, synced via snapshots and JSON Patch |
| Frontend Tools | Tools executed on the application side, with results sent back to the agent |
| Human Intervention | A run ends with interrupt, user approves, modifies, or rejects; the next run resumes from there |
| Reasoning Display | Real-time display of reasoning, including encrypted round-trips |
| Subagents | Nested delegation, events carry the subagent run's ownership |
| Multimodal | Images, audio, video, and documents in inputs and tool results |
Quick Start
Option 1: Scaffold — one command generates an app (CopilotKit plus 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 8000
The README says it's a FastAPI endpoint: it receives RunAgentInput and uses EventEncoder and StreamingResponse to stream out events.
Option 3: Minimal TypeScript client (requires Node.js 20+)
npm init -y && npm pkg set type=module
npm install @ag-ui/client tsx
npx tsx client.ts
The client uses HttpAgent and receives events through callbacks like onRunStartedEvent, onTextMessageContentEvent.
SDKs
| Language | Install command |
|---|---|
| TypeScript | npm install @ag-ui/client (also @ag-ui/core) |
| Python | pip install ag-ui-protocol |
| .NET | dotnet add package AGUI.Client |
These three SDKs are generated from the spec. Community SDKs cover Kotlin, Go, Java, Dart, Rust, Ruby, C++, Swift; I have not individually verified their maturity.
Detailed Analysis
Event Stream: How a Run Progresses
The core model is simple:
- The application sends a
RunAgentInputwith conversation history, frontend tools, shared state, and context - The agent responds with a typed event stream
- Only the "run lifecycle" events are required, so a minimal agent can run by emitting a few events and then expand from there
The README says AG-UI 1.0 defines 31 event types in eight families:
| Family | Events |
|---|---|
| Run & Step | RUN_STARTED RUN_FINISHED RUN_ERROR STEP_STARTED STEP_FINISHED |
| Text Message | TEXT_MESSAGE_START TEXT_MESSAGE_CONTENT TEXT_MESSAGE_END TEXT_MESSAGE_CHUNK |
| Tool Call | 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 |
| Subagent | SUBAGENT_STARTED SUBAGENT_FINISHED SUBAGENT_ERROR |
| Passthrough | RAW CUSTOM |
One detail I verified myself: besides the wildcard REASONING_MESSAGE_*, the table lists 27 event names. The README says the total is 31, meaning the wildcard expands to 4 events, but the README does not list them individually, so I did not write out their names; check the official spec page when needed.
To feel the stream with an example: ask the agent a question, and it calls a tool midway. The order of events is roughly (illustrative, 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_FINISHED
The frontend does not need to know whether the backend is LangGraph or CrewAI; as long as it recognizes these events, it can display text character by character, draw tool calls as cards, and sync state changes to the interface.
State Sync Uses JSON Patch
Shared state syncs through two event types: STATE_SNAPSHOT gives the full state, and STATE_DELTA sends only the changes, in JSON Patch format. This means large states do not need to be fully re-transmitted each time, a very practical design.
Human Intervention: Ending a Run with interrupt
The approach to human-in-the-loop is interesting: instead of having the agent hang waiting, it ends the run with an interrupt outcome. After the user approves, modifies, or rejects, the next run resumes from that point. That way the server does not have to hold a long-lived pending connection.
Transport Layer
AG-UI is not bound to a specific transport. The spec defines two bindings: HTTP plus SSE, and HTTP plus Protobuf (binary). The README also mentions using middleware to adapt arbitrary event sources, and references WebSocket and other transports, but only SSE and Protobuf are listed as spec bindings.
Ecosystem and Integrations
The README states AG-UI is adopted by Google, Microsoft, Amazon, Oracle, and others, and is built into most agent frameworks:
- Partners: LangChain, CrewAI
- Built-in support: Microsoft Agent Framework, Google ADK, AWS Strands Agents, Mastra, Pydantic AI, Agno, LlamaIndex, AG2, etc.
- More frameworks: Claude Agent SDK, IBM watsonx Orchestrate, Langroid, Spring AI, Cloudflare Agents, OpenAI Agents, etc.
- Clients: CopilotKit (React, Angular, Vue, React Native), Slack and Teams, terminal, etc.
In the repository's integrations/ directory you can see corresponding subdirectories, e.g., langgraph, crew-ai, mastra, microsoft-agent-framework, openai-agents, claude-agent-sdk, vercel-ai-sdk. Note that "adopted" is the README's claim; I have not verified the completeness of each integration. When you use one, look at the documentation in that directory.
Repository Structure
sdks/:typescript,python,dotnet,communityintegrations/: integration implementations for various frameworks, plusserver-starterandserver-starter-all-featurestemplatesmiddlewares/: middleware (MCP, A2UI, and starter templates)apps/dojo: online demo (dojo.ag-ui.com)spec/anddocs/: spec and documentation
Limitations and Caveats
The README says little about limitations; I summarize a few points:
- Not every framework is natively integrated: the README mentions using middleware to adapt unsupported sources, which itself indicates varying integration depth
- Only SSE and Protobuf are spec bindings: using WebSocket etc. requires your own adaptation
- The project is initiated by CopilotKit: many integration documents link to CopilotKit docs. The protocol itself is MIT open source, but if you want a ready-made frontend scaffold, you will naturally fall into CopilotKit's ecosystem; keep that in mind when choosing
- 1.0 is frozen: the benefit is stability; the cost is that new requirements wait for future draft specs. The README mentions a public roadmap and draft specs but does not describe their content
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)
- 🎮 Online demo: dojo.ag-ui.com
- 💬 Community: Discord, GitHub Discussions, GitHub Issues
- 📄 License: MIT
Summary and Outlook
Key Points Recap
- Positioning: MCP handles tools, A2A handles agent-to-agent, AG-UI handles agent-to-user; the three are complementary
- Core design: a run emits a typed event stream; only lifecycle events are required, making it easy to start and extend
- Coverage: streaming text, tool calls, shared state, reasoning, human intervention, subagents, multimodal
- Ecosystem: TypeScript, Python, .NET SDKs, plus integrations with many frameworks
- Watch out: integration depth varies, and there is a CopilotKit commercial context
Who It's For
- Developers building frontends for agents who don't want to be tied to a specific framework
- Teams that want the same agent to serve web, terminal, and chat tools simultaneously
- Those who want to understand how "frontend protocols" for agent applications should be designed; this event model is worth referencing
Learning Suggestions
First, visit the Dojo demo to see each capability in action, then read the event definitions in the spec. To get hands-on, use npx create-ag-ui-app@latest to spin up a scaffold, or follow the README to start a minimal FastAPI server, connect with a TypeScript client, and print each event you receive to see the event order in a run. Finally, go to integrations/ to find the framework you use and see how complete its integration is.
Welcome to PrimeSkills — a curated AI Agent and skills marketplace, all verified through real enterprise workflows. No gimmicks, only what genuinely works.
For more practical knowledge and interesting products, visit my personal homepage