# ag-ui-protocol/ag-ui architecture

> Architecture diagram of the GitHub repository ag-ui-protocol/ag-ui, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ag-ui-protocol/ag-ui
- Repository: https://github.com/ag-ui-protocol/ag-ui
- Video tour (about a minute): https://gitdiagram.com/ag-ui-protocol/ag-ui/video

## Overview

##### Project type and purpose
- AG-UI is an open, event-based protocol specification rather than a monolithic application.
- Its goal is to standardize how AI agent backends emit events and accept inputs in front-end applications.

##### File structure
- The only artifact in the repo is README.md, which serves as both documentation and the de-facto spec entry point.
- There are no “src/” or “lib/” directories here; the protocol reference implementation and client libraries live in other repos (e.g., CopilotKit for React).

##### README for additional insights
- AG-UI defines 16 standard event types, a handful of input types, and a middleware layer that can plug into any transport (SSE, WebSockets, webhooks, etc.).
- It ships a reference HTTP implementation and a default connector; it interoperates with multiple agent frameworks (LangGraph, Mastra, CrewAI, AG2, etc.).

##### Detail and essential architecture
- Integration point: the 16 event types, input channels, default HTTP connector.
- Optional paths: tool calls, human-in-the-loop callbacks, state sync.
- Avoid oversimplification: the value of AG-UI lies in its middleware flexibility and multi-transport support.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Agent Backends Layer
    subgraph "Agent Backends"
        direction TB
        LG["LangGraph"]:::backend
        MA["Mastra"]:::backend
        CR["CrewAI"]:::backend
        AG2["AG2"]:::backend
    end

    %% AG-UI Specification Layer
    subgraph "AG-UI Specification" 
        direction TB
        Spec["AG-UI Spec\n(event types, input schemas)"]:::spec
        Middleware["AG-UI Middleware\n(event normalizer, transformers)"]:::middleware
        Connector["Reference HTTP Connector"]:::middleware
    end

    %% Transport Layer
    subgraph "Transport Layer"
        direction TB
        SSE["Server-Sent Events"]:::transport
        WS["WebSockets"]:::transport
        WH["Webhooks"]:::transport
    end

    %% Front-end Applications Layer
    subgraph "Front-end Applications"
        direction TB
        React["React + CopilotKit"]:::frontend
        MsgClient["Messaging Clients"]:::frontend
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Tools["Tool APIs"]:::external
        DB["Data Stores"]:::external
        HIL["Human-in-Loop UIs"]:::external
    end

    %% Event Flow
    LG -->|emits raw events| Middleware
    MA -->|emits raw events| Middleware
    CR -->|emits raw events| Middleware
    AG2 -->|emits raw events| Middleware

    Spec --> Middleware
    Middleware --> Connector
    Connector --> SSE
    Connector --> WS
    Connector --> WH

    SSE --> React
    WS --> React
    WH --> React

    SSE --> MsgClient
    WS --> MsgClient
    WH --> MsgClient

    %% Input Flow
    React -->|user actions / API calls| SSE
    React -->|user actions / API calls| WS
    React -->|user actions / API calls| WH

    MsgClient -->|user actions / API calls| SSE
    MsgClient -->|user actions / API calls| WS
    MsgClient -->|user actions / API calls| WH

    SSE -->|forwards inputs| Middleware
    WS -->|forwards inputs| Middleware
    WH -->|forwards inputs| Middleware

    Middleware -->|forwards inputs| LG
    Middleware -->|forwards inputs| MA
    Middleware -->|forwards inputs| CR
    Middleware -->|forwards inputs| AG2

    %% External Services Integration
    Middleware -->|calls / enrichment requests| Tools
    Middleware --> Tools
    Middleware -->|state / context| DB
    Middleware --> DB
    Middleware -->|human callbacks| HIL
    HIL -->|feedback events| Middleware

    %% Click Events
    click Spec "https://github.com/ag-ui-protocol/ag-ui/blob/main/README.md"

    %% Styles
    classDef backend fill:#D0E6FF,stroke:#0366D6,color:#0366D6
    classDef spec fill:none,stroke:#6A737D,stroke-dasharray:5 5,color:#6A737D
    classDef middleware fill:#DFFFE0,stroke:#28A745,color:#28A745
    classDef transport fill:#E0F7FF,stroke:#17A2B8,color:#17A2B8
    classDef frontend fill:#FFF5E6,stroke:#FF8C00,color:#FF8C00
    classDef external fill:#F2F2F2,stroke:#6C757D,color:#6C757D
```
