UAT: ASGI server lacks a version discovery endpoint — clients cannot query supported A2A protocol versions #4091

New issue

Open

opened 2026-04-06 10:15:32 +00:00 by freemo · 0 comments

freemo commented

2026-04-06 10:15:32 +00:00

Owner

Metadata

Branch: fix/asgi-a2a-version-endpoint
Commit Message: fix(a2a): add /version endpoint to ASGI server for A2A protocol version discovery
Milestone: (none — see backlog note below)
Parent Epic: #933

Backlog note: This issue was discovered during autonomous operation
on milestone v3.4.0. It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.

Bug Report

Feature Area: API Versioning and Backward Compatibility
Severity: Medium
Found by: UAT Testing (automated)

Summary

The ASGI server (src/cleveragents/a2a/asgi.py) only serves health and readiness endpoints (/live, /ready, /health, /). There is no /version endpoint that would allow clients to discover the server's supported A2A protocol versions before attempting to connect. This makes it impossible for clients to perform version negotiation without attempting a full connection.

Epic #933 explicitly lists "Version negotiation per A2A spec" as an acceptance criterion. The ASGI server must expose version information to satisfy this requirement.

Expected Behavior

The ASGI server should expose a /version endpoint that returns:

The current A2A protocol version
The list of supported A2A protocol versions
The application version

This allows clients to:

Check compatibility before sending requests
Select the appropriate protocol version
Fail fast with a clear error if versions are incompatible

Actual Behavior

Current ASGI routes in src/cleveragents/a2a/asgi.py:

GET /       → {"service": "cleveragents"}
GET /live   → {"status": "alive"}
GET /ready  → {"status": "ready"}
GET /health → {"status": "ok"}

No version information is exposed. A client connecting to the server has no way to discover what A2A protocol versions are supported without attempting to send a request and potentially receiving an A2aVersionMismatchError.

Steps to Reproduce

Start the ASGI server: agents server serve
Send GET /version request
Observe 404 response — no version endpoint exists

Impact

Clients cannot perform pre-flight version compatibility checks
Version negotiation must happen at the request level rather than the connection level
Kubernetes/container health probes cannot verify protocol version compatibility
The ServerClient.get_version() protocol method (in src/cleveragents/a2a/clients.py) has no server-side implementation to call

Code Location

src/cleveragents/a2a/asgi.py — ASGI application (missing /version route)
src/cleveragents/a2a/versioning.py — A2aVersionNegotiator (has the version data)
src/cleveragents/a2a/clients.py — ServerClient.get_version() protocol (stub)

Suggested Fix

Add a /version endpoint to the ASGI app:

if method == "GET" and path == "/version":
    import json
    from cleveragents.a2a.versioning import A2aVersionNegotiator
    from cleveragents import __version__
    negotiator = A2aVersionNegotiator()
    body = json.dumps({
        "version": __version__,
        "a2a_version": negotiator.get_current(),
        "a2a_supported_versions": list(negotiator.SUPPORTED_VERSIONS),
    }).encode()
    await _send_response(send, status=200, body=body)
    return

Subtasks

Add GET /version route to src/cleveragents/a2a/asgi.py
Implement response using A2aVersionNegotiator and __version__
Implement ServerClient.get_version() to call the new endpoint
Tests (Behave): Add scenario — GET /version returns correct version payload
Tests (Behave): Add scenario — response includes a2a_version and a2a_supported_versions
Tests (Robot): Add integration test for /version endpoint against live ASGI server
Verify coverage >=97% via nox -s coverage_report
Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off
GET /version returns a JSON payload with version, a2a_version, and a2a_supported_versions
ServerClient.get_version() successfully calls the endpoint and returns parsed version data
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly
The commit is submitted as a pull request, reviewed, and merged
All nox stages pass
Coverage >= 97%

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/asgi-a2a-version-endpoint` - **Commit Message**: `fix(a2a): add /version endpoint to ASGI server for A2A protocol version discovery` - **Milestone**: *(none — see backlog note below)* - **Parent Epic**: #933 > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.4.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. ## Bug Report **Feature Area:** API Versioning and Backward Compatibility **Severity:** Medium **Found by:** UAT Testing (automated) ### Summary The ASGI server (`src/cleveragents/a2a/asgi.py`) only serves health and readiness endpoints (`/live`, `/ready`, `/health`, `/`). There is no `/version` endpoint that would allow clients to discover the server's supported A2A protocol versions before attempting to connect. This makes it impossible for clients to perform version negotiation without attempting a full connection. Epic #933 explicitly lists "Version negotiation per A2A spec" as an acceptance criterion. The ASGI server must expose version information to satisfy this requirement. ### Expected Behavior The ASGI server should expose a `/version` endpoint that returns: - The current A2A protocol version - The list of supported A2A protocol versions - The application version This allows clients to: 1. Check compatibility before sending requests 2. Select the appropriate protocol version 3. Fail fast with a clear error if versions are incompatible ### Actual Behavior Current ASGI routes in `src/cleveragents/a2a/asgi.py`: ``` GET / → {"service": "cleveragents"} GET /live → {"status": "alive"} GET /ready → {"status": "ready"} GET /health → {"status": "ok"} ``` No version information is exposed. A client connecting to the server has no way to discover what A2A protocol versions are supported without attempting to send a request and potentially receiving an `A2aVersionMismatchError`. ### Steps to Reproduce 1. Start the ASGI server: `agents server serve` 2. Send `GET /version` request 3. Observe 404 response — no version endpoint exists ### Impact - Clients cannot perform pre-flight version compatibility checks - Version negotiation must happen at the request level rather than the connection level - Kubernetes/container health probes cannot verify protocol version compatibility - The `ServerClient.get_version()` protocol method (in `src/cleveragents/a2a/clients.py`) has no server-side implementation to call ### Code Location - `src/cleveragents/a2a/asgi.py` — ASGI application (missing `/version` route) - `src/cleveragents/a2a/versioning.py` — `A2aVersionNegotiator` (has the version data) - `src/cleveragents/a2a/clients.py` — `ServerClient.get_version()` protocol (stub) ### Suggested Fix Add a `/version` endpoint to the ASGI app: ```python if method == "GET" and path == "/version": import json from cleveragents.a2a.versioning import A2aVersionNegotiator from cleveragents import __version__ negotiator = A2aVersionNegotiator() body = json.dumps({ "version": __version__, "a2a_version": negotiator.get_current(), "a2a_supported_versions": list(negotiator.SUPPORTED_VERSIONS), }).encode() await _send_response(send, status=200, body=body) return ``` ## Subtasks - [ ] Add `GET /version` route to `src/cleveragents/a2a/asgi.py` - [ ] Implement response using `A2aVersionNegotiator` and `__version__` - [ ] Implement `ServerClient.get_version()` to call the new endpoint - [ ] Tests (Behave): Add scenario — `GET /version` returns correct version payload - [ ] Tests (Behave): Add scenario — response includes `a2a_version` and `a2a_supported_versions` - [ ] Tests (Robot): Add integration test for `/version` endpoint against live ASGI server - [ ] Verify coverage >=97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - [ ] All subtasks above are completed and checked off - [ ] `GET /version` returns a JSON payload with `version`, `a2a_version`, and `a2a_supported_versions` - [ ] `ServerClient.get_version()` successfully calls the endpoint and returns parsed version data - [ ] A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly - [ ] The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly - [ ] The commit is submitted as a **pull request**, reviewed, and **merged** - [ ] All nox stages pass - [ ] Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added a new dependency

2026-04-06 10:15:41 +00:00

#933 Epic: A2A Protocol Compliance — JSON-RPC 2.0 Framing, Standard Operations, and Extension Methods

freemo added the

Points

label

2026-04-06 10:20:58 +00:00

freemo referenced this issue

2026-04-06 10:23:25 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775