cleveragents-core/docs/reference/acp.md

ACP (Agent Communication Protocol) Reference

Overview

The ACP package provides the boundary layer between the CleverAgents application core and any external orchestrator or UI. It defines a request/response envelope, a set of named operations, and an event streaming interface.

Module: cleveragents.acp
ACP Version: 1.0

Table of Contents

• Modes of Operation
• Local Facade
• Operation Routing Table
• Server Transport Stub
• Event Queue
• Version Negotiation
• Models
• Error Hierarchy

---

Modes of Operation

Mode	Class	Behaviour
Local	AcpLocalFacade	Routes operations to in-process service calls
Server	AcpHttpTransport	Stub — raises AcpNotAvailableError on all ops

In local mode the facade translates each ACP operation into a direct Python method call. No serialization, no network, no authentication overhead.

---

Local Facade

from cleveragents.acp import AcpLocalFacade, AcpRequest

facade = AcpLocalFacade()
response = facade.dispatch(AcpRequest(operation="session.create"))
assert response.status == "ok"

Constructor

Parameter	Type	Default	Description
services	dict[str, Any] | None	None	Named services for routing

Methods

Method	Returns	Description
dispatch(request)	AcpResponse	Route request to handler
register_service	None	Register a named service
list_operations	list[str]	All supported operation names

---

Operation Routing Table

Operation	Response Keys
session.create	session_id, status
session.close	status
plan.create	plan_id, status
plan.execute	plan_id, status
plan.status	plan_id, phase
plan.diff	plan_id, changes
plan.apply	plan_id, status
registry.list_tools	tools
registry.list_resources	resources
context.get	context
event.subscribe	subscription_id, status

Unknown operations raise AcpOperationNotFoundError.

---

Server Transport Stub

All methods on AcpHttpTransport raise AcpNotAvailableError:

Method	Description
send(request)	Would send request over HTTP
connect(url)	Would open HTTP connection
disconnect()	Would close connection
is_connected()	Returns False (does not raise)

---

Event Queue

AcpEventQueue provides an in-memory event queue for local mode:

Method	Mode	Description
publish(event)	Local	Append event and notify callbacks
subscribe_local(cb)	Local	Register callback, return sub ID
unsubscribe(id)	Local	Remove subscription
get_events(limit)	Local	Return recent events
subscribe_remote(ep)	Server	Raises AcpNotAvailableError

---

Version Negotiation

AcpVersionNegotiator validates protocol version compatibility:

from cleveragents.acp import AcpVersionNegotiator

negotiator = AcpVersionNegotiator()
version = negotiator.negotiate("1.0")  # returns "1.0"
negotiator.negotiate("2.0")            # raises AcpVersionMismatchError

Supported versions: ["1.0"]

---

Models

AcpRequest

Field	Type	Default
acp_version	str	"1.0"
request_id	str	Auto-generated ULID
operation	str	required
params	dict[str, Any]	{}
auth	dict[str, Any] | None	None

AcpResponse

Field	Type	Default
acp_version	str	"1.0"
request_id	str	required
status	str ("ok" or "error")	required
data	dict[str, Any]	{}
error	AcpErrorDetail | None	None
timing_ms	float | None	None

AcpErrorDetail

Field	Type	Default
code	str	required
message	str	required
details	dict[str, Any]	{}

AcpEvent

Field	Type	Default
event_id	str	Auto-generated ULID
event_type	str	required
plan_id	str | None	None
data	dict[str, Any]	{}
timestamp	str	Auto-generated ISO UTC

---

Error Hierarchy

CleverAgentsError
  └── AcpError
        ├── AcpNotAvailableError
        ├── AcpVersionMismatchError
        └── AcpOperationNotFoundError

Exception	When Raised
AcpNotAvailableError	Server-mode operation in local mode
AcpVersionMismatchError	Unsupported ACP version requested
AcpOperationNotFoundError	Unknown operation dispatched