DOCSEARCHbyAlgolia
Submit Docs

Agent Communication Protocol (ACP)

repository·main·Indexed 21 days ago

https://github.com/i-am-bee/acp

An open protocol for multimodal communication, coordination, and state sharing between AI agents, applications, and humans. It includes a Python SDK for both server and client implementations, a TypeScript SDK for client consumption, and an OpenAPI specification. Key concepts include Agent Manifests, Runs, Messages, and Sessions to enable structured interaction and discovery of agent capabilities.

Tokens
43.3K
Snippets
140
Records
210
Agent score
77%

What's inside ACP

  1. Overview of the acp_sdk Python package

    main

    The acp_sdk is the Python implementation of the Agent Communication Protocol (ACP). It provides the necessary tools to build and interact with agents using the protocol. The package is organized into several functional areas:

    • acp_sdk.client: Tools for implementing an ACP client to communicate with agents or servers.
    • acp_sdk.server: Tools for implementing an ACP server to host agent capabilities.
    • acp_sdk.models: Data models and schemas that define the structure of ACP messages and entities.
    • acp_sdk.instrumentation: Utilities for monitoring, logging, or tracing ACP communications.
    • acp_sdk.version: Package versioning information.

  2. Overview of the ACP TypeScript SDK

    main

    The Agent Communication Protocol SDK for TypeScript is designed to help developers consume agents that follow the ACP standard.

    Current Capabilities:

    • Provides an ACP Client for interacting with agents.
    • Provides Data Models for protocol compliance.

    Limitations:

    • The SDK currently does not include a server implementation (server implementation is planned for a future release).

  3. Explore the acp_sdk.client package

    main

    The acp_sdk.client package is the primary entry point for interacting with the Agent Communication Protocol (ACP) using the Python SDK. It provides the core client functionality required to communicate with agents and orchestrators. The package is organized into several submodules:

    • acp_sdk.client.client: Contains the main client implementation and logic.
    • acp_sdk.client.types: Defines the data structures, schemas, and type hints used throughout the client.
    • acp_sdk.client.utils: Provides helper functions and utilities for client operations.

  4. What is the Agent Communication Protocol (ACP)?

    main

    The Agent Communication Protocol (ACP) is an open, standardized RESTful API designed for agent interoperability. It allows AI agents, applications, and humans to communicate regardless of the underlying framework (e.g., BeeAI, LangChain, CrewAI) or infrastructure.

    ACP supports:

    • Multiple Modalities: Uses MimeTypes for content identification (text, images, audio, video, etc.).
    • Communication Patterns: Supports synchronous, asynchronous, and streaming interactions.
    • Operational Modes: Handles both stateful and stateless operations, as well as long-running tasks.
    • Discovery: Enables both online and offline agent discovery (via metadata in distribution packages).

    ACP is an open standard developed under the Linux Foundation (as part of A2A).

  5. What is Agent Detail and how is it used?

    main
    Agent Detail is a structured description of an agent's properties, including its identity, capabilities, metadata, and runtime status. It is defined via the @server.agent decorator. This detail is used by the ACP server to advertise the agent's existence and capabilities to clients, enabling discovery and proper interaction within the Agent Communication Protocol (ACP) ecosystem.

  6. What is an Agent Manifest

    main

    An Agent Manifest is a structured description of an agent's identity, capabilities, metadata, and runtime status. It is used by the ACP server to advertise agents to clients and facilitates agent discoverability.

    If an agent's name or description are not explicitly provided during implementation, the ACP server will use the agent's function name and its docstring as defaults.

  7. Use Trajectory Metadata for reasoning tracking

    main
    ACP now supports TrajectoryMetadata within MessagePart. This allows agents to expose internal reasoning paths, tool invocation chains, and state transitions. Use this to implement advanced debugging and interpretability workflows by tracking how an agent arrives at a specific response.

  8. Use Citation Metadata for source attribution

    main

    Citation metadata is used to attribute content to original sources, which is essential for research and RAG (Retrieval-Augmented Generation) agents. It identifies the specific text range in a message part that corresponds to a source.

    Each citation metadata object must include a kind field set to "citation".

    Fields:

    • start_index (Optional[int]): The start of the text range.
    • end_index (Optional[int]): The end of the text range.
    • url (Optional[str]): The source URL.
    • title (Optional[str]): The source title.
    • description (Optional[str]): A source description or snippet.
    yield MessagePart(
    content="According to recent studies, AI adoption has increased by 40% this year.",
    metadata=CitationMetadata(
        url="https://example.com/ai-study-2024",
        title="AI Adoption Report 2024",
        description="Comprehensive analysis of AI adoption trends across industries",
        start_index=15,
        end_index=27
    )
)

  9. Understand the relationship between MCP and ACP

    main

    The Model Context Protocol (MCP) and the Agent Communication Protocol (ACP) serve different purposes in an agentic system and are designed to work together:

    • MCP (Model Context Protocol): An open standard (by Anthropic) that provides a single agent with context, such as tools and resources. It manages the connection between an LLM and its local environment.
    • ACP (Agent Communication Protocol): A protocol designed for communication between multiple agents. It enables different agents to interact with one another.

    In a complete system, MCP is used inside each agent to connect the model to its tools, while ACP is used between agents to facilitate multi-agent collaboration.

  10. Configure Message Roles

    main

    Every message must specify a role to identify the sender. Valid formats include:

    • user: Messages originating from a human user.
    • agent: Generic messages from an agent.
    • agent/{name}: Specific messages from a named agent. The {name} can contain alphanumeric characters, underscores, and hyphens (e.g., agent/image-analyzer, agent/chat_bot).

  11. Understand the ACP error structure

    main

    The Agent Communication Protocol (ACP) uses a consistent error structure designed to separate programmatic logic from human-readable information. Every error consists of two primary fields:

    • Code: A predefined identifier used for programmatic error handling (e.g., deciding whether to retry a request or prompt the user for new input).
    • Message: A human-readable description intended for logging or displaying to an end-user.

    Refer to the official ACP specification for the complete list of available error codes.

  12. Use the Await mechanism to pause agent execution

    main

    The Await mechanism allows an agent to pause its execution in the awaiting state when it requires external data, user clarification, or confirmation to proceed.

    Once the agent is in the awaiting state, the client can interact with it using the following outcomes:

    1. Resumed Execution: The client provides the requested information via the resume endpoint, transitioning the agent back to in-progress.
    2. Cancelled Execution: The client cancels the run while it is waiting.
    3. Timeout: If no response is received within the timeout period, the run transitions to failed.