Architecture

The Agent Context Protocol (ACP) extends the Model Context Protocol (MCP) by introducing the concept of agents, enabling more dynamic and modular interactions.

​

Client-Server Architecture

ACP maintains the fundamental client-server architecture from MCP, allowing clients to interact with multiple servers seamlessly.

• Hosts: Applications or environments (IDEs, development tools, AI systems) that utilize ACP to access data and services through agents. A good example of a host is BeeAI UI, which can be invoked with the command beeai ui.
• Clients: Protocol clients maintaining direct connections with ACP servers, exchanging requests and responses via JSON-RPC.
• Servers: Servers providing specialized capabilities via agents, responding to client requests, and managing interactions with local or remote data sources.

​

Core Components

​

Protocol Layer

ACP utilizes JSON-RPC 2.0, a standardized protocol for invoking remote server functions using JSON messages. JSON-RPC is specifically designed for Remote Procedure Calls (RPC). It defines message formats and request-response handling, explicitly making it a Layer 7 protocol.

JSON-RPC message example:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "methodName",
  "params": {
    /* parameters */
  }
}

ACP inherits the message types from MCP:

• Requests: Expect responses from servers or agents.
• Results: Responses indicating successful handling of requests.
• Notifications: One-way messages for updates or event reporting.
• Errors: Standardized error reporting with clear codes and descriptive messages.

​

Communication Layer

The Communication Layer provides optional schemas for JSON-RPC communication. Agents are not required to strictly adhere to these schemas but, if adopted, can leverage built-in UI components, simplified composition patterns, and better interoperability across ACP-enabled tools and systems.

class TextInput(Input):
    text: str

class TextOutput(Output):
    text: str

class UserMessage(BaseModel):
    role: Literal["user"]
    content: str

class AssistantMessage(BaseModel):
    role: Literal["assistant"]
    content: str

Message = Annotated[Union[UserMessage, AssistantMessage], Discriminator("role")]

class MessageInput(Input):
    messages: list[Message]

class MessageOutput(Output):
    messages: list[Message]

​

Transport Layer

This layer manages how JSON-RPC messages are physically exchanged. Supported transport methods include:

• HTTP with Server-Sent Events (SSE) (preferred): Optimal for remote transfer.
• Stdio: Optimal for local process communication.
• WebSockets (under development): Optimal for bi-directional remote communication.

​

ACP in OSI Model

The following example illustrates where ACP fits within the Open Systems Interconnection (OSI) model. This is a simplified representation showcasing the recommended usage of ACP through HTTP with SSE.

Both ACP and JSON-RPC operate above the Application layer, as they manage higher-level interactions.