graph TB
    subgraph Your App
        A[React / Angular / Vanilla JS]
    end

    subgraph Your Server
        B[CopilotKit Runtime]
    end

    subgraph Any Agent Framework
        C[LangGraph / CrewAI / Mastra / Custom]
    end

    A -->|HTTP POST| B
    B -->|AG-UI Events| C
    C -->|AG-UI Events| B
    B -->|SSE Stream| A

sequenceDiagram
    participant User
    participant App as Your App
    participant Core as CopilotKitCore
    participant Runtime as CopilotRuntime
    participant Agent as AI Agent

    Note over App: Setup (on mount)
    App->>Core: Provider creates Core
    Core->>Runtime: GET /info (fetch agent list)
    Runtime-->>Core: [{ name, description }]
    App->>Core: Hooks register tools + context

    Note over User: User sends message
    User->>App: Types message, hits send
    App->>Core: Gets agent instance
    Core->>Runtime: POST /agent/{id}/run
    Runtime->>Agent: AgentRunner.run()

    Note over Agent: Events stream back
    Agent-->>Runtime: TEXT_MESSAGE_START
    Agent-->>Runtime: TEXT_MESSAGE_CONTENT (streaming)
    Agent-->>Runtime: TEXT_MESSAGE_END
    Runtime-->>Core: SSE event stream
    Core-->>App: Subscribers fire, UI re-renders
    App-->>User: Chat shows streaming response

    Note over Agent: Tool call (optional)
    Agent-->>Runtime: TOOL_CALL_START + ARGS
    Runtime-->>Core: SSE events
    Core->>Core: Execute frontend tool
    Core-->>Runtime: TOOL_CALL_RESULT
    Runtime->>Agent: Agent continues
    Agent-->>Runtime: RUN_FINISHED

graph BT
    subgraph AG-UI Protocol
        core["@ag-ui/core
<i>Types + Event schemas</i>"]
        client["@ag-ui/client
<i>AbstractAgent, HttpAgent, Middleware</i>"]
        encoder["@ag-ui/encoder
<i>SSE / Binary / Protobuf encoding</i>"]
        client --> core
        encoder --> core
    end

    subgraph CopilotKit Packages
        shared["@copilotkit/shared
<i>Utils, types, constants</i>"]
        core["@copilotkit/core
<i>CopilotKitCore orchestrator</i>"]
        reactcore["@copilotkit/react-core
<i>Provider + hooks</i>"]
        reactui["@copilotkit/react-ui
<i>Chat, Popup, Sidebar</i>"]
        reacttextarea["@copilotkit/react-textarea
<i>AI text editing</i>"]
        gql["@copilotkit/runtime-client-gql
<i>urql GraphQL client</i>"]
        runtime["@copilotkit/runtime
<i>Express/Hono server + AgentRunner + Built-in agent</i>"]

        core --> shared
        reactcore --> core
        reactcore --> gql
        reactui --> reactcore
        reacttextarea --> reactcore
        runtime --> shared
        reactcore -.-> client
        gql --> shared
    end

graph LR
    subgraph Lifecycle
        RS[RUN_STARTED] --> SS[STEP_STARTED]
        SF[STEP_FINISHED] --> RF[RUN_FINISHED]
    end

    subgraph Text
        TMS[TEXT_MESSAGE_START] --> TMC[TEXT_MESSAGE_CONTENT]
        TMC --> TME[TEXT_MESSAGE_END]
    end

    subgraph Tools
        TCS[TOOL_CALL_START] --> TCA[TOOL_CALL_ARGS]
        TCA --> TCE[TOOL_CALL_END]
        TCE --> TCR[TOOL_CALL_RESULT]
    end

    subgraph State
        SNP[STATE_SNAPSHOT]
        SD[STATE_DELTA]
    end

    SS --> TMS
    TME --> TCS
    TCR --> SF

cpk/
├── ag-ui/                          # AG-UI Protocol (open standard)
│   ├── sdks/typescript/packages/
│   │   ├── core/                   # @ag-ui/core — types + events
│   │   ├── client/                 # @ag-ui/client — AbstractAgent, HttpAgent
│   │   ├── encoder/                # @ag-ui/encoder — SSE/binary encoding
│   │   └── proto/                  # @ag-ui/proto — protobuf
│   └── integrations/               # 13+ framework adapters
│       ├── langgraph/
│       ├── crewai/
│       ├── mastra/
│       └── ...
│
└── CopilotKit/                     # CopilotKit Product
    └── packages/                   # All packages flat under @copilotkit/ scope
        ├── shared/                 # @copilotkit/shared — utils, types, constants
        ├── core/                   # @copilotkit/core — CopilotKitCore orchestrator
        ├── react-core/             # @copilotkit/react-core — provider + hooks
        ├── react-ui/               # @copilotkit/react-ui — chat components
        ├── react-textarea/         # @copilotkit/react-textarea — AI text editing
        ├── runtime/                # @copilotkit/runtime — Express/Hono server + AgentRunner + Built-in agent
        ├── runtime-client-gql/     # @copilotkit/runtime-client-gql — urql GraphQL client
        ├── angular/                # @copilotkit/angular — Angular integration
        ├── voice/                  # @copilotkit/voice — voice support
        ├── web-inspector/          # @copilotkit/web-inspector — debug console
        ├── sqlite-runner/          # @copilotkit/sqlite-runner — persistent AgentRunner
        └── sdk-js/                 # @copilotkit/sdk-js — LangGraph/LangChain helpers