UAT: Agent Card capability discovery endpoint not implemented — spec requires /.well-known/agent.json for A2A capability negotiation #2168

Closed
opened 2026-04-03 04:41:31 +00:00 by freemo · 2 comments
Owner

Metadata

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

Background

The specification states:

"Agent Card discovery | Client → Server | Capability negotiation — advertises supported _cleveragents/ extensions, automation profiles, tool registries"

The A2A standard requires servers to expose an Agent Card at /.well-known/agent.json that declares supported A2A operations, supported _cleveragents/ extension methods, authentication schemes (OAuth2, API key), and server capabilities. This is a prerequisite for any A2A capability negotiation before a client can connect.

Actual behavior: The cleveragents.a2a.asgi:app ASGI application has no Agent Card endpoint. There is no /.well-known/agent.json route, no AgentCard model, and no capability discovery mechanism anywhere in the codebase. The A2aLocalFacade.list_operations() method exists but is not exposed via HTTP. The A2aVersionNegotiator exists but is not wired to any HTTP endpoint.

Code location: src/cleveragents/a2a/asgi.py — no Agent Card endpoint exists. src/cleveragents/a2a/ — no AgentCard model or capability discovery module.

Severity: High — without an Agent Card, external A2A clients cannot discover what operations the server supports, what authentication to use, or what extensions are available.

Subtasks

  • Define AgentCard Pydantic model in src/cleveragents/a2a/models.py (or a new src/cleveragents/a2a/agent_card.py) with fields for supported operations, extension methods, and authentication schemes
  • Implement GET /.well-known/agent.json route in src/cleveragents/a2a/asgi.py that returns a serialised AgentCard JSON response
  • Wire A2aLocalFacade.list_operations() output into the AgentCard supported operations list
  • Wire A2aVersionNegotiator supported versions into the AgentCard response
  • Populate _cleveragents/ extension method list from the registered operation registry
  • Populate authentication schemes (OAuth2, API key) in the AgentCard response
  • Write Behave scenarios (features/) covering: endpoint returns 200, correct Content-Type, required fields present, extension methods listed, auth schemes listed
  • Write Robot Framework integration test (robot/) verifying the live ASGI app serves a valid Agent Card
  • Ensure all new code is statically typed and passes nox -e typecheck
  • Run nox (all default sessions) and fix any failures
  • Verify coverage ≥ 97% via nox -e coverage_report

Definition of Done

  • GET /.well-known/agent.json returns HTTP 200 with Content-Type: application/json
  • Response body is a valid AgentCard JSON document containing: supported A2A operations, all registered _cleveragents/ extension methods, supported authentication schemes, and server version information
  • A2aLocalFacade.list_operations() output is reflected in the Agent Card
  • A2aVersionNegotiator supported versions are reflected in the Agent Card
  • All Behave unit test scenarios pass (nox -e unit_tests)
  • Robot Framework integration test passes (nox -e integration_tests)
  • No # type: ignore suppressions; Pyright passes cleanly (nox -e typecheck)
  • All nox stages pass
  • Coverage >= 97%

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

## Metadata - **Branch**: `fix/a2a-agent-card-capability-discovery-endpoint` - **Commit Message**: `fix(a2a): implement Agent Card capability discovery endpoint at /.well-known/agent.json` - **Milestone**: v3.7.0 - **Parent Epic**: #933 ## Background The specification states: > "Agent Card discovery | Client → Server | Capability negotiation — advertises supported `_cleveragents/` extensions, automation profiles, tool registries" The A2A standard requires servers to expose an Agent Card at `/.well-known/agent.json` that declares supported A2A operations, supported `_cleveragents/` extension methods, authentication schemes (OAuth2, API key), and server capabilities. This is a prerequisite for any A2A capability negotiation before a client can connect. **Actual behavior**: The `cleveragents.a2a.asgi:app` ASGI application has no Agent Card endpoint. There is no `/.well-known/agent.json` route, no `AgentCard` model, and no capability discovery mechanism anywhere in the codebase. The `A2aLocalFacade.list_operations()` method exists but is not exposed via HTTP. The `A2aVersionNegotiator` exists but is not wired to any HTTP endpoint. **Code location**: `src/cleveragents/a2a/asgi.py` — no Agent Card endpoint exists. `src/cleveragents/a2a/` — no `AgentCard` model or capability discovery module. **Severity**: High — without an Agent Card, external A2A clients cannot discover what operations the server supports, what authentication to use, or what extensions are available. ## Subtasks - [ ] Define `AgentCard` Pydantic model in `src/cleveragents/a2a/models.py` (or a new `src/cleveragents/a2a/agent_card.py`) with fields for supported operations, extension methods, and authentication schemes - [ ] Implement `GET /.well-known/agent.json` route in `src/cleveragents/a2a/asgi.py` that returns a serialised `AgentCard` JSON response - [ ] Wire `A2aLocalFacade.list_operations()` output into the `AgentCard` supported operations list - [ ] Wire `A2aVersionNegotiator` supported versions into the `AgentCard` response - [ ] Populate `_cleveragents/` extension method list from the registered operation registry - [ ] Populate authentication schemes (OAuth2, API key) in the `AgentCard` response - [ ] Write Behave scenarios (`features/`) covering: endpoint returns 200, correct Content-Type, required fields present, extension methods listed, auth schemes listed - [ ] Write Robot Framework integration test (`robot/`) verifying the live ASGI app serves a valid Agent Card - [ ] Ensure all new code is statically typed and passes `nox -e typecheck` - [ ] Run `nox` (all default sessions) and fix any failures - [ ] Verify coverage ≥ 97% via `nox -e coverage_report` ## Definition of Done - [ ] `GET /.well-known/agent.json` returns HTTP 200 with `Content-Type: application/json` - [ ] Response body is a valid `AgentCard` JSON document containing: supported A2A operations, all registered `_cleveragents/` extension methods, supported authentication schemes, and server version information - [ ] `A2aLocalFacade.list_operations()` output is reflected in the Agent Card - [ ] `A2aVersionNegotiator` supported versions are reflected in the Agent Card - [ ] All Behave unit test scenarios pass (`nox -e unit_tests`) - [ ] Robot Framework integration test passes (`nox -e integration_tests`) - [ ] No `# type: ignore` suppressions; Pyright passes cleanly (`nox -e typecheck`) - [ ] All nox stages pass - [ ] Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator
freemo added this to the v3.7.0 milestone 2026-04-03 04:41:35 +00:00
Author
Owner

Potential overlap with #1994 ("BUG-HUNT: [spec-alignment] Missing Agent Card implementation"). Both issues report the absence of Agent Card functionality. However, #1994 is scoped to v3.8.0 (Server Implementation) while this issue is scoped to v3.7.0. #1994 focuses on the Pydantic model and HTTP endpoint, while this issue additionally covers capability negotiation and version negotiation wiring.

Triaging as a distinct issue since it covers additional scope (capability negotiation, version negotiation) beyond #1994's scope.

Issue triaged by project owner:

  • State: Verified
  • Priority: High (confirmed) — Agent Card is required for A2A capability negotiation.
  • Milestone: v3.7.0 (confirmed — A2A Protocol Compliance Epic #933)
  • MoSCoW: Should Have — Important for A2A compliance but server mode is deferred. Related to #1994.
  • Parent Epic: #933 (confirmed correct)

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

**Potential overlap with #1994** ("BUG-HUNT: [spec-alignment] Missing Agent Card implementation"). Both issues report the absence of Agent Card functionality. However, #1994 is scoped to v3.8.0 (Server Implementation) while this issue is scoped to v3.7.0. #1994 focuses on the Pydantic model and HTTP endpoint, while this issue additionally covers capability negotiation and version negotiation wiring. Triaging as a distinct issue since it covers additional scope (capability negotiation, version negotiation) beyond #1994's scope. Issue triaged by project owner: - **State**: Verified - **Priority**: High (confirmed) — Agent Card is required for A2A capability negotiation. - **Milestone**: v3.7.0 (confirmed — A2A Protocol Compliance Epic #933) - **MoSCoW**: Should Have — Important for A2A compliance but server mode is deferred. Related to #1994. - **Parent Epic**: #933 (confirmed correct) --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner
Author
Owner

Closing as duplicate of #1767. Both issues describe the same bug: the ASGI app is missing the Agent Card endpoint (/.well-known/agent.json). Issue #1767 was filed earlier (milestone v3.4.0) and is the canonical bug report. Issue #1994 is also related.

Please track this work in #1767.


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

Closing as duplicate of #1767. Both issues describe the same bug: the ASGI app is missing the Agent Card endpoint (`/.well-known/agent.json`). Issue #1767 was filed earlier (milestone v3.4.0) and is the canonical bug report. Issue #1994 is also related. Please track this work in #1767. --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: ca-backlog-groomer
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#2168
No description provided.