How i-am-bee/acp works
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.