{"id":1894,"library":"agent-client-protocol","title":"Agent Client Protocol (ACP) Python SDK","description":"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.","status":"active","version":"0.9.0","language":"en","source_language":"en","source_url":"https://github.com/agentclientprotocol/python-sdk","tags":["agent","protocol","ai","async"],"install":[{"cmd":"pip install agent-client-protocol","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Used extensively for schema validation of ACP messages and data models. The SDK specifically requires Pydantic v2.","package":"pydantic","optional":false}],"imports":[{"note":"The primary `Agent` class moved in version 0.7.0 during a major API refactor, consolidating agent-related components into `acp.agents`.","wrong":"from acp.sdk import Agent","symbol":"Agent","correct":"from acp.agents import Agent"},{"note":"The `AgentServer` class was moved as part of the 0.7.0 API refactor to `acp.agents`.","wrong":"from acp.sdk import AgentServer","symbol":"AgentServer","correct":"from acp.agents import AgentServer"},{"note":"Core protocol message types and data models are consistently located in the `acp.schemas` module.","symbol":"Message","correct":"from acp.schemas import Message"}],"quickstart":{"code":"import asyncio\nfrom acp.agents import Agent\nfrom acp.schemas import Message, MessageContents, TextResourceContents, MessageID\n\nclass SimpleEchoAgent(Agent):\n    \"\"\"\n    A simple agent that echoes back any text message it receives.\n    In a real application, this agent would be registered with an AgentServer\n    and communicate via a transport layer (e.g., stdio).\n    \"\"\"\n    # In a full setup, send_message would use the transport for communication.\n    # We override it here purely for demonstration purposes in this quickstart.\n    async def send_message(self, message: Message) -> None:\n        if message.contents and message.contents.text:\n            print(f\"Agent sending: '{message.contents.text.text}'\")\n\n    async def handle_message(self, message: Message) -> None:\n        if message.contents and message.contents.text:\n            response_text = f\"Echo from agent: {message.contents.text.text}\"\n            response_message = Message(\n                id=MessageID.new_id(),\n                contents=MessageContents(\n                    text=TextResourceContents(text=response_text)\n                ),\n                parent_id=message.id,\n            )\n            await self.send_message(response_message)\n        else:\n            print(f\"Agent received non-text message: {message.id}\")\n\nasync def run_agent_example():\n    agent = SimpleEchoAgent()\n\n    # Simulate an incoming message that a real server would pass to the agent\n    incoming_message = Message(\n        id=MessageID.new_id(),\n        contents=MessageContents(\n            text=TextResourceContents(text=\"Hello ACP!\")\n        )\n    )\n\n    print(f\"Simulating client sending: '{incoming_message.contents.text.text}'\\n\")\n    await agent.handle_message(incoming_message)\n\n    print(\"\\nAgent quickstart example finished.\")\n\nif __name__ == \"__main__\":\n    asyncio.run(run_agent_example())","lang":"python","description":"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."},"warnings":[{"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`).","message":"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.","severity":"breaking","affected_versions":"0.7.0 and later"},{"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.","message":"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.","severity":"breaking","affected_versions":"0.5.0 and later"},{"fix":"Ensure your project's Python interpreter is within the `3.10-3.14` range. Consider using `pyenv`, `conda`, or `venv` for environment management.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}