UAT: A2A Agent Card discovery endpoint is completely absent — spec requires /.well-known/agent.json for ecosystem interoperability #4077

Open
opened 2026-04-06 10:03:32 +00:00 by freemo · 0 comments
Owner

Metadata

  • Branch: feat/a2a-agent-card-discovery
  • Commit Message: feat(a2a): implement Agent Card discovery endpoint at /.well-known/agent.json
  • Milestone: (backlog — see note below)
  • Parent Epic: #933 (Epic: A2A Protocol Compliance — JSON-RPC 2.0 Framing, Standard Operations, and Extension Methods)

Bug Report

What was tested: A2A Agent Card discovery endpoint implementation against the specification

Expected behavior (from spec, section "Standards Alignment" and "Server and Client Architecture"):

The spec states that CleverAgents adopts the A2A standard which provides "Agent Card-based capability discovery". The A2A standard requires a /.well-known/agent.json endpoint that serves an Agent Card describing the agent's capabilities, supported operations, and extension methods.

The spec explicitly states:

"Standard A2A operations handle agent messaging (message/send, message/stream), task lifecycle, streaming updates, and Agent Card-based discovery."

"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."

"Agent Card served at discovery endpoint" (in the server presentation layer description)

The Agent Card is essential for:

  1. Third-party clients discovering CleverAgents capabilities
  2. IDE plugins discovering available extension methods
  3. Ecosystem interoperability with other A2A-compliant agents

Actual behavior (from code analysis):

The ASGI app (src/cleveragents/a2a/asgi.py) only handles these paths:

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

There is NO /.well-known/agent.json endpoint. Searching the entire codebase for agent_card, AgentCard, agent.card, or well-known returns zero results related to A2A Agent Card serving.

Code location:

  • src/cleveragents/a2a/asgi.py_KNOWN_PATHS frozenset (line 24) and app() function — no /.well-known/agent.json path

Steps to reproduce:

  1. Start the server: agents server serve
  2. Request GET /.well-known/agent.json
  3. Observe: 404 response — Agent Card endpoint does not exist

Severity: High — without Agent Card discovery, CleverAgents cannot participate in the A2A ecosystem. Third-party clients and IDE plugins cannot discover the server's capabilities, defeating the interoperability goal of adopting the A2A standard.

Subtasks

  • Define AgentCard model with required A2A fields (name, description, version, capabilities, extension methods)
  • Implement /.well-known/agent.json endpoint in the ASGI app
  • Populate Agent Card with all supported _cleveragents/* extension methods
  • Populate Agent Card with standard A2A operations (message/send, message/stream)
  • Add unit tests (Behave scenarios) for Agent Card content
  • Add integration tests (Robot Framework) for endpoint availability

Definition of Done

  • GET /.well-known/agent.json returns a valid A2A Agent Card
  • Agent Card includes all supported extension methods
  • Agent Card includes standard A2A operations
  • Agent Card version matches the CleverAgents version
  • All existing server tests continue to pass
  • New Behave scenarios cover Agent Card content validation
  • Pyright type checking passes with no suppressions
  • All nox stages pass
  • Coverage >= 97%

Backlog note: This issue was discovered during autonomous operation
on milestone v3.4.0. It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.


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

## Metadata - **Branch**: `feat/a2a-agent-card-discovery` - **Commit Message**: `feat(a2a): implement Agent Card discovery endpoint at /.well-known/agent.json` - **Milestone**: (backlog — see note below) - **Parent Epic**: #933 (Epic: A2A Protocol Compliance — JSON-RPC 2.0 Framing, Standard Operations, and Extension Methods) ## Bug Report **What was tested:** A2A Agent Card discovery endpoint implementation against the specification **Expected behavior (from spec, section "Standards Alignment" and "Server and Client Architecture"):** The spec states that CleverAgents adopts the A2A standard which provides "**Agent Card**-based capability discovery". The A2A standard requires a `/.well-known/agent.json` endpoint that serves an Agent Card describing the agent's capabilities, supported operations, and extension methods. The spec explicitly states: > "Standard A2A operations handle agent messaging (`message/send`, `message/stream`), task lifecycle, streaming updates, and **Agent Card**-based discovery." > "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." > "Agent Card served at discovery endpoint" (in the server presentation layer description) The Agent Card is essential for: 1. Third-party clients discovering CleverAgents capabilities 2. IDE plugins discovering available extension methods 3. Ecosystem interoperability with other A2A-compliant agents **Actual behavior (from code analysis):** The ASGI app (`src/cleveragents/a2a/asgi.py`) only handles these paths: - `GET /` → `{"service":"cleveragents"}` - `GET /live` → `{"status":"alive"}` - `GET /ready` → `{"status":"ready"}` - `GET /health` → `{"status":"ok"}` There is NO `/.well-known/agent.json` endpoint. Searching the entire codebase for `agent_card`, `AgentCard`, `agent.card`, or `well-known` returns zero results related to A2A Agent Card serving. **Code location:** - `src/cleveragents/a2a/asgi.py` — `_KNOWN_PATHS` frozenset (line 24) and `app()` function — no `/.well-known/agent.json` path **Steps to reproduce:** 1. Start the server: `agents server serve` 2. Request `GET /.well-known/agent.json` 3. Observe: 404 response — Agent Card endpoint does not exist **Severity:** High — without Agent Card discovery, CleverAgents cannot participate in the A2A ecosystem. Third-party clients and IDE plugins cannot discover the server's capabilities, defeating the interoperability goal of adopting the A2A standard. ## Subtasks - [ ] Define `AgentCard` model with required A2A fields (name, description, version, capabilities, extension methods) - [ ] Implement `/.well-known/agent.json` endpoint in the ASGI app - [ ] Populate Agent Card with all supported `_cleveragents/*` extension methods - [ ] Populate Agent Card with standard A2A operations (`message/send`, `message/stream`) - [ ] Add unit tests (Behave scenarios) for Agent Card content - [ ] Add integration tests (Robot Framework) for endpoint availability ## Definition of Done - [ ] `GET /.well-known/agent.json` returns a valid A2A Agent Card - [ ] Agent Card includes all supported extension methods - [ ] Agent Card includes standard A2A operations - [ ] Agent Card version matches the CleverAgents version - [ ] All existing server tests continue to pass - [ ] New Behave scenarios cover Agent Card content validation - [ ] Pyright type checking passes with no suppressions - [ ] All nox stages pass - [ ] Coverage >= 97% > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.4.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator
HAL9000 added this to the v3.5.0 milestone 2026-04-09 03:11: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#4077
No description provided.