{"id":28024475,"url":"https://github.com/i-am-bee/acp","last_synced_at":"2025-05-11T02:13:04.337Z","repository":{"id":286860064,"uuid":"959719880","full_name":"i-am-bee/acp","owner":"i-am-bee","description":"Agent Communication Protocol","archived":false,"fork":false,"pushed_at":"2025-05-09T12:49:15.000Z","size":2861,"stargazers_count":181,"open_issues_count":24,"forks_count":24,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-05-11T02:12:54.146Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://agentcommunicationprotocol.dev","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/i-am-bee.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-03T08:40:43.000Z","updated_at":"2025-05-10T21:15:25.000Z","dependencies_parsed_at":null,"dependency_job_id":"13f2729f-74c8-4269-9b02-eaa91cd555f9","html_url":"https://github.com/i-am-bee/acp","commit_stats":null,"previous_names":["i-am-bee/acp"],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/i-am-bee%2Facp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/i-am-bee%2Facp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/i-am-bee%2Facp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/i-am-bee%2Facp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/i-am-bee","download_url":"https://codeload.github.com/i-am-bee/acp/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253505669,"owners_count":21918943,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-11T02:13:03.839Z","updated_at":"2025-05-11T02:13:04.302Z","avatar_url":"https://github.com/i-am-bee.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n  Agent Communication Protocol (ACP)\n\u003c/h1\u003e\n\u003ch3 align=\"center\"\u003eFramework-agnostic agent communication. Unified by design.\u003c/h3\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n[![Apache 2.0](https://img.shields.io/badge/Apache%202.0-License-EA7826?style=flat-square\u0026logo=apache\u0026logoColor=white)](https://github.com/i-am-bee/beeai-framework?tab=Apache-2.0-1-ov-file#readme)\n[![Follow on Bluesky](https://img.shields.io/badge/Follow%20on%20Bluesky-0285FF?style=flat-square\u0026logo=bluesky\u0026logoColor=white)](https://bsky.app/profile/beeaiagents.bsky.social)\n[![Join our Discord](https://img.shields.io/badge/Join%20our%20Discord-7289DA?style=flat-square\u0026logo=discord\u0026logoColor=white)](https://discord.gg/NradeA6ZNF)\n[![LF AI \u0026 Data](https://img.shields.io/badge/LF%20AI%20%26%20Data-0072C6?style=flat-square\u0026logo=linuxfoundation\u0026logoColor=white)](https://lfaidata.foundation/projects/)\n\n\u003c/div\u003e\n\n\u003cbr\u003e\n\nThe **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.\n\n## ACP Toolkit\n\n- **📚 [Documentation](https://agentcommunicationprotocol.dev)**. Comprehensive guides and reference material for implementing and using ACP.\n- **📝 [OpenAPI Specification](https://github.com/i-am-bee/acp/blob/main/docs/spec/openapi.yaml).** Defines the REST API endpoints, request/response formats, and data models to form the ACP protocol.\n- **🛠️ [Python SDK](https://github.com/i-am-bee/acp/blob/main/python).** Contains a server implementation, client libraries, and model definitions to easily create and interact with ACP agents.\n- **💻 [Examples](https://github.com/i-am-bee/acp/tree/main/examples/python).** Ready-to-run code samples demonstrating how to build agents and clients that communicate using ACP.\n\n## Core Concepts\n\n| **Concept**      | **Description**  |\n| ---------------- | -------------------------------------------------------------------------------------------- |\n| **[Agent Detail](https://agentcommunicationprotocol.dev/core-concepts/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. |\n| **[Run](https://agentcommunicationprotocol.dev/core-concepts/agent-lifecycle#agent-runs-and-state-management)** | A single agent execution with specific inputs. Supports sync or streaming, with intermediate and final output. |\n| **[Message](https://agentcommunicationprotocol.dev/core-concepts/message-structure)** | The core structure for communication, consisting of a sequence of ordered components that form a complete, structured, and multi-modal exchange of information. |\n| **[MessagePart](https://agentcommunicationprotocol.dev/core-concepts/message-structure)**  | The individual content units within a `Message`, which can include types like text, image, or JSON. Together, they combine to create structured, multimodal communication. |\n| **[Await](https://agentcommunicationprotocol.dev/core-concepts/agent-lifecycle#single-turn-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. |\n\n---\n\n## Quickstart\n\n\u003e [!NOTE]\n\u003e This guide uses `uv`. See the [`uv` primer](https://agentcommunicationprotocol.dev/introduction/uv-primer) for more details.\n\n**1. Initialize your project**\n\n```sh\nuv init --python '\u003e=3.11' my_acp_project\ncd my_acp_project\n```\n\n**2. Add the ACP SDK**\n\n```sh\nuv add acp-sdk\n```\n\n**3. Create an agent**\n\nLet’s create a simple \"echo agent\" that returns any message it receives.  \nCreate an `agent.py` file in your project directory with the following code:\n\n```python\n# agent.py\nimport asyncio\nfrom collections.abc import AsyncGenerator\n\nfrom acp_sdk.models import Message\nfrom acp_sdk.server import Context, RunYield, RunYieldResume, Server\n\nserver = Server()\n\n\n@server.agent()\nasync def echo(\n    input: list[Message], context: Context\n) -\u003e AsyncGenerator[RunYield, RunYieldResume]:\n    \"\"\"Echoes everything\"\"\"\n    for message in input:\n        await asyncio.sleep(0.5)\n        yield {\"thought\": \"I should echo everything\"}\n        await asyncio.sleep(0.5)\n        yield message\n\n\nserver.run()\n```\n\n**4. Start the ACP server**\n\n```sh\nuv run agent.py\n```\n\nYour server should now be running at http://localhost:8000.\n\n**5. Verify your agent is available**\n\nIn another terminal, run the following `curl` command:\n\n```sh\ncurl http://localhost:8000/agents\n```\n\nYou should see a JSON response containing your `echo` agent, confirming it's available:\n\n```json\n{\n  \"agents\": [\n    { \"name\": \"echo\", \"description\": \"Echoes everything\", \"metadata\": {} }\n  ]\n}\n```\n\n**6. Run the agent via HTTP**\n\nRun the following `curl` command:\n\n```sh\ncurl -X POST http://localhost:8000/runs \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n        \"agent_name\": \"echo\",\n        \"input\": [\n          {\n            \"parts\": [\n              {\n                \"content\": \"Howdy!\",\n                \"content_type\": \"text/plain\"\n              }\n            ]\n          }\n        ]\n      }'\n```\n\nYour response should include the echoed message “Howdy!”:\n\n```json\n{\n  \"run_id\": \"44e480d6-9a3e-4e35-8a03-faa759e19588\",\n  \"agent_name\": \"echo\",\n  \"session_id\": \"b30b1946-6010-4974-bd35-89a2bb0ce844\",\n  \"status\": \"completed\",\n  \"await_request\": null,\n  \"output\": [\n    {\n      \"parts\": [\n        {\n          \"name\": null,\n          \"content_type\": \"text/plain\",\n          \"content\": \"Howdy!\",\n          \"content_encoding\": \"plain\",\n          \"content_url\": null\n        }\n      ]\n    }\n  ],\n  \"error\": null\n}\n```\n\nYour response should include the echoed message \"Howdy!\".\n\n**7. Build an ACP client**\n\nHere’s a simple ACP client to interact with your `echo` agent.  \nCreate a `client.py` file in your project directory with the following code:\n\n```python\n# client.py\nimport asyncio\n\nfrom acp_sdk.client import Client\nfrom acp_sdk.models import Message, MessagePart\n\n\nasync def example() -\u003e None:\n    async with Client(base_url=\"http://localhost:8000\") as client:\n        run = await client.run_sync(\n            agent=\"echo\",\n            input=[\n                Message(\n                    parts=[MessagePart(content=\"Howdy to echo from client!!\", content_type=\"text/plain\")]\n                )\n            ],\n        )\n        print(run.output)\n\n\nif __name__ == \"__main__\":\n    asyncio.run(example())\n```\n\n**8. Run the ACP client**\n\n```sh\nuv run client.py\n```\n\nYou should see the echoed response printed to your console. 🎉\n\n---\n\n## Contributors\n\nWe 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](https://agentcommunicationprotocol.dev/about/contribute) page of our documentation.\n\n![Contributors list](https://contrib.rocks/image?repo=i-am-bee/acp)\n\n## Maintainers\n\nFor information about maintainers, see [MAINTAINERS.md](./MAINTAINERS.md).\n\n---\n\nDeveloped by contributors to the BeeAI project, this initiative is part of the [Linux Foundation AI \u0026 Data program](https://lfaidata.foundation/projects/). Its development follows open, collaborative, and community-driven practices.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fi-am-bee%2Facp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fi-am-bee%2Facp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fi-am-bee%2Facp/lists"}