UAT: ASGI server (cleveragents.a2a.asgi:app) missing A2A JSON-RPC endpoint and /.well-known/agent.json Agent Card endpoint #3533

Open
opened 2026-04-05 19:01:07 +00:00 by freemo · 3 comments
Owner

Metadata

  • Branch: fix/asgi-a2a-endpoint-agent-card
  • Commit Message: fix(a2a): wire A2A JSON-RPC endpoint and Agent Card to ASGI app
  • Milestone: v3.6.0
  • Parent Epic: #933

Summary

The ASGI application at src/cleveragents/a2a/asgi.py only serves health/readiness probe endpoints (/live, /ready, /health, /). It is missing the two endpoints that are architecturally required by the spec:

  1. A2A JSON-RPC 2.0 endpoint — the spec states: "The server's sole client-facing interface is an A2A JSON-RPC 2.0 endpoint implemented using the A2A Python SDK's server-side connection handler. There is no REST API, no GraphQL, no separate admin endpoint." (spec §Server Presentation Layer)
  2. /.well-known/agent.json Agent Card endpoint — the spec states: "The connection lifecycle follows the A2A standard: the client discovers the server's Agent Card (capability exchange), authenticates via the declared HTTP auth scheme" (spec §Server Configuration and Connection). The Agent Card is fetched from /.well-known/agent.json.

Expected Behavior (from spec)

The ASGI app must expose:

  • A JSON-RPC 2.0 endpoint (e.g., /a2a or /) that accepts POST requests with A2A JSON-RPC payloads and routes them to A2aLocalFacade (or the server-side equivalent)
  • A GET /.well-known/agent.json endpoint that returns the Agent Card JSON describing supported capabilities, authentication schemes, and _cleveragents/ extension methods

The Agent Card must declare:

  • Supported A2A operations (message/send, message/stream)
  • CleverAgents extension methods (_cleveragents/*)
  • Authentication schemes (OAuth2, API key, Bearer token)
  • Protocol version (A2A-Version header)

Actual Behavior

src/cleveragents/a2a/asgi.py only handles:

  • GET /live{"status":"alive"}
  • GET /ready{"status":"ready"}
  • GET /health{"status":"ok"}
  • GET /{"service":"cleveragents"}
  • All other paths → 404

There is no A2A JSON-RPC endpoint and no Agent Card endpoint. Any client attempting to connect via A2A over HTTP will receive 404 for all A2A requests.

Steps to Reproduce

  1. Start the server: agents server serve --port 8000
  2. Attempt to fetch the Agent Card: curl http://localhost:8000/.well-known/agent.json
  3. Observe: {"error":"not found"} (404)
  4. Attempt an A2A JSON-RPC call: curl -X POST http://localhost:8000/a2a -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"_cleveragents/health/check","params":{}}'
  5. Observe: {"error":"not found"} (404)

Code Location

  • src/cleveragents/a2a/asgi.py — missing A2A endpoint and Agent Card endpoint
  • src/cleveragents/a2a/facade.pyA2aLocalFacade exists and is ready to handle dispatch, but is not wired to the ASGI app

Spec References

  • spec §Server Presentation Layer: "The server's sole client-facing interface is an A2A JSON-RPC 2.0 endpoint"
  • spec §Authentication: "Client fetches the server's Agent Card (via /.well-known/agent.json or configured URL)"
  • spec §Server Configuration and Connection: "The connection lifecycle follows the A2A standard: the client discovers the server's Agent Card"
  • spec §Transport Modes: "In server mode, A2A flows over HTTP to the CleverAgents server"

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

Subtasks

  • Write failing Behave scenario: GET /.well-known/agent.json returns 404 (TDD — must be committed to master before fix)
  • Write failing Behave scenario: POST /a2a JSON-RPC 2.0 request returns 404 (TDD — must be committed to master before fix)
  • Add GET /.well-known/agent.json endpoint to asgi.py returning Agent Card JSON
  • Add POST /a2a JSON-RPC 2.0 endpoint to asgi.py routing to A2aLocalFacade
  • Wire A2aLocalFacade dispatch to the new ASGI A2A endpoint
  • Agent Card JSON declares: supported A2A operations (message/send, message/stream), _cleveragents/* extension methods, authentication schemes, and A2A-Version header
  • Add Robot Framework integration test for A2A endpoint and Agent Card endpoint
  • Run nox (all default sessions) and fix any errors
  • Verify coverage >= 97% via nox -s coverage_report

Definition of Done

  • Failing Behave scenarios committed to master before fix is implemented (TDD requirement per CONTRIBUTING.md)
  • GET /.well-known/agent.json returns valid Agent Card JSON (200 OK)
  • POST /a2a accepts JSON-RPC 2.0 payloads and routes to A2aLocalFacade
  • Agent Card declares supported A2A operations, _cleveragents/* extension methods, authentication schemes, and A2A-Version
  • All other existing ASGI endpoints (/live, /ready, /health, /) continue to function correctly
  • All nox stages pass
  • Coverage >= 97%

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

## Metadata - **Branch**: `fix/asgi-a2a-endpoint-agent-card` - **Commit Message**: `fix(a2a): wire A2A JSON-RPC endpoint and Agent Card to ASGI app` - **Milestone**: v3.6.0 - **Parent Epic**: #933 ## Summary The ASGI application at `src/cleveragents/a2a/asgi.py` only serves health/readiness probe endpoints (`/live`, `/ready`, `/health`, `/`). It is missing the two endpoints that are architecturally required by the spec: 1. **A2A JSON-RPC 2.0 endpoint** — the spec states: *"The server's sole client-facing interface is an A2A JSON-RPC 2.0 endpoint implemented using the A2A Python SDK's server-side connection handler. There is no REST API, no GraphQL, no separate admin endpoint."* (spec §Server Presentation Layer) 2. **`/.well-known/agent.json` Agent Card endpoint** — the spec states: *"The connection lifecycle follows the A2A standard: the client discovers the server's Agent Card (capability exchange), authenticates via the declared HTTP auth scheme"* (spec §Server Configuration and Connection). The Agent Card is fetched from `/.well-known/agent.json`. ## Expected Behavior (from spec) The ASGI app must expose: - A JSON-RPC 2.0 endpoint (e.g., `/a2a` or `/`) that accepts `POST` requests with A2A JSON-RPC payloads and routes them to `A2aLocalFacade` (or the server-side equivalent) - A `GET /.well-known/agent.json` endpoint that returns the Agent Card JSON describing supported capabilities, authentication schemes, and `_cleveragents/` extension methods The Agent Card must declare: - Supported A2A operations (`message/send`, `message/stream`) - CleverAgents extension methods (`_cleveragents/*`) - Authentication schemes (OAuth2, API key, Bearer token) - Protocol version (`A2A-Version` header) ## Actual Behavior `src/cleveragents/a2a/asgi.py` only handles: - `GET /live` → `{"status":"alive"}` - `GET /ready` → `{"status":"ready"}` - `GET /health` → `{"status":"ok"}` - `GET /` → `{"service":"cleveragents"}` - All other paths → 404 There is no A2A JSON-RPC endpoint and no Agent Card endpoint. Any client attempting to connect via A2A over HTTP will receive 404 for all A2A requests. ## Steps to Reproduce 1. Start the server: `agents server serve --port 8000` 2. Attempt to fetch the Agent Card: `curl http://localhost:8000/.well-known/agent.json` 3. Observe: `{"error":"not found"}` (404) 4. Attempt an A2A JSON-RPC call: `curl -X POST http://localhost:8000/a2a -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"_cleveragents/health/check","params":{}}'` 5. Observe: `{"error":"not found"}` (404) ## Code Location - `src/cleveragents/a2a/asgi.py` — missing A2A endpoint and Agent Card endpoint - `src/cleveragents/a2a/facade.py` — `A2aLocalFacade` exists and is ready to handle dispatch, but is not wired to the ASGI app ## Spec References - spec §Server Presentation Layer: *"The server's sole client-facing interface is an A2A JSON-RPC 2.0 endpoint"* - spec §Authentication: *"Client fetches the server's Agent Card (via `/.well-known/agent.json` or configured URL)"* - spec §Server Configuration and Connection: *"The connection lifecycle follows the A2A standard: the client discovers the server's Agent Card"* - spec §Transport Modes: *"In server mode, A2A flows over HTTP to the CleverAgents server"* --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-uat-tester ## Subtasks - [ ] Write failing Behave scenario: `GET /.well-known/agent.json` returns 404 (TDD — must be committed to `master` before fix) - [ ] Write failing Behave scenario: `POST /a2a` JSON-RPC 2.0 request returns 404 (TDD — must be committed to `master` before fix) - [ ] Add `GET /.well-known/agent.json` endpoint to `asgi.py` returning Agent Card JSON - [ ] Add `POST /a2a` JSON-RPC 2.0 endpoint to `asgi.py` routing to `A2aLocalFacade` - [ ] Wire `A2aLocalFacade` dispatch to the new ASGI A2A endpoint - [ ] Agent Card JSON declares: supported A2A operations (`message/send`, `message/stream`), `_cleveragents/*` extension methods, authentication schemes, and `A2A-Version` header - [ ] Add Robot Framework integration test for A2A endpoint and Agent Card endpoint - [ ] Run `nox` (all default sessions) and fix any errors - [ ] Verify coverage >= 97% via `nox -s coverage_report` ## Definition of Done - [ ] Failing Behave scenarios committed to `master` before fix is implemented (TDD requirement per CONTRIBUTING.md) - [ ] `GET /.well-known/agent.json` returns valid Agent Card JSON (200 OK) - [ ] `POST /a2a` accepts JSON-RPC 2.0 payloads and routes to `A2aLocalFacade` - [ ] Agent Card declares supported A2A operations, `_cleveragents/*` extension methods, authentication schemes, and `A2A-Version` - [ ] All other existing ASGI endpoints (`/live`, `/ready`, `/health`, `/`) continue to function correctly - [ ] All nox stages pass - [ ] Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator
freemo added this to the v3.6.0 milestone 2026-04-05 19:01:12 +00:00
Author
Owner

Issue triaged by project owner:

  • State: Verified
  • Priority: Critical — The ASGI server is the sole client-facing interface per spec §Server Presentation Layer. Without the A2A JSON-RPC endpoint and Agent Card, no external client can communicate with the server at all.
  • Milestone: v3.6.0 (already set, correct — A2A module rename and standardization is in M7 scope)
  • Story Points: 5 — L — Requires adding two new ASGI endpoints, wiring to existing A2aLocalFacade, constructing Agent Card JSON with capability declarations, plus Behave and Robot Framework tests. Moderate complexity with clear implementation path.
  • MoSCoW: Must Have — The spec states this is the "sole client-facing interface." Without it, the server mode is completely non-functional. This blocks all server-mode A2A communication.
  • Parent Epic: #933 (A2A Protocol Compliance)

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: ca-project-owner

Issue triaged by project owner: - **State**: Verified - **Priority**: Critical — The ASGI server is the sole client-facing interface per spec §Server Presentation Layer. Without the A2A JSON-RPC endpoint and Agent Card, no external client can communicate with the server at all. - **Milestone**: v3.6.0 (already set, correct — A2A module rename and standardization is in M7 scope) - **Story Points**: 5 — L — Requires adding two new ASGI endpoints, wiring to existing `A2aLocalFacade`, constructing Agent Card JSON with capability declarations, plus Behave and Robot Framework tests. Moderate complexity with clear implementation path. - **MoSCoW**: Must Have — The spec states this is the "sole client-facing interface." Without it, the server mode is completely non-functional. This blocks all server-mode A2A communication. - **Parent Epic**: #933 (A2A Protocol Compliance) --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner
Author
Owner

Transition of issue #3533 from State/Unverified to State/Verified completed.

Preconditions checked: none required for this transition (not transitioning from Paused).

Changes made:

  • Removed old state label: State/Unverified
  • Added new state label: State/Verified

Current labels on the issue: Priority/Critical, State/Verified, Type/Bug
Milestone remains: v3.6.0

If you want me to also perform any validation steps or update subtasks/DoD references accordingly, I can proceed.


Automated by CleverAgents Bot
Supervisor: Implementation | Agent: ca-issue-state-updater

Transition of issue #3533 from State/Unverified to State/Verified completed. Preconditions checked: none required for this transition (not transitioning from Paused). Changes made: - Removed old state label: State/Unverified - Added new state label: State/Verified Current labels on the issue: Priority/Critical, State/Verified, Type/Bug Milestone remains: v3.6.0 If you want me to also perform any validation steps or update subtasks/DoD references accordingly, I can proceed. --- **Automated by CleverAgents Bot** Supervisor: Implementation | Agent: ca-issue-state-updater
Author
Owner

Issue verified and triaged:

  • Priority: Critical — the ASGI server has no A2A endpoint and no Agent Card, making the entire server mode non-functional.
  • Milestone: v3.6.0 (already assigned)
  • Story Points: 5 (L) — requires implementing JSON-RPC endpoint, Agent Card endpoint, and wiring to A2aLocalFacade.
  • Parent Epic: #933 (already linked)
  • Next step: This issue is now ready for implementation.

Automated by CleverAgents Bot
Supervisor: Human Liaison | Agent: ca-human-liaison

Issue verified and triaged: - **Priority**: Critical — the ASGI server has no A2A endpoint and no Agent Card, making the entire server mode non-functional. - **Milestone**: v3.6.0 (already assigned) - **Story Points**: 5 (L) — requires implementing JSON-RPC endpoint, Agent Card endpoint, and wiring to A2aLocalFacade. - **Parent Epic**: #933 (already linked) - **Next step**: This issue is now ready for implementation. --- **Automated by CleverAgents Bot** Supervisor: Human Liaison | Agent: ca-human-liaison
freemo removed this from the v3.6.0 milestone 2026-04-06 23:43:18 +00:00
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Reference
cleveragents/cleveragents-core#3533
No description provided.