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
• Service Wiring
• Operation Routing Table
• Error Code Taxonomy
• 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

---

Service Wiring

Each ACP operation is wired to a concrete application service. Services are injected via the services dict at construction time or registered later with register_service(). When a service key is absent, the handler falls back to a safe stub response.

Service Keys

Key	Type	Wired Operations
session_service	SessionService	session.create, session.close
plan_lifecycle_service	PlanLifecycleService	plan.create, plan.execute, plan.status, plan.diff, plan.apply
tool_registry	ToolRegistry	registry.list_tools
resource_registry_service	ResourceRegistryService	registry.list_resources
event_queue	AcpEventQueue	event.subscribe

Wired Operation Details

Operation	Service	Service Method	Required Params
session.create	SessionService	create(actor_name=…)	actor_name (optional)
session.close	SessionService	delete(session_id)	session_id
plan.create	PlanLifecycleService	use_action(…)	action_name
plan.execute	PlanLifecycleService	execute_plan(plan_id)	plan_id
plan.status	PlanLifecycleService	get_plan(plan_id)	plan_id
plan.diff	PlanLifecycleService	get_plan(plan_id)	plan_id
plan.apply	PlanLifecycleService	apply_plan(plan_id)	plan_id
registry.list_tools	ToolRegistry	list_tools(namespace=…)	namespace (optional)
registry.list_resources	ResourceRegistryService	list_resources(type_name=…)	type_name (optional)
context.get	(stub)	N/A	—
event.subscribe	AcpEventQueue	subscribe_local(cb)	—

!!! note "context.get" context.get currently returns a stub response ({"context": {}, "stub": true}) pending the completion of the ACMS ContextAssemblyPipeline.

Example: Wired Facade

from cleveragents.acp.facade import AcpLocalFacade
from cleveragents.acp.events import AcpEventQueue
from cleveragents.acp.models import AcpRequest

facade = AcpLocalFacade(services={
    "session_service": my_session_service,
    "plan_lifecycle_service": my_plan_lifecycle_service,
    "tool_registry": my_tool_registry,
    "resource_registry_service": my_resource_registry_service,
    "event_queue": AcpEventQueue(),
})

response = facade.dispatch(
    AcpRequest(operation="plan.status", params={"plan_id": "01J…"})
)
assert response.status == "ok"
assert "phase" in response.data

---

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, state
plan.diff	plan_id, changes, phase
plan.apply	plan_id, status
registry.list_tools	tools (list of {name, description})
registry.list_resources	resources (list of {resource_id, name, type_name})
context.get	context, stub, message
event.subscribe	subscription_id, status

Unknown operations raise AcpOperationNotFoundError.

---

Error Code Taxonomy

Domain exceptions are mapped to ACP error codes via map_domain_error():

ACP Error Code	Domain Exception(s)	Meaning
NOT_FOUND	ResourceNotFoundError	Requested entity does not exist
VALIDATION_ERROR	ValidationError	Input failed validation
PLAN_ERROR	PlanError	Plan lifecycle fault
INVALID_STATE	BusinessRuleViolation	State precondition not met
AUTH_ERROR	AuthenticationError	Authentication failure
FORBIDDEN	AuthorizationError	Insufficient permissions
CONFIGURATION_ERROR	ConfigurationError	Configuration missing or invalid
INTERNAL_ERROR	Any other CleverAgentsError or Exception	Unexpected server error

Error details are returned in the AcpResponse.error field as an AcpErrorDetail with the code and message fields populated.

---

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