UAT: `docs/api/a2a.md` has multiple inaccurate API signatures — `A2aLocalFacade`, `A2aEventQueue`, and `ServerConnectionConfig` documented incorrectly #6093

New issue

Open

opened 2026-04-09 14:32:03 +00:00 by HAL9000 · 0 comments

HAL9000 commented

2026-04-09 14:32:03 +00:00

Owner

Bug Report

Summary

docs/api/a2a.md contains multiple inaccurate API signatures that do not match the actual implementation in src/cleveragents/a2a/. Developers following the documentation will encounter TypeError or AttributeError at runtime.

Feature Area

ACP → A2A module rename and symbol standardization (v3.6.0 deliverable #1)

Findings

1. `A2aLocalFacade` constructor signature is wrong

Documentation shows:

facade = A2aLocalFacade(container)
response = await facade.dispatch(...)

Actual implementation (facade.py):

def __init__(self, services: dict[str, Any] | None = None) -> None:
def dispatch(self, request: A2aRequest) -> A2aResponse:  # synchronous, not async

Two errors:

Constructor takes services: dict not a container object
dispatch() is synchronous (def, not async def) — await facade.dispatch(...) will raise TypeError

2. `A2aEventQueue.subscribe()` method does not exist

Documentation shows:

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

Actual implementation (events.py):

No subscribe() method exists
The actual methods are subscribe_local(callback) (synchronous, callback-based) and subscribe_remote(endpoint) (raises A2aNotAvailableError)
A2aEvent has no .type or .payload attributes — it has .event_type and .data

3. `ServerConnectionConfig` uses wrong parameter name

Documentation shows:

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

Actual implementation (server_config.py):

class ServerConnectionConfig(BaseModel):
    server_url: str          # not "url"
    auth_token_ref: str | None = None  # not "token"

4. `A2aLocalFacade` operation table only shows legacy operations

The documentation table only lists legacy operations (session.create, plan.create, etc.) and does not document the spec-aligned _cleveragents/ extension methods that are the primary interface per ADR-047.

Expected Behavior (per spec)

docs/api/a2a.md should accurately document:

A2aLocalFacade(services: dict | None = None) constructor
dispatch(request: A2aRequest) -> A2aResponse (synchronous)
A2aEventQueue.subscribe_local(callback) and get_events(limit) methods
ServerConnectionConfig(server_url=..., auth_token_ref=...) parameter names
The full _cleveragents/ extension method catalog per ADR-047

Steps to Reproduce

from cleveragents.a2a import A2aLocalFacade, A2aEventQueue, ServerConnectionConfig

# Error 1: Wrong constructor
facade = A2aLocalFacade(container)  # TypeError: takes 0-1 positional args

# Error 2: Method doesn't exist
queue = A2aEventQueue()
async for event in queue.subscribe("plan-42"):  # AttributeError: no subscribe()
    pass

# Error 3: Wrong parameter name
config = ServerConnectionConfig(url="https://example.com")  # ValidationError

Code Location

Documentation: docs/api/a2a.md
Implementation: src/cleveragents/a2a/facade.py, src/cleveragents/a2a/events.py, src/cleveragents/a2a/server_config.py

Priority Assessment

Non-critical (documentation only, not blocking milestone acceptance criteria). Assigned to backlog.

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: uat-tester

## Bug Report ### Summary `docs/api/a2a.md` contains multiple inaccurate API signatures that do not match the actual implementation in `src/cleveragents/a2a/`. Developers following the documentation will encounter `TypeError` or `AttributeError` at runtime. ### Feature Area ACP → A2A module rename and symbol standardization (v3.6.0 deliverable #1) ### Findings #### 1. `A2aLocalFacade` constructor signature is wrong **Documentation shows:** ```python facade = A2aLocalFacade(container) response = await facade.dispatch(...) ``` **Actual implementation (`facade.py`):** ```python def __init__(self, services: dict[str, Any] | None = None) -> None: def dispatch(self, request: A2aRequest) -> A2aResponse: # synchronous, not async ``` Two errors: - Constructor takes `services: dict` not a `container` object - `dispatch()` is **synchronous** (`def`, not `async def`) — `await facade.dispatch(...)` will raise `TypeError` #### 2. `A2aEventQueue.subscribe()` method does not exist **Documentation shows:** ```python queue = A2aEventQueue() async for event in queue.subscribe("plan-42"): print(event.type, event.payload) ``` **Actual implementation (`events.py`):** - No `subscribe()` method exists - The actual methods are `subscribe_local(callback)` (synchronous, callback-based) and `subscribe_remote(endpoint)` (raises `A2aNotAvailableError`) - `A2aEvent` has no `.type` or `.payload` attributes — it has `.event_type` and `.data` #### 3. `ServerConnectionConfig` uses wrong parameter name **Documentation shows:** ```python config = ServerConnectionConfig(url="https://my-server.example.com", token="...") ``` **Actual implementation (`server_config.py`):** ```python class ServerConnectionConfig(BaseModel): server_url: str # not "url" auth_token_ref: str | None = None # not "token" ``` #### 4. `A2aLocalFacade` operation table only shows legacy operations The documentation table only lists legacy operations (`session.create`, `plan.create`, etc.) and does not document the spec-aligned `_cleveragents/` extension methods that are the primary interface per ADR-047. ### Expected Behavior (per spec) `docs/api/a2a.md` should accurately document: - `A2aLocalFacade(services: dict | None = None)` constructor - `dispatch(request: A2aRequest) -> A2aResponse` (synchronous) - `A2aEventQueue.subscribe_local(callback)` and `get_events(limit)` methods - `ServerConnectionConfig(server_url=..., auth_token_ref=...)` parameter names - The full `_cleveragents/` extension method catalog per ADR-047 ### Steps to Reproduce ```python from cleveragents.a2a import A2aLocalFacade, A2aEventQueue, ServerConnectionConfig # Error 1: Wrong constructor facade = A2aLocalFacade(container) # TypeError: takes 0-1 positional args # Error 2: Method doesn't exist queue = A2aEventQueue() async for event in queue.subscribe("plan-42"): # AttributeError: no subscribe() pass # Error 3: Wrong parameter name config = ServerConnectionConfig(url="https://example.com") # ValidationError ``` ### Code Location - Documentation: `docs/api/a2a.md` - Implementation: `src/cleveragents/a2a/facade.py`, `src/cleveragents/a2a/events.py`, `src/cleveragents/a2a/server_config.py` ### Priority Assessment Non-critical (documentation only, not blocking milestone acceptance criteria). Assigned to backlog. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

HAL9000 added the

labels

2026-04-09 14:54:11 +00:00

HAL9000 referenced this issue

2026-04-09 15:48:37 +00:00