# i-am-bee/acp architecture

> Architecture diagram of the GitHub repository i-am-bee/acp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/i-am-bee/acp
- Repository: https://github.com/i-am-bee/acp

## Overview

##### Project type and purpose
- This is an open-source SDK and reference server for the “Agent Communication Protocol” (ACP).
- It provides:
- A Python server implementation (acp_sdk/server) exposing a REST API (OpenAPI spec) to host AI “agents.”
- Client libraries in Python (acp_sdk/client) and TypeScript (typescript/src/client) to discover agents, start runs, stream results, and handle awaits.
- Data models shared between client and server (acp_sdk/models and typescript/src/models).
- Pluggable state stores (in-memory, PostgreSQL, Redis).
- Example agents/clients and comprehensive documentation.

##### File structure
- Top-level: docs/, examples/, python/, typescript/, package.json, pnpm-workspace.
- python/: Python SDK with subpackages: client/, server/, models/, instrumentation/, shared/, store implementations.
- typescript/: TS SDK client and models.
- docs/: static site content, OpenAPI spec, MDX guides.
- examples/: end-to-end sample agents and clients in Python and TS.
- Configuration: uv CLI integration via uv.lock, mise.toml; GitHub workflows for CI/CD; Dockerignore.

##### README
- Describes ACP goals: inter-agent messaging, discovery, long-running tasks, streaming, awaits.
- Lists components: Documentation site, OpenAPI spec, Python and TS SDKs, Examples.
- Shows quickstart: uv init, uv add acp-sdk, define @server.agent() in Python, run Server(), call endpoints.

##### Main components
a. Protocol / API layer
- OpenAPI Specification (docs/spec/openapi.yaml)
- REST endpoints: /agents, /runs, /sessions, /events (SSE)
b. Python SDK Server
- Server entrypoint (acp_sdk/server/server.py)
- Agent registry & discovery (server.app, server.context)
- Run lifecycle & executor (server.executor, server.agent)
- Await & resume mechanism (RunYield / RunYieldResume)
- Telemetry & logging (server.telemetry, server.logging)
- Store adapters (memory_store, postgresql_store, redis_store)
c. Python Client Library
- Client class (acp_sdk/client/client.py)
- Models & types (acp_sdk/models)
- Utils (client.utils, models.schemas)
d. TypeScript SDK
- Client (src/client/*)
- SSE streaming adapter (client.sse)
- Shared models (src/models/*)
e. Examples & CLI
- uv CLI tool for bootstrapping & running agents.
- Example agents & clients demonstrating flows.
f. External systems
- PostgreSQL / Redis (optional back-end stores)
- HTTP clients (curl, external applications)

##### Relationships and interactions
- Clients (Python/TS/Examples) → HTTP(S) requests → ACP Server
- Server → Store Adapter → Data Store (Memory / Postgres / Redis)
- Server → Telemetry & Logging → External logs/metrics sinks (optional)
- Clients may open an SSE stream to /runs/{run_id}/events for live output.
- Server uses models for request/response validation (Pydantic in Python, Zod/TS types in TypeScript).
- Documentation site (docs/) and OpenAPI spec drive code generation for clients and examples.

##### Important architectural patterns
- Hexagonal (Ports & Adapters): server core is independent of store, logging, telemetry back-ends.
- Plugin model for agents: functions decorated with @server.agent() can be registered at runtime.
- Streaming via SSE: enables push of message parts.
- Shared data models ensure cross-language compatibility.

- Component labels (e.g., “Python SDK Server”, “TypeScript Client Library”)
- Protocol & Specs
- Server Core
- Adapters (Store, Telemetry)
- Clients & Examples
- External Systems (DBs, Logs)

- How ACP’s OpenAPI specification sits at the heart of a hexagonal architecture.
- The flow of agent discovery, run creation, streaming of messages, and state persistence.
- The cross-language, multi-SDK nature of the project.
- The pluggable back-ends and extensibility points for custom agents, stores, and telemetry.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Protocol & Specs
    subgraph "Protocol & Specs"
        OpenAPI["OpenAPI Spec"]:::docs
    end

    %% Server Core
    subgraph "Server Core"
        ServerEntry["Server Entrypoint"]:::server
        App["App (agent registry)"]:::server
        Context["Context (registry)"]:::server
        AgentDef["@server.agent decorator"]:::server
        Executor["Run Executor"]:::server
        Telemetry["Telemetry"]:::server
        Logging["Logging"]:::server
    end

    %% Store Adapters
    subgraph "Store Adapters"
        Memory["In-Memory Store"]:::datastore
        PostgresStore["PostgreSQL Store"]:::datastore
        RedisStore["Redis Store"]:::datastore
        StoreInterface["Store Interface"]:::datastore
        StoreUtils["Store Utils"]:::datastore
    end

    %% Shared Models (Python)
    subgraph "Shared Models (Python)"
        PMModels["models.py"]:::models
        PMSchemas["schemas.py"]:::models
        PMErrors["errors.py"]:::models
        PMTypes["types.py"]:::models
    end

    %% Python Client Library
    subgraph "Python Client Library"
        PyClient["Client Core"]:::client
        PyTypes["Types"]:::client
        PyUtils["Utils"]:::client
    end

    %% TypeScript SDK
    subgraph "TypeScript SDK"
        TSClientCore["client.ts"]:::client
        TSIndex["index.ts"]:::client
        TSSE["sse.ts"]:::client
    end

    %% Shared Models (TS)
    subgraph "Shared Models (TS)"
        TSMModels["models.ts"]:::models
        TSMSchemas["schemas.ts"]:::models
        TSMErrors["errors.ts"]:::models
        TSMPlatform["platform.ts"]:::models
        TSMUtils["utils.ts"]:::models
        TSMIndex["index.ts"]:::models
    end

    %% Clients & Examples
    subgraph "Clients & Examples"
        PyExamples["Python Examples"]:::client
        TSExamples["TS Examples"]:::client
        CLI["uv CLI Tool"]:::client
    end

    %% Documentation
    subgraph "Documentation"
        DocsSite["Docs Site & Guides"]:::docs
    end

    %% External Systems
    subgraph "External Systems"
        PostgresDB["PostgreSQL DB"]:::external
        RedisDB["Redis"]:::external
        Logs["Logs/Metrics Sink"]:::external
    end

    %% Connections
    DocsSite --> OpenAPI
    OpenAPI -->|drives| ServerEntry
    ServerEntry -->|hosts endpoints| App
    App --> Context
    Context --> AgentDef
    AgentDef --> Executor
    Executor -->|calls| App
    ServerEntry -->|exposes| Executor
    ServerEntry -->|pipes to| Telemetry
    ServerEntry -->|pipes to| Logging

    ServerEntry -->|uses| Memory
    ServerEntry -->|uses| PostgresStore
    ServerEntry -->|uses| RedisStore
    ServerEntry -->|interfaces| StoreInterface
    StoreInterface --> StoreUtils

    Memory --> PostgresDB
    PostgresStore --> PostgresDB
    RedisStore --> RedisDB

    PyClient -->|HTTP requests| ServerEntry
    TSClientCore -->|HTTP requests| ServerEntry
    PyClient -->|uses models| PMModels
    PyClient -->|uses schemas| PMSchemas
    PyClient -->|uses errors| PMErrors
    PyClient -->|uses types| PMTypes
    PyTypes --> PyClient
    PyUtils --> PyClient

    TSClientCore -->|uses SSE| TSSE
    TSClientCore -->|uses models| TSMModels
    TSClientCore -->|uses schemas| TSMSchemas
    TSClientCore -->|uses errors| TSMErrors
    TSClientCore -->|uses platform| TSMPlatform
    TSClientCore -->|uses utils| TSMUtils
    TSClientCore -->|uses index| TSMIndex

    PyExamples --> PyClient
    TSExamples --> TSClientCore
    CLI --> ServerEntry

    ServerEntry -->|logs to| Logs

    %% SSE Streams
    PyClient -->|"SSE /runs/{id}/events"| ServerEntry
    TSClientCore -->|"SSE /runs/{id}/events"| ServerEntry

    %% Click Events
    click OpenAPI "https://github.com/i-am-bee/acp/blob/main/docs/spec/openapi.yaml"
    click ServerEntry "https://github.com/i-am-bee/acp/blob/main/python/src/acp_sdk/server/server.py"
    click App "https://github.com/i-am-bee/acp/blob/main/python/src/acp_sdk/server/app.py"
    click Context "https://github.com/i-am-bee/acp/blob/main/python/src/acp_sdk/server/context.py"
    click AgentDef "https://github.com/i-am-bee/acp/blob/main/python/src/acp_sdk/server/agent.py"
    click Executor "https://github.com/i-am-bee/acp/blob/main/python/src/acp_sdk/server/executor.py"
    click Telemetry "https://github.com/i-am-bee/acp/blob/main/python/src/acp_sdk/server/telemetry.py"
    click Logging "https://github.com/i-am-bee/acp/blob/main/python/src/acp_sdk/server/logging.py"
    click Memory "https://github.com/i-am-bee/acp/blob/main/python/src/acp_sdk/server/store/memory_store.py"
    click PostgresStore "https://github.com/i-am-bee/acp/blob/main/python/src/acp_sdk/server/store/postgresql_store.py"
    click RedisStore "https://github.com/i-am-bee/acp/blob/main/python/src/acp_sdk/server/store/redis_store.py"
    click StoreInterface "https://github.com/i-am-bee/acp/blob/main/python/src/acp_sdk/server/store/store.py"
    click StoreUtils "https://github.com/i-am-bee/acp/blob/main/python/src/acp_sdk/server/store/utils.py"
    click PyClient "https://github.com/i-am-bee/acp/blob/main/python/src/acp_sdk/client/client.py"
    click PyTypes "https://github.com/i-am-bee/acp/blob/main/python/src/acp_sdk/client/types.py"
    click PyUtils "https://github.com/i-am-bee/acp/blob/main/python/src/acp_sdk/client/utils.py"
    click PMModels "https://github.com/i-am-bee/acp/blob/main/python/src/acp_sdk/models/models.py"
    click PMSchemas "https://github.com/i-am-bee/acp/blob/main/python/src/acp_sdk/models/schemas.py"
    click PMErrors "https://github.com/i-am-bee/acp/blob/main/python/src/acp_sdk/models/errors.py"
    click PMTypes "https://github.com/i-am-bee/acp/blob/main/python/src/acp_sdk/models/types.py"
    click TSClientCore "https://github.com/i-am-bee/acp/blob/main/typescript/src/client/client.ts"
    click TSIndex "https://github.com/i-am-bee/acp/blob/main/typescript/src/client/index.ts"
    click TSSE "https://github.com/i-am-bee/acp/blob/main/typescript/src/client/sse.ts"
    click TSMModels "https://github.com/i-am-bee/acp/blob/main/typescript/src/models/models.ts"
    click TSMSchemas "https://github.com/i-am-bee/acp/blob/main/typescript/src/models/schemas.ts"
    click TSMErrors "https://github.com/i-am-bee/acp/blob/main/typescript/src/models/errors.ts"
    click TSMPlatform "https://github.com/i-am-bee/acp/blob/main/typescript/src/models/platform.ts"
    click TSMUtils "https://github.com/i-am-bee/acp/blob/main/typescript/src/models/utils.ts"
    click TSMIndex "https://github.com/i-am-bee/acp/blob/main/typescript/src/models/index.ts"
    click PyExamples "https://github.com/i-am-bee/acp/tree/main/examples/python"
    click TSExamples "https://github.com/i-am-bee/acp/tree/main/examples/typescript/basic"
    click DocsSite "https://github.com/i-am-bee/acp/tree/main/docs/"

    %% Styles
    classDef server fill:#cce5ff,stroke:#339,stroke-width:1px
    classDef client fill:#d4edda,stroke:#396,stroke-width:1px
    classDef datastore fill:#fff3cd,stroke:#cc8,stroke-width:1px
    classDef external fill:#f0f0f0,stroke:#888,stroke-width:1px
    classDef docs fill:#e2e3e5,stroke:#666,stroke-width:1px
    classDef models fill:#f8f0fc,stroke:#a55,stroke-width:1px
```
