BUG-HUNT: [spec-alignment] Missing Agent Card implementation #1994

New issue

Open

opened 2026-04-03 00:32:38 +00:00 by freemo · 1 comment

freemo commented

2026-04-03 00:32:38 +00:00

Owner

Metadata

Branch: fix/a2a-agent-card-implementation
Commit Message: fix(a2a): implement Agent Card served at /.well-known/agent.json per ADR-047
Milestone: v3.8.0
Parent Epic: #933

Bug Report: [spec-alignment] — Missing Agent Card implementation

Severity Assessment

Impact: Without an Agent Card, other agents and clients cannot discover the capabilities of the CleverAgents agent, which is a fundamental feature of the A2A protocol.
Likelihood: High. The Agent Card is a core part of the A2A discovery mechanism.
Priority: High

Location

File: src/cleveragents/a2a

Description

ADR-047 specifies that CleverAgents will use Agent Cards for dynamic capability discovery. The Agent Card is a JSON metadata document served at /.well-known/agent.json that describes an agent's identity, capabilities, skills, supported protocol bindings, authentication requirements, and extensions.

The current implementation of the a2a module does not contain any code related to the Agent Card.

Evidence

There is no code in the src/cleveragents/a2a directory that implements the Agent Card functionality.

Expected Behavior

The a2a module should include an implementation of the Agent Card, including the ability to serve it at /.well-known/agent.json in server mode and provide it during initialization in local mode.

Actual Behavior

The Agent Card functionality is completely missing.

Suggested Fix

Implement the Agent Card functionality as described in ADR-047 and the A2A specification.

Subtasks

Implement AgentCard Pydantic model with all required fields (name, description, url, version, capabilities, skills, authentication, extensions)
Implement /.well-known/agent.json HTTP endpoint in the ASGI application (src/cleveragents/a2a/asgi.py)
Implement getExtendedAgentCard A2A extension method for dynamic capability discovery
Provide Agent Card during initialization in local (stdio) mode
Tests (Behave): Add BDD scenarios for Agent Card endpoint and content validation
Tests (Robot): Add integration tests for Agent Card HTTP endpoint
Verify coverage >= 97% via nox -s coverage_report
Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly (fix(a2a): implement Agent Card served at /.well-known/agent.json per ADR-047), followed by a blank line, then additional lines providing relevant details about the implementation.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly (fix/a2a-agent-card-implementation).
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.
All nox stages pass
Coverage >= 97%

Automated by CleverAgents Bot
Supervisor: Bug Hunting | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/a2a-agent-card-implementation` - **Commit Message**: `fix(a2a): implement Agent Card served at /.well-known/agent.json per ADR-047` - **Milestone**: v3.8.0 - **Parent Epic**: #933 ## Bug Report: [spec-alignment] — Missing Agent Card implementation ### Severity Assessment - **Impact**: Without an Agent Card, other agents and clients cannot discover the capabilities of the CleverAgents agent, which is a fundamental feature of the A2A protocol. - **Likelihood**: High. The Agent Card is a core part of the A2A discovery mechanism. - **Priority**: High ### Location - **File**: `src/cleveragents/a2a` ### Description ADR-047 specifies that CleverAgents will use Agent Cards for dynamic capability discovery. The Agent Card is a JSON metadata document served at `/.well-known/agent.json` that describes an agent's identity, capabilities, skills, supported protocol bindings, authentication requirements, and extensions. The current implementation of the `a2a` module does not contain any code related to the Agent Card. ### Evidence There is no code in the `src/cleveragents/a2a` directory that implements the Agent Card functionality. ### Expected Behavior The `a2a` module should include an implementation of the Agent Card, including the ability to serve it at `/.well-known/agent.json` in server mode and provide it during initialization in local mode. ### Actual Behavior The Agent Card functionality is completely missing. ### Suggested Fix Implement the Agent Card functionality as described in ADR-047 and the A2A specification. ### Category spec-alignment ## Subtasks - [ ] Implement `AgentCard` Pydantic model with all required fields (name, description, url, version, capabilities, skills, authentication, extensions) - [ ] Implement `/.well-known/agent.json` HTTP endpoint in the ASGI application (`src/cleveragents/a2a/asgi.py`) - [ ] Implement `getExtendedAgentCard` A2A extension method for dynamic capability discovery - [ ] Provide Agent Card during initialization in local (stdio) mode - [ ] Tests (Behave): Add BDD scenarios for Agent Card endpoint and content validation - [ ] Tests (Robot): Add integration tests for Agent Card HTTP endpoint - [ ] Verify coverage >= 97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly (`fix(a2a): implement Agent Card served at /.well-known/agent.json per ADR-047`), followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly (`fix/a2a-agent-card-implementation`). - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. - All nox stages pass - Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: Bug Hunting | Agent: ca-new-issue-creator

freemo added this to the v3.8.0 milestone

2026-04-03 00:32:56 +00:00

freemo commented

2026-04-03 02:42:26 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: High — The Agent Card is a fundamental component of the A2A protocol discovery mechanism (ADR-047). Without it, other agents cannot discover capabilities.
Milestone: v3.8.0 (Server Implementation — already assigned, confirmed correct since Agent Card is an A2A server feature)
MoSCoW: Should Have — While the Agent Card is essential for the A2A protocol, v3.8.0 has no deadline and the project should focus on M1-M6 milestones first (per milestone description). This is important for eventual server implementation but is not blocking current milestone work.
Parent Epic: #933 (already linked, confirmed correct)

The issue is well-scoped with clear subtasks covering the Pydantic model, HTTP endpoint, extension method, and local mode initialization. Valid and actionable.

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

Issue triaged by project owner: - **State**: Verified - **Priority**: High — The Agent Card is a fundamental component of the A2A protocol discovery mechanism (ADR-047). Without it, other agents cannot discover capabilities. - **Milestone**: v3.8.0 (Server Implementation — already assigned, confirmed correct since Agent Card is an A2A server feature) - **MoSCoW**: Should Have — While the Agent Card is essential for the A2A protocol, v3.8.0 has no deadline and the project should focus on M1-M6 milestones first (per milestone description). This is important for eventual server implementation but is not blocking current milestone work. - **Parent Epic**: #933 (already linked, confirmed correct) The issue is well-scoped with clear subtasks covering the Pydantic model, HTTP endpoint, extension method, and local mode initialization. Valid and actionable. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo referenced this issue

2026-04-03 04:45:20 +00:00

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

freemo referenced this issue

2026-04-03 04:46:59 +00:00

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