Repository: ag-ui-protocol/ag-ui

Stars: 13050

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Common Development Commands

TypeScript SDK (Main Development)

bash

Install dependencies (using pnpm)

pnpm install
Build all packages

pnpm build
Run development mode

pnpm dev
Run linting

pnpm lint

Run type checking

pnpm check-types
Run tests

pnpm test
Format code

pnpm format
Clean build artifacts

pnpm clean
Full clean build

pnpm build:clean

Python SDK

bash

Navigate to python-sdk directory

cd python-sdk
Install dependencies (using poetry)

poetry install
Run tests

python -m unittest discover tests
Build distribution

poetry build

Running Specific Integration Tests

bash

For TypeScript packages/integrations

cd packages/<package-name>
pnpm test
For running a single test file

cd packages/<package-name>
pnpm test -- path/to/test.spec.ts

High-Level Architecture

AG-UI is an event-based protocol that standardizes agent-user interactions. The codebase is organized as a monorepo with the following structure:

Core Protocol Architecture

- Event-Driven Communication: All agent-UI communication happens through typed events (BaseEvent and its subtypes)
- Transport Agnostic: Protocol supports SSE, WebSockets, HTTP binary, and custom transports
- Observable Pattern: Uses RxJS Observables for streaming agent responses

Key Abstractions

1. AbstractAgent: Base class that all agents must implement with a run(input: RunAgentInput) -> Observable<BaseEvent> method
2. HttpAgent: Standard HTTP client supporting SSE and binary protocols for connecting to agent endpoints
3. Event Types: Lifecycle events (RUN_STARTED/FINISHED), message events (TEXT_MESSAGE_), tool events (TOOL_CALL_), and state management events (STATE_SNAPSHOT/DELTA)

Repository Structure

- /sdks/typescript/: Main TypeScript implementation
- /packages/: Core protocol packages (@ag-ui/core, @ag-ui/client, @ag-ui/encoder, @ag-ui/proto)
- /integrations/: Framework integrations (langgraph, mastra, crewai, etc.)
- /apps/: Example applications including the AG-UI Dojo demo viewer
- /sdks/python/: Python implementation of the protocol
- /docs/: Documentation site content

Integration Pattern

Each framework integration follows a similar pattern:
1. Implements the AbstractAgent interface
2. Translates framework-specific events to AG-UI protocol events
3. Provides both TypeScript client and Python server implementations
4. Includes examples demonstrating key AG-UI features (agentic chat, generative UI, human-in-the-loop, etc.)

State Management

- Uses STATE_SNAPSHOT for complete state representations
- Uses STATE_DELTA with JSON Patch (RFC 6902) for efficient incremental updates
- MESSAGES_SNAPSHOT provides conversation history

Multiple Sequential Runs

- AG-UI supports multiple sequential runs in a single event stream
- Each run must complete (RUN_FINISHED) before a new run can start (RUN_STARTED)
- Messages accumulate across runs (e.g., messages from run1 + messages from run2)
- State continues to evolve across runs unless explicitly reset with STATE_SNAPSHOT
- Run-specific tracking (active messages, tool calls, steps) resets between runs

Development Workflow

- Nx is used for monorepo build orchestration
- Each package has independent versioning
- Integration tests demonstrate protocol compliance
- The AG-UI Dojo app showcases all protocol features with live examples

General Guidelines for working with Nx

- When running tasks (for example build, lint, test, e2e, etc.), always prefer running the task through nx (i.e. nx run, nx run-many, nx affected) instead of using the underlying tooling directly
- You have access to the Nx MCP server and its tools, use them to help the user
- When answering questions about the repository, use the nx_workspace tool first to gain an understanding of the workspace architecture where applicable.
- When working in individual projects, use the nx_project_details mcp tool to analyze and understand the specific project structure and dependencies
- For questions around nx configuration, best practices or if you're unsure, use the nx_docs tool to get relevant, up-to-date docs. Always use this instead of assuming things about nx configuration
- If the user needs help with an Nx configuration or project graph error, use the nx_workspace tool to get any errors
- For Nx plugin best practices, check node_modules/@nx/<plugin>/PLUGIN.md. Not all plugins have this file - proceed without it if unavailable.

README.md

<img src="https://github.com/user-attachments/assets/ebc0dd08-8732-4519-9b6c-452ce54d8058" alt="ag-ui Logo" width="22"/> AG-UI: The Agent-User Interaction Protocol

AG-UI is an open, lightweight, event-based protocol that standardizes how AI agents connect to user-facing applications.
Built for simplicity and flexibility, it enables seamless integration between AI agents, real time user context, and user interfaces.

---

<br>

![Version](https://www.npmjs.com/package/@ag-ui/core)
!MIT
!Discord

<a href="https://discord.gg/Jd3FzfdJa8" target="_blank"> Join our Discord → </a>     <a href="https://ag-ui.com/" target="_blank"> Read the Docs → </a>     <a href="https://dojo.ag-ui.com/" target="_blank"> Go to the AG-UI Dojo → </a>     <a href="https://x.com/CopilotKit" target="_blank"> Follow us → </a>

🚀 Getting Started

Create a new AG-UI application in seconds:

bash

npx create-ag-ui-app my-agent-app

<h3> Useful Links:</h3>

- The AG-UI Dojo
- Build AG-UI-powered applications(Quickstart)
- Build new AG-UI framework integrations (Quickstart)
- Book a call to discuss an AG-UI integration with a new framework
- Join the Discord Community

What is AG-UI?

AG-UI is an open, lightweight, event-based protocol for agent-human interaction, designed for simplicity & flexibility:

- During agent executions, agent backends emit events _compatible_ with one of AG-UI's ~16 standard event types
- Agent backends can accept one of a few simple AG-UI compatible inputs as arguments

AG-UI includes a flexible middleware layer that ensures compatibility across diverse environments:

- Works with any event transport (SSE, WebSockets, webhooks, etc.)
- Allows for loose event format matching, enabling broad agent and app interoperability

It also ships with a reference HTTP implementation and default connector to help teams get started fast.

Learn more about the specs →

Why AG-UI?

AG-UI was developed based on real-world requirements and practical experience building in-app agent interactions.

Where does AGUI fit in the agentic protocol stack?

AG-UI is complementary to the other 2 top agentic protocols
- MCP gives agents tools
- A2A allows agents to communicate with other agents
- AG-UI brings agents into user-facing applications

🚀 Features

- 💬 Real-time agentic chat with streaming
- 🔄 Bi-directional state synchronization
- 🧩 Generative UI and structured messages
- 🧠 Real-time context enrichment
- 🛠️ Frontend tool integration
- 🧑‍💻 Human-in-the-loop collaboration

🛠 Supported Integrations

AG-UI was born from CopilotKit's initial partnership with LangGraph and CrewAI - and brings the incredibly popular agent-user-interactivity infrastructure to the wider agentic ecosystem.

1st party = the platforms that have AG‑UI built in and provide documentation for guidance.

Frameworks

| Framework | Status | AG-UI Resources |
| ------------------------------------------------------------------ | ------------------------ | -------------------------------------------------------------------------------- |
| Built-in Agent | ✅ Supported | ➡️ Docs |

🤝 Partnerships

| Framework | Status | AG-UI Resources |
| ---------- | ------- | ---------------- |
| LangGraph | ✅ Supported | ➡️ Docs 🎮 Demos |
| CrewAI | ✅ Supported | ➡️ Docs 🎮 Demos |

🧩 1st Party

| Framework | Status | AG-UI Resources |
| ---------- | ------- | ---------------- |
| Microsoft Agent Framework | ✅ Supported | ➡️ Docs 🎮 Demos |
| Google ADK | ✅ Supported | ➡️ Docs 🎮 Demos |
| AWS Strands Agents | ✅ Supported | ➡️ Docs 🎮 Demos |
| AWS Bedrock AgentCore | ✅ Supported | ➡️ Docs |
| Mastra | ✅ Supported | ➡️ Docs 🎮 Demos |
| Pydantic AI | ✅ Supported | ➡️ Docs 🎮 Demos |
| Agno | ✅ Supported | ➡️ Docs 🎮 Demos |
| LlamaIndex | ✅ Supported | ➡️ Docs 🎮 Demos |
| AG2 | ✅ Supported | ➡️ Docs 🎮 Demos |
| AWS Bedrock Agents | 🛠️ In Progress | – |

🌐 Community

| Framework | Status | AG-UI Resources |
| ---------- | ------- | ---------------- |
| Langroid | ✅ Supported | 🎮 Demos |
| OpenAI Agent SDK | 🛠️ In Progress | – |
| Cloudflare Agents | 🛠️ In Progress | – |

Agent Interaction Protocols

| Protocols | Status | AG-UI Resources | Integrations |
| ---------- | ------- | ---------------- | ------------- |
| [A2A]() | ✅ Supported | ➡️ Docs | Partnership |

Infrastructure / Deployment

| Platform | Status | AG-UI Resources | Integrations |
| ---------- | ------- | ---------------- | ------------- |
| Amazon Bedrock AgentCore | ✅ Supported | ➡️ Docs | 1st Party |

Specification (standard)

| Framework | Status | AG-UI Resources |
| ---------- | ------- | ---------------- |
| Oracle Agent Spec | ✅ Supported | ➡️ Docs 🎮 Demos |

Generative UI

| Framework | Status | AG-UI Resources |
| ---------- | ------- | ---------------- |
| MCP Apps | ✅ Supported | ➡️ Docs 🎮 [Demos]() |

SDKs

| SDK | Status | AG-UI Resources | Integrations |
| --- | ------- | ---------------- | ------------- |
| [Kotlin]() | ✅ Supported | ➡️ Getting Started | Community |
| [Golang]() | ✅ Supported | ➡️ Getting Started | Community |
| [Dart]() | ✅ Supported | ➡️ Getting Started | Community |
| [Java]() | ✅ Supported | ➡️ Getting Started | Community |
| [Rust]() | ✅ Supported | ➡️ Getting Started | Community |
| [Ruby]() | ✅ Supported | ➡️ Getting Started | Community |
| [.NET]() | 🛠️ In Progress | ➡️ PR | Community |
| [Nim]() | 🛠️ In Progress | ➡️ PR | Community |
| [Flowise]() | 🛠️ In Progress | ➡️ GitHub Source | Community |
| [Langflow]() | 🛠️ In Progress | ➡️ GitHub Source | Community |
| [C++]() | 🛠️ In Progress | ➡️ GitHub Source | Community |

Clients

| Client | Status | AG-UI Resources | Integrations |
| --- | ------- | ---------------- | ------------- |
| CopilotKit | ✅ Supported | ➡️ Getting Started | 1st Party |
| [Terminal + Agent]() | ✅ Supported | ➡️ Getting Started | Community |
| [React Native]() | 🛠️ Help Wanted | ➡️ GitHub Source | Community |

View all supported integrations →

Examples

Hello World App

Video:

https://github.com/user-attachments/assets/18c03330-1ebc-4863-b2b8-cc6c3a4c7bae

https://agui-demo.vercel.app/

The AG-UI Dojo (Building-Blocks Viewer)

The AG-UI Dojo demonstrates AG-UI's core building blocks through simple, focused examples—each just 50-200 lines of code.

View the source code for the Dojo and all framework integrations here.

https://github.com/user-attachments/assets/c298eea8-3f39-4a94-b968-7712429b0c49

🙋🏽‍♂️ Contributing to AG-UI

Check out the Contributing guide

- Bi-Weekely AG-UI Working Group
📅 Follow the CopilotKit Luma Events Calendar

Roadmap

Check out the AG-UI Roadmap to see what's being built and where you can jump in.

📄 License

AG-UI is open source software licensed as MIT.

Repository: ag-ui-protocol/ag-ui

Stars: 13050

CLAUDE.md Copy Chapter

CLAUDE.md

Common Development Commands Copy Chapter

TypeScript SDK (Main Development) Copy Section

Install dependencies (using pnpm)

Build all packages

Run development mode

Run linting

Run type checking

Run tests

Format code

Clean build artifacts

Full clean build

Python SDK Copy Section

Navigate to python-sdk directory

Install dependencies (using poetry)

Run tests

Build distribution

Running Specific Integration Tests Copy Section

For TypeScript packages/integrations

For running a single test file

High-Level Architecture Copy Chapter

Core Protocol Architecture Copy Section

Key Abstractions Copy Section

Repository Structure Copy Section

Integration Pattern Copy Section

State Management Copy Section

Multiple Sequential Runs Copy Section

Development Workflow Copy Section

General Guidelines for working with Nx

README.md Copy Chapter

<img src="https://github.com/user-attachments/assets/ebc0dd08-8732-4519-9b6c-452ce54d8058" alt="ag-ui Logo" width="22"/> AG-UI: The Agent-User Interaction Protocol

🚀 Getting Started Copy Chapter

What is AG-UI? Copy Chapter

Why AG-UI? Copy Chapter

Where does AGUI fit in the agentic protocol stack? Copy Chapter

🚀 Features Copy Chapter

🛠 Supported Integrations Copy Chapter

Frameworks Copy Chapter

🤝 Partnerships Copy Section

🧩 1st Party Copy Section

🌐 Community Copy Section

Agent Interaction Protocols Copy Chapter

Infrastructure / Deployment Copy Chapter

Specification (standard) Copy Chapter

Generative UI Copy Chapter

SDKs Copy Chapter

Clients Copy Chapter

Examples Copy Chapter

Hello World App Copy Section

The AG-UI Dojo (Building-Blocks Viewer) Copy Chapter

🙋🏽‍♂️ Contributing to AG-UI Copy Chapter

Roadmap Copy Chapter

📄 License Copy Chapter

Explore Related Technologies & Topics

CLAUDE.md

Common Development Commands

TypeScript SDK (Main Development)

Python SDK

Running Specific Integration Tests

High-Level Architecture

Core Protocol Architecture

Key Abstractions

Repository Structure

Integration Pattern

State Management

Multiple Sequential Runs

Development Workflow

README.md

🚀 Getting Started

What is AG-UI?

Why AG-UI?

Where does AGUI fit in the agentic protocol stack?

🚀 Features

🛠 Supported Integrations

Frameworks

🤝 Partnerships

🧩 1st Party

🌐 Community

Agent Interaction Protocols

Infrastructure / Deployment

Specification (standard)

Generative UI

SDKs

Clients

Examples

Hello World App

The AG-UI Dojo (Building-Blocks Viewer)

🙋🏽‍♂️ Contributing to AG-UI

Roadmap

📄 License