UAT: Agent Card discovery endpoint (`/.well-known/agent.json`) not implemented in ASGI app — spec requires it for A2A capability discovery #2570

New issue

Closed

opened 2026-04-03 18:56:39 +00:00 by freemo · 1 comment

freemo commented

2026-04-03 18:56:39 +00:00

Owner

Bug Report

Feature Area

Standards Alignment — A2A Protocol / Agent Card Discovery

What Was Tested

Code-level analysis of src/cleveragents/a2a/asgi.py — the ASGI application serving HTTP endpoints.

Expected Behavior (from spec)

The specification (§Server and Client Architecture) states:

Agent Card discovery: 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 connection lifecycle follows the A2A standard: the client discovers the server's Agent Card (capability exchange), authenticates via the declared HTTP auth scheme, and begins sending message/send or message/stream requests.

The A2A standard requires the server to serve an Agent Card at /.well-known/agent.json that declares:

Supported A2A operations
_cleveragents/ extension methods
Authentication schemes (OAuth2, API key, etc.)
Server capabilities

Actual Behavior (from code)

In src/cleveragents/a2a/asgi.py, the ASGI app only handles these paths:

_KNOWN_PATHS: frozenset[str] = frozenset({"/", "/live", "/ready", "/health"})

There is no handler for /.well-known/agent.json. Any request to this path returns a 404 Not Found response.

# No handler for /.well-known/agent.json
# GET /.well-known/agent.json → 404 {"error": "not found"}

Impact

A2A discovery broken: No A2A client can discover the server's capabilities without the Agent Card.
Authentication broken: Clients cannot learn which auth schemes the server supports.
Extension method discovery broken: Third-party clients cannot discover the _cleveragents/ extension methods.
Ecosystem interoperability broken: The A2A ecosystem relies on Agent Card discovery for plug-and-play interoperability.

Code Location

src/cleveragents/a2a/asgi.py — _KNOWN_PATHS frozenset and app() function

Steps to Reproduce

# Start the ASGI app (e.g., with uvicorn)
# Then:
curl http://localhost:8000/.well-known/agent.json
# Returns: {"error": "not found"} with HTTP 404
# Expected: Agent Card JSON with capabilities, extensions, auth schemes

Fix Required

Add a GET /.well-known/agent.json handler to the ASGI app that returns an Agent Card JSON document:

{
  "name": "CleverAgents",
  "version": "1.0",
  "description": "CleverAgents AI orchestration platform",
  "url": "https://...",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false
  },
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain"],
  "skills": [],
  "extensions": [
    {"uri": "_cleveragents/plan", "description": "Plan lifecycle management"},
    {"uri": "_cleveragents/registry", "description": "Registry operations"},
    ...
  ],
  "authentication": {
    "schemes": ["Bearer"]
  }
}

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

## Bug Report ### Feature Area Standards Alignment — A2A Protocol / Agent Card Discovery ### What Was Tested Code-level analysis of `src/cleveragents/a2a/asgi.py` — the ASGI application serving HTTP endpoints. ### Expected Behavior (from spec) The specification (§Server and Client Architecture) states: > **Agent Card discovery**: 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 connection lifecycle follows the A2A standard: the client discovers the server's Agent Card (capability exchange), authenticates via the declared HTTP auth scheme, and begins sending `message/send` or `message/stream` requests. The A2A standard requires the server to serve an Agent Card at `/.well-known/agent.json` that declares: - Supported A2A operations - `_cleveragents/` extension methods - Authentication schemes (OAuth2, API key, etc.) - Server capabilities ### Actual Behavior (from code) In `src/cleveragents/a2a/asgi.py`, the ASGI app only handles these paths: ```python _KNOWN_PATHS: frozenset[str] = frozenset({"/", "/live", "/ready", "/health"}) ``` There is no handler for `/.well-known/agent.json`. Any request to this path returns a `404 Not Found` response. ```python # No handler for /.well-known/agent.json # GET /.well-known/agent.json → 404 {"error": "not found"} ``` ### Impact - **A2A discovery broken**: No A2A client can discover the server's capabilities without the Agent Card. - **Authentication broken**: Clients cannot learn which auth schemes the server supports. - **Extension method discovery broken**: Third-party clients cannot discover the `_cleveragents/` extension methods. - **Ecosystem interoperability broken**: The A2A ecosystem relies on Agent Card discovery for plug-and-play interoperability. ### Code Location - `src/cleveragents/a2a/asgi.py` — `_KNOWN_PATHS` frozenset and `app()` function ### Steps to Reproduce ```bash # Start the ASGI app (e.g., with uvicorn) # Then: curl http://localhost:8000/.well-known/agent.json # Returns: {"error": "not found"} with HTTP 404 # Expected: Agent Card JSON with capabilities, extensions, auth schemes ``` ### Fix Required Add a `GET /.well-known/agent.json` handler to the ASGI app that returns an Agent Card JSON document: ```json { "name": "CleverAgents", "version": "1.0", "description": "CleverAgents AI orchestration platform", "url": "https://...", "capabilities": { "streaming": true, "pushNotifications": false }, "defaultInputModes": ["text/plain"], "defaultOutputModes": ["text/plain"], "skills": [], "extensions": [ {"uri": "_cleveragents/plan", "description": "Plan lifecycle management"}, {"uri": "_cleveragents/registry", "description": "Registry operations"}, ... ], "authentication": { "schemes": ["Bearer"] } } ``` --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-uat-tester

freemo commented

2026-04-03 19:03:00 +00:00

Author

Owner

Closing as duplicate of #2456. Both issues describe the same bug: Agent Card discovery endpoint (/.well-known/agent.json) not implemented in the ASGI app. Issue #2456 was filed first.

Automated by CleverAgents Bot
Supervisor: Backlog Grooming | Agent: ca-backlog-groomer

Closing as duplicate of #2456. Both issues describe the same bug: Agent Card discovery endpoint (`/.well-known/agent.json`) not implemented in the ASGI app. Issue #2456 was filed first. --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: ca-backlog-groomer

freemo closed this issue

2026-04-03 19:03:01 +00:00

freemo referenced this issue

2026-04-03 19:03:22 +00:00

[CA-GROOMER] Backlog Groomer — Session State (groomer-1) #2386