forked from cleveragents/cleveragents-core
freemo
e9c96c3d0c
Add docs/api/ with per-module API documentation for core, a2a, actor, skills, tool, mcp, resource, and config packages. Add docs/architecture.md with a developer-oriented system overview including component map, layer diagram, plan lifecycle, and key design decisions. Update mkdocs.yml nav to expose both new sections. ISSUES CLOSED: #N/A
115 lines
2.9 KiB
Markdown
115 lines
2.9 KiB
Markdown
# `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.
|