UAT: ASGI app missing /.well-known/agent.json Agent Card endpoint — A2A server mode discovery is broken #2456

Open
opened 2026-04-03 18:27:27 +00:00 by freemo · 1 comment
Owner

Metadata

  • Branch: fix/a2a-agent-card-endpoint
  • Commit Message: fix(a2a): add /.well-known/agent.json Agent Card endpoint to ASGI app
  • Milestone: v3.8.0
  • Parent Epic: #690

Summary

The ASGI application (src/cleveragents/a2a/asgi.py) is missing the /.well-known/agent.json endpoint required by the A2A standard for Agent Card discovery. Without this endpoint, A2A clients cannot discover the server's capabilities, supported extension methods, or authentication schemes — making server mode interoperability impossible.

What Was Tested

  • Code analysis of src/cleveragents/a2a/asgi.py
  • Specification review of A2A Agent Card discovery requirements

Expected Behavior (from spec)

Per docs/specification.md (lines 23568-23569, 43339-43341):

"Client fetches the server's Agent Card (via /.well-known/agent.json or configured URL). The Agent Card declares supported capabilities, _cleveragents extensions, and authentication schemes."

The Agent Card must:

  1. Be served at GET /.well-known/agent.json
  2. Declare supported A2A capabilities and _cleveragents/ extension methods
  3. Declare authentication schemes (OAuth2, API key, Bearer token)
  4. Include _cleveragents.version in the extensions section
  5. Declare the A2A protocol version (also sent via A2A-Version HTTP header)

Actual Behavior

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

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

GET /.well-known/agent.json returns 404 {"error":"not found"}.

Code Location

src/cleveragents/a2a/asgi.py — the _KNOWN_PATHS frozenset and app() function do not include /.well-known/agent.json.

Steps to Reproduce

  1. Start the ASGI server: python -m cleveragents server serve --app cleveragents.a2a.asgi:app
  2. Send: GET /.well-known/agent.json
  3. Observe: 404 {"error":"not found"}

Impact

Without the Agent Card endpoint, A2A clients cannot:

  • Discover what capabilities the server supports
  • Know which _cleveragents/ extension methods are available
  • Determine the correct authentication scheme
  • Perform version negotiation

This blocks all A2A server mode interoperability with third-party clients and the A2A ecosystem.

Subtasks

  • Add /.well-known/agent.json to _KNOWN_PATHS in asgi.py
  • Implement GET /.well-known/agent.json handler returning a valid Agent Card JSON
  • Agent Card must include: name, description, version, capabilities, extensions (with _cleveragents.version), authentication
  • Add BDD test for the Agent Card endpoint
  • Verify Agent Card response is valid JSON conforming to A2A spec

Definition of Done

  • GET /.well-known/agent.json returns HTTP 200 with a valid Agent Card JSON body
  • Agent Card declares all supported _cleveragents/ extension methods
  • Agent Card declares authentication schemes
  • BDD test covers the endpoint
  • All CI checks pass
  • All nox stages pass
  • Coverage >= 97%

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

## Metadata - **Branch**: `fix/a2a-agent-card-endpoint` - **Commit Message**: `fix(a2a): add /.well-known/agent.json Agent Card endpoint to ASGI app` - **Milestone**: v3.8.0 - **Parent Epic**: #690 ## Summary The ASGI application (`src/cleveragents/a2a/asgi.py`) is missing the `/.well-known/agent.json` endpoint required by the A2A standard for Agent Card discovery. Without this endpoint, A2A clients cannot discover the server's capabilities, supported extension methods, or authentication schemes — making server mode interoperability impossible. ## What Was Tested - Code analysis of `src/cleveragents/a2a/asgi.py` - Specification review of A2A Agent Card discovery requirements ## Expected Behavior (from spec) Per `docs/specification.md` (lines 23568-23569, 43339-43341): > "Client fetches the server's Agent Card (via `/.well-known/agent.json` or configured URL). The Agent Card declares supported capabilities, `_cleveragents` extensions, and authentication schemes." The Agent Card must: 1. Be served at `GET /.well-known/agent.json` 2. Declare supported A2A capabilities and `_cleveragents/` extension methods 3. Declare authentication schemes (OAuth2, API key, Bearer token) 4. Include `_cleveragents.version` in the extensions section 5. Declare the A2A protocol version (also sent via `A2A-Version` HTTP header) ## Actual Behavior `src/cleveragents/a2a/asgi.py` only handles these paths: - `GET /` → `{"service":"cleveragents"}` - `GET /live` → `{"status":"alive"}` - `GET /ready` → `{"status":"ready"}` - `GET /health` → `{"status":"ok"}` `GET /.well-known/agent.json` returns `404 {"error":"not found"}`. ## Code Location `src/cleveragents/a2a/asgi.py` — the `_KNOWN_PATHS` frozenset and `app()` function do not include `/.well-known/agent.json`. ## Steps to Reproduce 1. Start the ASGI server: `python -m cleveragents server serve --app cleveragents.a2a.asgi:app` 2. Send: `GET /.well-known/agent.json` 3. Observe: `404 {"error":"not found"}` ## Impact Without the Agent Card endpoint, A2A clients cannot: - Discover what capabilities the server supports - Know which `_cleveragents/` extension methods are available - Determine the correct authentication scheme - Perform version negotiation This blocks all A2A server mode interoperability with third-party clients and the A2A ecosystem. ## Subtasks - [ ] Add `/.well-known/agent.json` to `_KNOWN_PATHS` in `asgi.py` - [ ] Implement `GET /.well-known/agent.json` handler returning a valid Agent Card JSON - [ ] Agent Card must include: `name`, `description`, `version`, `capabilities`, `extensions` (with `_cleveragents.version`), `authentication` - [ ] Add BDD test for the Agent Card endpoint - [ ] Verify Agent Card response is valid JSON conforming to A2A spec ## Definition of Done - [ ] `GET /.well-known/agent.json` returns HTTP 200 with a valid Agent Card JSON body - [ ] Agent Card declares all supported `_cleveragents/` extension methods - [ ] Agent Card declares authentication schemes - [ ] BDD test covers the endpoint - [ ] All CI checks pass - All nox stages pass - Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator
freemo added this to the v3.8.0 milestone 2026-04-03 18:27:31 +00:00
Author
Owner

Issue triaged by project owner:

  • State: Verified
  • Priority: High — Missing /.well-known/agent.json Agent Card endpoint means A2A server mode discovery is broken. Clients cannot discover the agent's capabilities.
  • MoSCoW: Must Have — The Agent Card is a core A2A protocol requirement for server discovery. Without it, the A2A server is not discoverable.

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

Issue triaged by project owner: - **State**: Verified - **Priority**: High — Missing `/.well-known/agent.json` Agent Card endpoint means A2A server mode discovery is broken. Clients cannot discover the agent's capabilities. - **MoSCoW**: Must Have — The Agent Card is a core A2A protocol requirement for server discovery. Without it, the A2A server is not discoverable. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner
freemo removed this from the v3.8.0 milestone 2026-04-06 20:59:03 +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#2456
No description provided.