UAT: A2A Agent Card discovery endpoint (/.well-known/agent.json) not implemented — blocks server-mode client authentication and capability negotiation #3595

Open
opened 2026-04-05 20:14:33 +00:00 by freemo · 0 comments
Owner

Metadata

  • Branch: fix/a2a-agent-card-discovery
  • Commit Message: feat(a2a): implement Agent Card discovery endpoint at /.well-known/agent.json
  • Milestone: v3.6.0
  • Parent Epic: #366

Background

Per docs/specification.md (lines 23420, 23455, 23566-23579, 43372-43380), the A2A protocol requires an Agent Card for capability discovery and authentication:

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.

Authentication follows the A2A standard Agent Card-based discovery:

  1. Client fetches the server's Agent Card (via /.well-known/agent.json or configured URL)
  2. Agent Card declares supported authentication schemes (OAuth2, API key, Bearer token)

The spec also states (line 23578-23579):

  • A2A protocol version is declared in the Agent Card and sent via the A2A-Version HTTP header
  • CleverAgents extension version is declared in the Agent Card's extensions section under _cleveragents.version

Current Behavior

The ASGI application in src/cleveragents/a2a/asgi.py only serves health/readiness endpoints (/live, /ready, /health, /). There is no /.well-known/agent.json endpoint.

The A2aLocalFacade in src/cleveragents/a2a/facade.py has no Agent Card model or generation logic.

There is no AgentCard model anywhere in the codebase (grep -r "AgentCard\|agent_card\|agent.json" src/ returns no results).

Expected Behavior

Per the specification, the server must expose:

  1. GET /.well-known/agent.json — returns the Agent Card JSON document
  2. The Agent Card must declare:
    • name: "CleverAgents"
    • version: current server version
    • capabilities: list of supported _cleveragents/ extension methods
    • authentication: supported auth schemes (OAuth2, API key, Bearer token)
    • extensions._cleveragents.version: CleverAgents extension version

Without the Agent Card, server-mode clients cannot:

  • Discover what operations the server supports
  • Authenticate (auth schemes are declared in the Agent Card)
  • Negotiate protocol versions

Impact

This is a critical gap for server-mode operation. Without Agent Card discovery, no external A2A client can connect to a CleverAgents server. The spec states this is the sole communication protocol for all client-server interaction.

Code Locations

  • src/cleveragents/a2a/asgi.py — ASGI app missing /.well-known/agent.json route
  • src/cleveragents/a2a/facade.py — no Agent Card model or generation
  • src/cleveragents/a2a/versioning.py — version info exists but not exposed via Agent Card

Subtasks

  • Create AgentCard Pydantic model in src/cleveragents/a2a/models.py with all required fields
  • Implement AgentCardGenerator that builds the card from registered operations and version info
  • Add GET /.well-known/agent.json route to src/cleveragents/a2a/asgi.py
  • Populate Agent Card with all supported _cleveragents/ extension methods from A2aLocalFacade
  • Include _cleveragents.version in extensions section
  • Write Behave unit tests for AgentCard model and generator
  • Write integration test verifying /.well-known/agent.json returns valid JSON
  • Verify all nox stages pass

Definition of Done

  • GET /.well-known/agent.json returns a valid Agent Card JSON document
  • Agent Card includes all required fields per A2A spec
  • Unit and integration tests 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-discovery` - **Commit Message**: `feat(a2a): implement Agent Card discovery endpoint at /.well-known/agent.json` - **Milestone**: v3.6.0 - **Parent Epic**: #366 ## Background Per `docs/specification.md` (lines 23420, 23455, 23566-23579, 43372-43380), the A2A protocol requires an **Agent Card** for capability discovery and authentication: > 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. > Authentication follows the A2A standard Agent Card-based discovery: > 1. Client fetches the server's Agent Card (via `/.well-known/agent.json` or configured URL) > 2. Agent Card declares supported authentication schemes (OAuth2, API key, Bearer token) The spec also states (line 23578-23579): > - A2A protocol version is declared in the Agent Card and sent via the `A2A-Version` HTTP header > - CleverAgents extension version is declared in the Agent Card's extensions section under `_cleveragents.version` ## Current Behavior The ASGI application in `src/cleveragents/a2a/asgi.py` only serves health/readiness endpoints (`/live`, `/ready`, `/health`, `/`). There is no `/.well-known/agent.json` endpoint. The `A2aLocalFacade` in `src/cleveragents/a2a/facade.py` has no Agent Card model or generation logic. There is no `AgentCard` model anywhere in the codebase (`grep -r "AgentCard\|agent_card\|agent.json" src/` returns no results). ## Expected Behavior Per the specification, the server must expose: 1. `GET /.well-known/agent.json` — returns the Agent Card JSON document 2. The Agent Card must declare: - `name`: "CleverAgents" - `version`: current server version - `capabilities`: list of supported `_cleveragents/` extension methods - `authentication`: supported auth schemes (OAuth2, API key, Bearer token) - `extensions._cleveragents.version`: CleverAgents extension version Without the Agent Card, server-mode clients cannot: - Discover what operations the server supports - Authenticate (auth schemes are declared in the Agent Card) - Negotiate protocol versions ## Impact This is a critical gap for server-mode operation. Without Agent Card discovery, no external A2A client can connect to a CleverAgents server. The spec states this is the **sole** communication protocol for all client-server interaction. ## Code Locations - `src/cleveragents/a2a/asgi.py` — ASGI app missing `/.well-known/agent.json` route - `src/cleveragents/a2a/facade.py` — no Agent Card model or generation - `src/cleveragents/a2a/versioning.py` — version info exists but not exposed via Agent Card ## Subtasks - [ ] Create `AgentCard` Pydantic model in `src/cleveragents/a2a/models.py` with all required fields - [ ] Implement `AgentCardGenerator` that builds the card from registered operations and version info - [ ] Add `GET /.well-known/agent.json` route to `src/cleveragents/a2a/asgi.py` - [ ] Populate Agent Card with all supported `_cleveragents/` extension methods from `A2aLocalFacade` - [ ] Include `_cleveragents.version` in extensions section - [ ] Write Behave unit tests for `AgentCard` model and generator - [ ] Write integration test verifying `/.well-known/agent.json` returns valid JSON - [ ] Verify all nox stages pass ## Definition of Done - [ ] `GET /.well-known/agent.json` returns a valid Agent Card JSON document - [ ] Agent Card includes all required fields per A2A spec - [ ] Unit and integration tests 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.6.0 milestone 2026-04-05 20:14:37 +00:00
freemo removed this from the v3.6.0 milestone 2026-04-06 23:37:40 +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.

Blocks
#366 Epic: Post-MVP Deferred Work
cleveragents/cleveragents-core
Reference
cleveragents/cleveragents-core#3595
No description provided.