cleveragents/cleveragents-core

Fork 3

UAT: ASGI app missing `/.well-known/agent.json` Agent Card discovery endpoint — A2A protocol compliance gap #2566

New issue

Open

opened 2026-04-03 18:55:52 +00:00 by freemo · 2 comments

freemo commented

2026-04-03 18:55:52 +00:00

Owner

Bug Report

What Was Tested

The ASGI application (src/cleveragents/a2a/asgi.py) was analyzed against the A2A protocol specification requirements for Agent Card discovery.

Expected Behavior (from spec)

The specification (§Server and Client Architecture, §Agent-to-Agent Protocol) explicitly requires Agent Card discovery:

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 spec states (§23568):

Client fetches the server's Agent Card (via /.well-known/agent.json or configured URL)

The spec also states (§23372):

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 Agent Card is the first step in the A2A connection lifecycle. Without it, clients cannot:

Discover supported capabilities and _cleveragents/ extensions
Determine the authentication scheme (OAuth2, API key, Bearer token)
Negotiate protocol versions

Actual Behavior

The ASGI app (src/cleveragents/a2a/asgi.py) only serves four paths:

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

Handlers:

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

GET /.well-known/agent.json returns 404 Not Found.

Any A2A-compliant client attempting to connect to the CleverAgents server will fail at the first step of the connection lifecycle because the Agent Card endpoint is absent.

Code Location

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

Steps to Reproduce

Start the server: agents server serve --host 127.0.0.1 --port 8000
Request the Agent Card: curl http://127.0.0.1:8000/.well-known/agent.json
Observe: {"error":"not found"} with HTTP 404

Impact

Critical for A2A protocol compliance. Without the Agent Card endpoint:

No A2A-compliant client can connect to the CleverAgents server
Authentication scheme discovery is impossible
Extension capability negotiation (_cleveragents/ methods) cannot occur
The server is not interoperable with the A2A ecosystem

Suggested Fix

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

Supported A2A protocol version
_cleveragents/ extension methods
Authentication schemes (Bearer token)
Server capabilities

Example minimal Agent Card:

{
  "name": "CleverAgents",
  "version": "1.0",
  "url": "https://agents.example.com",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false
  },
  "authentication": {
    "schemes": ["Bearer"]
  },
  "extensions": {
    "_cleveragents.version": "1.0",
    "_cleveragents.methods": ["_cleveragents/plan/use", "..."]
  }
}

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

## Bug Report ### What Was Tested The ASGI application (`src/cleveragents/a2a/asgi.py`) was analyzed against the A2A protocol specification requirements for Agent Card discovery. ### Expected Behavior (from spec) The specification (§Server and Client Architecture, §Agent-to-Agent Protocol) explicitly requires Agent Card discovery: > **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 spec states (§23568): > 1. Client fetches the server's Agent Card (via `/.well-known/agent.json` or configured URL) The spec also states (§23372): > 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 Agent Card is the **first step** in the A2A connection lifecycle. Without it, clients cannot: - Discover supported capabilities and `_cleveragents/` extensions - Determine the authentication scheme (OAuth2, API key, Bearer token) - Negotiate protocol versions ### Actual Behavior The ASGI app (`src/cleveragents/a2a/asgi.py`) only serves four paths: ```python _KNOWN_PATHS: frozenset[str] = frozenset({"/", "/live", "/ready", "/health"}) ``` Handlers: - `GET /` → `{"service":"cleveragents"}` - `GET /live` → `{"status":"alive"}` - `GET /ready` → `{"status":"ready"}` - `GET /health` → `{"status":"ok"}` **`GET /.well-known/agent.json` returns `404 Not Found`.** Any A2A-compliant client attempting to connect to the CleverAgents server will fail at the first step of the connection lifecycle because the Agent Card endpoint is absent. ### Code Location - `src/cleveragents/a2a/asgi.py` — `_KNOWN_PATHS` frozenset and `app()` function ### Steps to Reproduce 1. Start the server: `agents server serve --host 127.0.0.1 --port 8000` 2. Request the Agent Card: `curl http://127.0.0.1:8000/.well-known/agent.json` 3. Observe: `{"error":"not found"}` with HTTP 404 ### Impact **Critical for A2A protocol compliance.** Without the Agent Card endpoint: - No A2A-compliant client can connect to the CleverAgents server - Authentication scheme discovery is impossible - Extension capability negotiation (`_cleveragents/` methods) cannot occur - The server is not interoperable with the A2A ecosystem ### Suggested Fix Add a `/.well-known/agent.json` handler to the ASGI app that returns an Agent Card JSON document declaring: - Supported A2A protocol version - `_cleveragents/` extension methods - Authentication schemes (Bearer token) - Server capabilities Example minimal Agent Card: ```json { "name": "CleverAgents", "version": "1.0", "url": "https://agents.example.com", "capabilities": { "streaming": true, "pushNotifications": false }, "authentication": { "schemes": ["Bearer"] }, "extensions": { "_cleveragents.version": "1.0", "_cleveragents.methods": ["_cleveragents/plan/use", "..."] } } ``` --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-uat-tester

freemo added the

MoSCoW

Must have

label

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

freemo commented

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

Author

Owner

Issue triaged by project owner:

State: Verified
MoSCoW: Must Have — Critical spec compliance issue.

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

Issue triaged by project owner: - **State**: Verified - **MoSCoW**: Must Have — Critical spec compliance issue. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo referenced this issue

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

[UAT-SUPERVISOR] Progress Report — Cycle 1591 — v3.7.0 #2593

freemo added a new dependency

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

#2597 fix(ci): restore all CI quality gates to passing on master — no suppression, no bypasses

freemo added this to the v3.8.0 milestone

2026-04-04 19:11:33 +00:00

freemo added a new dependency

2026-04-04 19:11:46 +00:00

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

freemo commented

2026-04-04 19:11:51 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Critical — The Agent Card discovery endpoint (/.well-known/agent.json) is the first step in the A2A connection lifecycle per the specification. Without it, no A2A-compliant client can connect to the server, making the entire server mode non-functional for external clients.
Milestone: v3.8.0 (M9: Server Implementation)
MoSCoW: Must Have — The spec explicitly requires Agent Card discovery as part of the A2A protocol. This is a mandatory protocol compliance requirement, not optional.
Parent Epic: #933 (A2A Protocol Compliance — JSON-RPC 2.0 Framing, Standard Operations, and Extension Methods)

The existing Priority/Critical and MoSCoW/Must have labels are correct. This issue blocks A2A interoperability and should be prioritized within the server implementation milestone.

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Critical — The Agent Card discovery endpoint (`/.well-known/agent.json`) is the **first step** in the A2A connection lifecycle per the specification. Without it, no A2A-compliant client can connect to the server, making the entire server mode non-functional for external clients. - **Milestone**: v3.8.0 (M9: Server Implementation) - **MoSCoW**: Must Have — The spec explicitly requires Agent Card discovery as part of the A2A protocol. This is a mandatory protocol compliance requirement, not optional. - **Parent Epic**: #933 (A2A Protocol Compliance — JSON-RPC 2.0 Framing, Standard Operations, and Extension Methods) The existing Priority/Critical and MoSCoW/Must have labels are correct. This issue blocks A2A interoperability and should be prioritized within the server implementation milestone. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo referenced this issue

2026-04-04 21:02:37 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.7.0 — Session Tracker #2803

freemo removed a dependency

2026-04-14 22:18:56 +00:00

#2597 fix(ci): restore all CI quality gates to passing on master — no suppression, no bypasses