# `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](../adr/ADR-026-agent-client-protocol.md) and
[ADR-047](../adr/ADR-047-acp-standard-adoption.md) for design rationale.

---

## Core Classes

### `A2aLocalFacade`

```python
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 |

```python
from cleveragents.a2a import A2aLocalFacade, A2aRequest

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

---

### `A2aRequest` / `A2aResponse`

```python
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.

```python
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

```python
from cleveragents.a2a import ServerConnectionConfig

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

Validates URL format and token presence.