跪拜 Guibai
← Back to the summary

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

Prerequisites


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


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:

  1. The application sends a RunAgentInput with conversation history, frontend tools, shared state, and context
  2. The agent responds with a typed event stream
  3. 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:

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

Limitations and Caveats

The README says little about limitations; I summarize a few points:

  1. Not every framework is natively integrated: the README mentions using middleware to adapt unsupported sources, which itself indicates varying integration depth
  2. Only SSE and Protobuf are spec bindings: using WebSocket etc. requires your own adaptation
  3. 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
  4. 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


Summary and Outlook

Key Points Recap

  1. Positioning: MCP handles tools, A2A handles agent-to-agent, AG-UI handles agent-to-user; the three are complementary
  2. Core design: a run emits a typed event stream; only lifecycle events are required, making it easy to start and extend
  3. Coverage: streaming text, tool calls, shared state, reasoning, human intervention, subagents, multimodal
  4. Ecosystem: TypeScript, Python, .NET SDKs, plus integrations with many frameworks
  5. Watch out: integration depth varies, and there is a CopilotKit commercial context

Who It's For

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