Agent Client Protocol (ACP) Python SDK
raw JSON → 0.9.0 verified Fri Apr 24 auth: no python
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.
pip install agent-client-protocol Common errors
error ModuleNotFoundError: No module named 'agent_client_protocol' ↓
cause The 'agent-client-protocol' package is not installed or the module name is incorrect.
fix
Ensure the package is installed using 'pip install agent-client-protocol' and import it as 'import acp'.
error ImportError: cannot import name 'AgentClient' from 'agent_client_protocol' ↓
cause The 'AgentClient' class does not exist in the 'agent_client_protocol' module.
fix
Check the library's documentation for the correct class name and import statement.
error AttributeError: module 'acp' has no attribute 'initialize' ↓
cause The 'initialize' function does not exist in the 'acp' module.
fix
Refer to the library's documentation for the correct function name and usage.
error TypeError: 'NoneType' object is not iterable ↓
cause A function is returning 'None' instead of an iterable object.
fix
Ensure that the function returns a valid iterable and handle cases where it might return 'None'.
error ValueError: Invalid ACP schema version ↓
cause The provided ACP schema version is not recognized or supported.
fix
Verify that the schema version is correct and supported by the library.
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 compatibility last tested: 2026-04-24
runtime status import time mem disk
3.10-alpine — — —
3.10-slim — — —
3.11-alpine — — —
3.11-slim — — —
3.12-alpine — — —
3.12-slim — — —
3.13-alpine — — —
3.13-slim — — —
3.9-alpine — — —
3.9-slim — — —
Imports
- Agent wrong
from acp.sdk import Agentcorrectfrom acp.agents import Agent - AgentServer wrong
from acp.sdk import AgentServercorrectfrom acp.agents import AgentServer - Message
from acp.schemas import Message
Quickstart last tested: 2026-04-25
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())