Skip to content
ag-ui-protocolPublic

About

AG-UI: the Agent-User Interaction Protocol. Bring Agents into Frontend Applications.

Topics

Resources

Contributing

Security policy

Stars

19.5k stars

Watchers

103 watching

Forks

Latest commit

 

History

5,480 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

AG-UI

The open protocol that connects any agent to any app.

npm version npm weekly downloads PyPI version Discord License: MIT

Docs · Examples · Spec · Discord

Running AG-UI in production? Talk to the team

ag-ui-protocol%2Fag-ui | Trendshift


AG-UI is an open, lightweight, event-based protocol that standardizes how AI agents connect to user-facing applications.

Agents don't fit the request/response model. They stream tokens, call tools mid-response, update shared state, pause for a human, and spawn subagents, and every framework does it differently. AG-UI replaces that custom wiring with one bi-directional event stream: the agent emits typed events, and any client can render them, no matter which framework built the agent. The same agent can power a web app, a mobile app, a terminal, or Slack.

AG-UI connects any agent to any app: web apps, mobile, Slack and Teams, and terminal clients connect bi-directionally through AG-UI to agents built with LangChain, CrewAI, Mastra, Google ADK, Microsoft Agent Framework, Pydantic AI or any framework, with streaming chat, generative UI, shared state, human in the loop, frontend tools and subagents; AG-UI works alongside MCP for tools and A2A for agents.

Important

AG-UI 1.0 is here. The protocol now has a stable, frozen specification backed by a JSON Schema, and the TypeScript, Python, and .NET SDKs are generated from it. 1.0 is backwards compatible in both directions: 0.x agents work with 1.0 clients and vice versa. What changed → · Migration guide →

Quick start

Start a new app. The CLI scaffolds a frontend (CopilotKit on Next.js, or a terminal client) wired to the agent framework you pick:

npx create-ag-ui-app@latest

Then follow the printed next steps. The generated templates call OpenAI, so set your key before npm run dev:

export OPENAI_API_KEY="sk-..."
Or speak the protocol directly: a 30-line agent server and client

An AG-UI agent is any HTTP endpoint that accepts a RunAgentInput and streams events back. No API keys needed for this one.

1. The agent (Python). Requires Python 3.9+.

pip install ag-ui-protocol fastapi uvicorn
# server.py
import uuid

from fastapi import FastAPI, Request
from fastapi.responses import StreamingResponse
from ag_ui.core import (
    PROTOCOL_VERSION,
    RunAgentInput,
    RunStartedEvent,
    RunFinishedEvent,
    TextMessageStartEvent,
    TextMessageContentEvent,
    TextMessageEndEvent,
)
from ag_ui.encoder import EventEncoder

app = FastAPI()

@app.post("/")
async def run_agent(input_data: RunAgentInput, request: Request):
    encoder = EventEncoder(accept=request.headers.get("accept"))

    async def events():
        yield encoder.encode(RunStartedEvent(
            thread_id=input_data.thread_id,
            run_id=input_data.run_id,
            protocol_version=PROTOCOL_VERSION,
        ))
        message_id = str(uuid.uuid4())
        yield encoder.encode(TextMessageStartEvent(message_id=message_id, role="assistant"))
        for chunk in ["Hello ", "from ", "AG-UI!"]:
            yield encoder.encode(TextMessageContentEvent(message_id=message_id, delta=chunk))
        yield encoder.encode(TextMessageEndEvent(message_id=message_id))
        yield encoder.encode(RunFinishedEvent(thread_id=input_data.thread_id, run_id=input_data.run_id))

    return StreamingResponse(events(), media_type=encoder.get_content_type())
uvicorn server:app --port 8000

2. The client (TypeScript). In a second terminal, in a new folder. Requires Node.js 20+.

npm init -y && npm pkg set type=module
npm install @ag-ui/client tsx
// client.ts
import { HttpAgent } from "@ag-ui/client";

const agent = new HttpAgent({ url: "http://localhost:8000/" });

agent.addMessage({ id: crypto.randomUUID(), role: "user", content: "Hi there!" });

await agent.runAgent({}, {
  onRunStartedEvent: ({ event }) => console.log(`run started (AG-UI ${event.protocolVersion})`),
  onTextMessageContentEvent: ({ event }) => { process.stdout.write(event.delta); },
  onRunFinishedEvent: () => console.log("\nrun finished"),
});
npx tsx client.ts

You should see Hello from AG-UI! stream in. Swap the server for any supported framework and the client doesn't change.

Where AG-UI fits

Diagram showing where AG-UI fits: a user works in your app, which connects to your agent through AG-UI (agent to user), while the agent reaches tools and data through MCP and other agents through A2A; a single agent often uses all three.

AG-UI is one of three open, complementary agentic protocols. MCP gives agents tools and context, A2A lets agents work with other agents, and AG-UI brings agents to users. A single agent often uses all three, and AG-UI can front agents that speak MCP or A2A. Read more →

Note

AG-UI or A2UI? They work together. A2UI, MCP Apps, and Open-JSON-UI are generative UI specs: they describe what UI an agent wants to show. AG-UI is the runtime protocol that carries those payloads, along with everything else, between the agent and the app. Learn more →

Integrations

AG-UI is adopted by Google, Microsoft, Amazon, and Oracle, and built into most agent frameworks. Every framework below has a live demo in the Dojo.

LangChain logo
LangChain
Docs · Demo
CrewAI logo
CrewAI
Docs · Demo
Microsoft Agent Framework logo
Microsoft Agent Framework
Docs · Demo
Google ADK logo
Google ADK
Docs · Demo
AWS Strands Agents logo
AWS Strands Agents
Docs · Demo
Mastra logo
Mastra
Docs · Demo
Pydantic AI logo
Pydantic AI
Docs · Demo
LlamaIndex logo
LlamaIndex
Docs · Demo
Agno logo
Agno
Docs · Demo
AG2 logo
AG2
Docs · Demo
Claude Agent SDK logo
Claude Agent SDK
Docs · Demo

+11 more
Antigravity, OpenAI Agents, watsonx, Spring AI, and others in the full list

Protocols: A2A · MCP · MCP Apps · A2UI
Clients: CopilotKit (React, Angular, Vue, React Native) · Slack & Teams · Terminal · OpenBot

Don't see your framework? Build an integration →

Full list of integrations

Show all integrations

Source for every integration lives in integrations/ and middlewares/, and the demos in apps/dojo.

SDKs

Language Install Reference
TypeScript npm install @ag-ui/client Docs · Source
Python pip install ag-ui-protocol Docs · Source
.NET dotnet add package AGUI.Client Docs · Source

Community SDKs: Kotlin · Go · Java · Dart · Rust · Ruby · C++ · Swift

Features: what you can build

Each building block maps to events in the spec, and each has a live demo in the AG-UI Dojo.

Building block What it does Try it
Streaming chat Token-by-token messages across multi-turn sessions, with cancel and resume Demo
Generative UI Agents render typed components, or declarative UI with A2UI and MCP Apps Demo
Shared state A typed store the agent and app both read and write, synced with snapshots and JSON Patch deltas Demo
Frontend tools The agent calls tools that run in the app, and gets the result back Demo
Human in the loop Runs end with an interrupt outcome; the user approves, edits, or rejects, and the next run resumes Demo
Reasoning Show the agent's reasoning as it works, including encrypted reasoning round-trips Demo
Subagents Nested delegation, with every event attributed to the subagent run that produced it Demo
Multimodal Images, audio, video, and documents in user input and tool results Demo

Tool output streaming, backend tool rendering, activity progress, token usage, and custom events are covered in the docs. Here's a quick tour of the Dojo:

dojo.mp4

How it works

Diagram of how AG-UI works: your app (CopilotKit, React, mobile, terminal, Slack or any client) sends a single RunAgentInput with messages, tools, state and context to your agent (LangChain, CrewAI, Mastra, Google ADK, Pydantic AI or any framework), and the agent streams back typed AG-UI events for lifecycle, text messages, tool calls, state, reasoning, activity, subagents, and custom and raw data, over any transport such as SSE, WebSockets or HTTP binary (Protobuf).

Your app starts a run by sending the agent a single RunAgentInput: the conversation, the tools the frontend offers, shared state, and context. The agent answers with a stream of typed events from eight families: run lifecycle, text messages, tool calls, state, reasoning, activity, subagents, and custom events (full list). Only the run lifecycle is required, so a minimal agent emits a handful of events and grows from there.

AG-UI is transport-agnostic. The spec defines HTTP + SSE and a binary HTTP + Protobuf binding, and middleware can adapt events from any source. Read the architecture overview for the full picture.

Event reference

AG-UI 1.0 defines 31 event types in eight families. See the spec for every field.

Event 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

Community

Contributing

Contributions are welcome: new integrations, SDKs, docs, and fixes. Start with CONTRIBUTING.md, and use the server starter and middleware starter as templates for new integrations. Report security issues as described in SECURITY.md.

AG-UI was created by CopilotKit and is developed in the open with the community.

License

AG-UI is open source under the MIT License.

About

AG-UI: the Agent-User Interaction Protocol. Bring Agents into Frontend Applications.

Topics

Resources

Contributing

Security policy

Stars

19.5k stars

Watchers

103 watching

Forks

Releases

Packages

Used by

Contributors

Languages