Key Features

  • REST-First Architecture: Plain HTTPS + OpenAPI 3.1 spec with no custom transport - works with curl, Postman, or any HTTP client.
  • Agent Discovery Manifest: Static /.well-known/agent.json with name, version, capabilities, auth, and endpoints - works offline in containers.
  • Multimodal Message Parts: Message → MessagePart array supporting text/plain, image/png, application/json, and custom MIME types out-of-box.
  • Flexible Session Patterns: Stateless one-shot POST /runs or stateful sessions with sessionId and Redis/PostgreSQL persistence.
  • Streaming & Async Support: SSE streaming with status, delta, and artifact events; async by default with DELETE /runs/{runId} cancellation.
  • Enterprise Security: TLS 1.3 mandatory, API key/OAuth2/mTLS/JWT auth, RBAC in token claims, Linux Foundation governance.

Use Cases

  • RAG pipelines - Retrieval agent → generation agent via ACP streaming with swappable LLMs
  • Edge/IoT mesh - Lightweight ARM device agents with mDNS + .well-known discovery
  • Enterprise B2B - Finance agent in Bank-A calls compliance agent in Bank-B via scoped JWT + mTLS
  • Agent marketplace - BeeAI Hub publishing, discovery, rating, and forking of agent manifests
  • Router/composition patterns - Downstream ACP agent orchestration with artifact merging

Pros & Cons

Advantages

  • Zero-vendor REST spec compatible with any HTTP stack
  • Multimodal, async-first design with offline discovery capabilities
  • Native interoperability with MCP, A2A, and ANP protocols
  • Type-safe clients via SDKs + OpenAPI code generation
  • Linux Foundation governance with public bi-weekly SIG calls

Disadvantages

  • Orchestration logic (retries, sagas) left to developer implementation
  • Initial manifest and authentication setup requires boilerplate work
  • Spec still evolving with potential breaking changes <1% per minor version
  • Security configuration (certs, tokens) requires rigorous setup

Architecture & Core Concepts

  • Message Model: Core Message → MessagePart[] array with contentType, content, contentUrl, and metadata fields
  • Discovery Schema: Static /.well-known/agent.json with name, version, capabilities, auth, and endpoints configuration
  • Session Management: Stateless POST /runs or stateful sessions with sessionId and backend persistence options
  • Streaming Protocol: Accept: text/event-stream for SSE with status, delta, artifact events and DELETE cancellation
  • Security Layer: TLS 1.3 transport, API key/OAuth2/mTLS/JWT auth, RBAC claims, Linux Foundation governance

Code Examples

Minimal Echo Agent

from acp_sdk.server import Server, Message, MessagePart

srv = Server()

@srv.agent()
async def echo(messages: list[Message]):
    last = messages[-1].parts[0].content
    return [Message(parts=[MessagePart(content=f"ECHO: {last}")])]

if __name__ == "__main__":
    srv.run(host="0.0.0.0", port=8000)

Agent Invocation

curl -X POST http://localhost:8000/runs \
  -H "Content-Type: application/json" \
  -d '{"agent_name":"echo","input":[{"parts":[{"content":"Hi"}]}]}'

Agent Discovery Manifest

// https://host/.well-known/agent.json
{
  "name": "data-processor",
  "version": "1.0.0",
  "capabilities": ["text-analysis", "data-transformation"],
  "auth": "oauth2",
  "endpoints": {
    "runs": "/runs",
    "status": "/runs/{runId}/status"
  }
}

Multimodal Message Structure

{
  "agent_name": "multimodal-processor",
  "input": [
    {
      "parts": [
        {
          "contentType": "text/plain",
          "content": "Analyze this image",
          "metadata": {}
        },
        {
          "contentType": "image/png",
          "contentUrl": "https://example.com/image.png",
          "metadata": {"source": "user_upload"}
        }
      ]
    }
  ]
}