Agent Client Protocol (ACP) Python SDK

0.9.0 · active · verified Thu Apr 09

The `agent-client-protocol` is a Python implementation of the Agent Client Protocol (ACP) by Zed Industries, designed to facilitate communication between AI agents and clients. It provides classes for building agents, clients, and handling protocol messages with schema validation. Currently at version 0.9.0, the library releases updates driven by upstream ACP schema changes and SDK improvements, typically every few months.

Warnings

breaking Version 0.7.0 introduced a major API refactor, moving core classes like `Agent` and `AgentServer` to `acp.agents` and standardizing method names to `snake_case`. Existing code using `camelCase` methods or older import paths will break.
Fix: Update import paths (e.g., `from acp.sdk import Agent` to `from acp.agents import Agent`) and refactor method calls to use `snake_case` (e.g., `handleMessage` to `handle_message`).
breaking In version 0.5.0, helper functions `acp.helpers.embedded_text_resource` and `acp.helpers.embedded_blob_resource` changed their return type to directly yield `TextResourceContents` / `BlobResourceContents`. If you were implicitly relying on an outer `ResourceBlock` wrapper, you now need to explicitly use `helpers.resource_block(...)` when emitting embedded resources.
Fix: If previously `my_resource = embedded_text_resource(...)`, now ensure it's `my_resource = resource_block(embedded_text_resource(...))` when embedding resources within a message.
gotcha The library has a strict Python version requirement: `>=3.10, <3.15`. Using Python 3.9 or older, or 3.15 or newer, will result in installation or runtime errors due to specific dependencies and tested environments.
Fix: Ensure your project's Python interpreter is within the `3.10-3.14` range. Consider using `pyenv`, `conda`, or `venv` for environment management.
gotcha The SDK closely tracks the upstream Agent Client Protocol schema. Minor SDK version bumps (e.g., 0.8.0, 0.9.0) often include `feat(schema): upgrade ACP`, which can introduce new types or modify existing ones. While typically backward-compatible, be aware of potential subtle API shifts in message structures.
Fix: Review changelogs for 'upgrade ACP' entries and consult the official ACP specification if unexpected behavior occurs after an update, especially when interacting with agents or clients on different protocol versions.

Install

pip install agent-client-protocol Install stable version

Imports

Agent
```
from acp.agents import Agent
```
The primary `Agent` class moved in version 0.7.0 during a major API refactor, consolidating agent-related components into `acp.agents`.
AgentServer
```
from acp.agents import AgentServer
```
The `AgentServer` class was moved as part of the 0.7.0 API refactor to `acp.agents`.
Message
```
from acp.schemas import Message
```
Core protocol message types and data models are consistently located in the `acp.schemas` module.

Quickstart

This quickstart demonstrates how to define a basic `Agent` that responds to text messages. In a production environment, this agent would be instantiated and registered with an `AgentServer` which handles the underlying communication transport (e.g., standard I/O, sockets) to an ACP client. The `send_message` method is overridden here for demonstration purposes; normally it would leverage the server's transport.

import asyncio
from acp.agents import Agent
from acp.schemas import Message, MessageContents, TextResourceContents, MessageID

class SimpleEchoAgent(Agent):
    """
    A simple agent that echoes back any text message it receives.
    In a real application, this agent would be registered with an AgentServer
    and communicate via a transport layer (e.g., stdio).
    """
    # In a full setup, send_message would use the transport for communication.
    # We override it here purely for demonstration purposes in this quickstart.
    async def send_message(self, message: Message) -> None:
        if message.contents and message.contents.text:
            print(f"Agent sending: '{message.contents.text.text}'")

    async def handle_message(self, message: Message) -> None:
        if message.contents and message.contents.text:
            response_text = f"Echo from agent: {message.contents.text.text}"
            response_message = Message(
                id=MessageID.new_id(),
                contents=MessageContents(
                    text=TextResourceContents(text=response_text)
                ),
                parent_id=message.id,
            )
            await self.send_message(response_message)
        else:
            print(f"Agent received non-text message: {message.id}")

async def run_agent_example():
    agent = SimpleEchoAgent()

    # Simulate an incoming message that a real server would pass to the agent
    incoming_message = Message(
        id=MessageID.new_id(),
        contents=MessageContents(
            text=TextResourceContents(text="Hello ACP!")
        )
    )

    print(f"Simulating client sending: '{incoming_message.contents.text.text}'\n")
    await agent.handle_message(incoming_message)

    print("\nAgent quickstart example finished.")

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

view raw JSON →