Agent Communication Protocol (ACP)

Framework-agnostic agent communication. Unified by design.

The Agent Communication Protocol (ACP) is an open standard with open governance for agent interoperability. It defines a standardized RESTful API supporting synchronous, asynchronous, and streaming interactions. In ACP, agents are services that exchange multimodal messages, with the protocol remaining agnostic to their internal implementations and requiring only minimal specifications for compatibility.

ACP Toolkit

• 📚 Documentation. Comprehensive guides and reference material for implementing and using ACP.
• 📝 OpenAPI Specification. Defines the REST API endpoints, request/response formats, and data models to form the ACP protocol.
• 🛠️ Python SDK. Contains a server implementation, client libraries, and model definitions to easily create and interact with ACP agents.
• 💻 Examples. Ready-to-run code samples demonstrating how to build agents and clients that communicate using ACP.

Core Concepts

Concept	Description
Agent Detail	A model describing an agent’s capabilities—its name, description, and optional metadata and status—for discovery and composition without exposing implementation details.
Run	A single agent execution with specific inputs. Supports sync or streaming, with intermediate and final output.
Message	The core structure for communication, consisting of a sequence of ordered components that form a complete, structured, and multi-modal exchange of information.
MessagePart	The individual content units within a Message, which can include types like text, image, or JSON. Together, they combine to create structured, multimodal communication.
Await	Let agents pause to request information from the client and resume, enabling interactive exchanges where the agent can wait for external input (data, actions, etc.) before continuing.

---

Quickstart

Note

This guide uses uv. See the uv primer for more details.

1. Initialize your project

uv init --python '>=3.11' my_acp_project
cd my_acp_project

2. Add the ACP SDK

uv add acp-sdk

3. Create an agent

Let’s create a simple "echo agent" that returns any message it receives.
Create an agent.py file in your project directory with the following code:

# agent.py
import asyncio
from collections.abc import AsyncGenerator

from acp_sdk.models import Message
from acp_sdk.server import Context, RunYield, RunYieldResume, Server

server = Server()


@server.agent()
async def echo(
    input: list[Message], context: Context
) -> AsyncGenerator[RunYield, RunYieldResume]:
    """Echoes everything"""
    for message in input:
        await asyncio.sleep(0.5)
        yield {"thought": "I should echo everything"}
        await asyncio.sleep(0.5)
        yield message


server.run()

4. Start the ACP server

uv run agent.py

Your server should now be running at http://localhost:8000.

5. Verify your agent is available

In another terminal, run the following curl command:

curl http://localhost:8000/agents

You should see a JSON response containing your echo agent, confirming it's available:

{
  "agents": [
    { "name": "echo", "description": "Echoes everything", "metadata": {} }
  ]
}

6. Run the agent via HTTP

Run the following curl command:

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

Your response should include the echoed message “Howdy!”:

{
  "run_id": "44e480d6-9a3e-4e35-8a03-faa759e19588",
  "agent_name": "echo",
  "session_id": "b30b1946-6010-4974-bd35-89a2bb0ce844",
  "status": "completed",
  "await_request": null,
  "output": [
    {
      "parts": [
        {
          "name": null,
          "content_type": "text/plain",
          "content": "Howdy!",
          "content_encoding": "plain",
          "content_url": null
        }
      ]
    }
  ],
  "error": null
}

Your response should include the echoed message "Howdy!".

7. Build an ACP client

Here’s a simple ACP client to interact with your echo agent.
Create a client.py file in your project directory with the following code:

# client.py
import asyncio

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


async def example() -> None:
    async with Client(base_url="http://localhost:8000") as client:
        run = await client.run_sync(
            agent="echo",
            input=[
                Message(
                    parts=[MessagePart(content="Howdy to echo from client!!", content_type="text/plain")]
                )
            ],
        )
        print(run.output)


if __name__ == "__main__":
    asyncio.run(example())

8. Run the ACP client

uv run client.py

You should see the echoed response printed to your console. 🎉

---

Contributors

We are grateful for the efforts of our initial contributors, who have played a vital role in getting ACP of the ground. As we continue to grow and evolve, we invite others to join our vibrant community and contribute to our project’s ongoing development. For more information, please visit the Contribute page of our documentation.

Maintainers

For information about maintainers, see MAINTAINERS.md.

---

Developed by contributors to the BeeAI project, this initiative is part of the Linux Foundation AI & Data program. Its development follows open, collaborative, and community-driven practices.