cleveragents-core/docs/api/a2a.md

cleveragents.a2a — Agent-to-Agent Protocol

The a2a package implements the Agent-to-Agent (A2A) protocol boundary. In local mode the A2aLocalFacade maps A2A operation names to direct Python method calls on application services — no serialization, no network. In server mode stub transports raise A2aNotAvailableError until the concrete HTTP transport is wired in.

See ADR-026 and ADR-047 for design rationale.

---

Core Classes

A2aLocalFacade

class A2aLocalFacade:
    async def dispatch(self, request: A2aRequest) -> A2aResponse: ...

Routes A2A requests to live application services. Supported operations:

Operation	Description
session.create	Create a new conversation session
session.close	Close an existing session
plan.create	Create a new plan
plan.execute	Execute a plan
plan.status	Query plan status
plan.diff	Retrieve plan diff
plan.apply	Apply a plan
registry.list_tools	List available tools
registry.list_resources	List available resources
event.subscribe	Subscribe to event stream

from cleveragents.a2a import A2aLocalFacade, A2aRequest

facade = A2aLocalFacade(container)
response = await facade.dispatch(
    A2aRequest(operation="session.create", params={"actor": "openai/gpt-4o"})
)

---

A2aRequest / A2aResponse

class A2aRequest(BaseModel):
    operation: str
    params: dict[str, Any] = {}
    version: A2aVersion = A2aVersion.V1

class A2aResponse(BaseModel):
    success: bool
    data: Any | None = None
    error: A2aErrorDetail | None = None

---

A2aEventQueue

Async event queue for subscribing to plan and session events.

queue = A2aEventQueue()
async for event in queue.subscribe("plan-42"):
    print(event.type, event.payload)

Call queue.close() on shutdown to release resources.

---

A2aVersionNegotiator

Negotiates the A2A protocol version between client and server.

---

Error Types

Exception	Description
A2aError	Base A2A exception
A2aNotAvailableError	Operation not available in current mode
A2aOperationNotFoundError	Unknown operation name
A2aVersionMismatchError	Incompatible protocol versions

---

Server Client Stubs

ServerClient, RemoteExecutionClient, and AuthClient are protocol interfaces for server-mode operation. StubServerClient, StubRemoteExecutionClient, and StubAuthClient raise A2aNotAvailableError for all methods until server mode is fully implemented.

---

Server Connection

from cleveragents.a2a import ServerConnectionConfig

config = ServerConnectionConfig(url="https://my-server.example.com", token="...")

Validates URL format and token presence.