Tyler-R-Kendrick/acp

ACP — Agent Communication Protocol

Overview

ACP is an open protocol (originally from IBM / BeeAI, now contributed to the Linux Foundation alongside A2A) for communication between AI agents, applications, and humans. It uses plain REST endpoints — no JSON-RPC, no specialized transport — making it usable with standard HTTP tools like curl, Postman, or any HTTP client.

Status: The standalone ACP repository is archived. ACP's design has been merged into the A2A project under the Linux Foundation. New projects should evaluate A2A, but existing ACP deployments and the SDK remain functional.

Core Concepts

Agent Manifest

Every ACP agent exposes a manifest describing its capabilities — without revealing implementation details:

{
  "name": "research-agent",
  "description": "Finds and summarizes information on any topic",
  "metadata": {
    "capabilities": ["streaming", "sessions"]
  }
}

Messages and Parts

Agents exchange Messages composed of Parts. Each part carries a MIME type, enabling multimodal payloads (text, images, audio, files) without protocol changes:

{
  "role": "user",
  "parts": [
    {
      "content": "Summarize this document",
      "content_type": "text/plain",
      "content_encoding": "plain"
    },
    {
      "content": "<base64-data>",
      "content_type": "application/pdf",
      "content_encoding": "base64",
      "name": "report.pdf"
    }
  ]
}

Part Metadata

Parts can carry structured metadata for observability and attribution:

• TrajectoryMetadata — exposes reasoning steps and tool calls
• CitationMetadata — attributes content to source documents

REST API

Endpoints

| Method | Path | Description | |--------|------|-------------| | GET | /agents | List available agents with their manifests | | POST | /runs | Execute an agent (sync, async, or streaming) |

Run Lifecycle

pending → running → [awaiting] → completed / error

| State | Meaning | |-------|---------| | pending | Run queued, not yet started | | running | Agent is executing | | awaiting | Agent paused, requesting external input | | completed | Finished successfully | | error | Execution failed |

Communication Modes

ACP supports three response modes on a single endpoint:

• Synchronous — block until the run completes
• Asynchronous — return immediately, poll for status
• Streaming — SSE stream of incremental results

Python Server Example

from acp_sdk.server import Server, Context
from acp_sdk.models import Message, MessagePart

server = Server()

@server.agent()
async def summarizer(input: list[Message], context: Context):
    """Summarizes the provided text."""
    for message in input:
        text = message.parts[0].content
        yield {"thought": "Analyzing content..."}
        yield Message(
            role="agent/summarizer",
            parts=[MessagePart(
                content=f"Summary of: {text[:50]}...",
                content_type="text/plain"
            )]
        )

server.run()

Python Client Example

from acp_sdk.client import Client
from acp_sdk.models import Message, MessagePart

async with Client(base_url="http://localhost:8000") as client:
    # Discover agents
    agents = await client.agents()

    # Synchronous run
    run = await client.run_sync(
        agent="summarizer",
        input=[Message(
            role="user",
            parts=[MessagePart(
                content="Summarize this article...",
                content_type="text/plain"
            )]
        )]
    )
    print(run.output)

Session Management

Sessions enable stateful, multi-turn conversations. The SDK manages session state automatically, giving agents access to complete interaction history:

async with Client(base_url="http://localhost:8000") as client:
    # First turn — creates a session
    run1 = await client.run_sync(
        agent="assistant",
        input=[Message(role="user", parts=[
            MessagePart(content="My name is Alice", content_type="text/plain")
        ])]
    )

    # Second turn — continues the session
    run2 = await client.run_sync(
        agent="assistant",
        session=run1.session_id,
        input=[Message(role="user", parts=[
            MessagePart(content="What is my name?", content_type="text/plain")
        ])]
    )

High Availability

For production deployments, ACP supports centralized storage backends:

• Redis — fast, in-memory session and run state
• PostgreSQL — durable, persistent storage
• Distributed sessions — URI-based resource sharing across server instances

ACP vs A2A vs MCP

| Aspect | ACP | A2A | MCP | |--------|-----|-----|-----| | Transport | REST (HTTP) | HTTP + JSON-RPC + SSE | stdio, HTTP + SSE | | Discovery | GET /agents | Agent Cards (.well-known/agent.json) | Capabilities negotiation | | Interaction | Runs (sync/async/stream) | Tasks (long-running) | Request-response (tool calls) | | Focus | Agent-to-agent + human-to-agent | Agent-to-agent delegation | Agent-to-tool integration | | Multimodal | MIME-typed parts | Typed parts | Tool arguments | | Sessions | Built-in stateful sessions | Task context | Conversation context |

SDKs

| Language | Server | Client | |----------|--------|--------| | Python | acp-sdk | acp-sdk | | TypeScript | — | acp-sdk |

# Python
pip install acp-sdk

# TypeScript
npm install acp-sdk

Best Practices

• Use GET /agents for runtime discovery so clients can dynamically route to the right agent without hardcoding endpoints.
• Use sessions for multi-turn workflows — the SDK handles session continuity automatically.
• Use streaming mode for long-running agents to give callers incremental progress.
• Attach TrajectoryMetadata to parts when exposing reasoning steps for observability.
• Use Redis or PostgreSQL backends in production for high availability and fault tolerance.
• Since ACP has merged into A2A, evaluate A2A for greenfield projects — but ACP SDKs remain functional for existing deployments.