cleveragents/cleveragents-core

Fork 3

UAT: Agent Card endpoint (/.well-known/agent.json) not served by ASGI app — blocks A2A capability discovery #6113

New issue

Open

opened 2026-04-09 14:53:40 +00:00 by HAL9000 · 2 comments

HAL9000 commented

2026-04-09 14:53:40 +00:00

Owner

Bug Report

Feature Area: A2A Facade / ASGI App
Severity: Critical — blocks A2A capability discovery per ADR-047
Spec Reference: ADR-047 §Agent Discovery: Agent Card, §Server Presentation Layer

What Was Tested

Code-level analysis of src/cleveragents/a2a/asgi.py against ADR-047 requirements for Agent Card discovery.

Expected Behavior (from spec)

Per ADR-047 §Agent Discovery: Agent Card:

A2A introduces Agent Cards — JSON metadata documents that describe an agent's capabilities, skills, security requirements, and supported protocol bindings. The CleverAgents Agent Card is served at /.well-known/agent.json in server mode and declares:

Skills: Plan lifecycle management, registry CRUD, context assembly, entity sync, namespace management, diagnostics

Extensions: _cleveragents/ methods with URI urn:cleveragents:extensions:v1

Supported interfaces: jsonrpc (primary)

Security schemes: OAuth2, API key, or HTTP bearer

Per ADR-047 §Compliance:

Agent Card tests: Validate the generated Agent Card conforms to the A2A specification schema.
Discovery tests: Verify /.well-known/agent.json is served correctly and getExtendedAgentCard returns authenticated detail.

Actual Behavior

The ASGI app (src/cleveragents/a2a/asgi.py) only serves these endpoints:

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

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

# From asgi.py - _KNOWN_PATHS does not include /.well-known/agent.json
_KNOWN_PATHS: frozenset[str] = frozenset({"/", "/live", "/ready", "/health"})

Steps to Reproduce

Start the ASGI app (e.g., uvicorn cleveragents.a2a.asgi:app)
GET /.well-known/agent.json
Observe 404 response

Or via code analysis:

# asgi.py handles only: /, /live, /ready, /health
# /.well-known/agent.json → falls through to 404 handler

Code Location

src/cleveragents/a2a/asgi.py — _KNOWN_PATHS frozenset and route handlers

Impact

Without the Agent Card endpoint:

A2A clients cannot discover CleverAgents capabilities dynamically
Third-party A2A-compatible agents cannot interoperate with CleverAgents
The getExtendedAgentCard operation (also missing from the facade) cannot function
Authentication scheme discovery (OAuth2, API key, Bearer) is unavailable

This is a prerequisite for full A2A standard compliance per ADR-047.

Suggested Fix

Add /.well-known/agent.json route to asgi.py:

# In asgi.py
_KNOWN_PATHS: frozenset[str] = frozenset({"/", "/live", "/ready", "/health", "/.well-known/agent.json"})

# Add handler:
if method == "GET" and path == "/.well-known/agent.json":
    agent_card = _build_agent_card()
    await _send_response(send, status=200, body=json.dumps(agent_card).encode())
    return

Where _build_agent_card() returns the A2A-compliant Agent Card JSON declaring CleverAgents' skills, extensions, and security schemes.

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

## Bug Report **Feature Area**: A2A Facade / ASGI App **Severity**: Critical — blocks A2A capability discovery per ADR-047 **Spec Reference**: ADR-047 §Agent Discovery: Agent Card, §Server Presentation Layer --- ## What Was Tested Code-level analysis of `src/cleveragents/a2a/asgi.py` against ADR-047 requirements for Agent Card discovery. ## Expected Behavior (from spec) Per ADR-047 §Agent Discovery: Agent Card: > A2A introduces **Agent Cards** — JSON metadata documents that describe an agent's capabilities, skills, security requirements, and supported protocol bindings. The CleverAgents Agent Card is served at `/.well-known/agent.json` in server mode and declares: > - **Skills**: Plan lifecycle management, registry CRUD, context assembly, entity sync, namespace management, diagnostics > - **Extensions**: `_cleveragents/` methods with URI `urn:cleveragents:extensions:v1` > - **Supported interfaces**: `jsonrpc` (primary) > - **Security schemes**: OAuth2, API key, or HTTP bearer Per ADR-047 §Compliance: > **Agent Card tests**: Validate the generated Agent Card conforms to the A2A specification schema. > **Discovery tests**: Verify `/.well-known/agent.json` is served correctly and `getExtendedAgentCard` returns authenticated detail. ## Actual Behavior The ASGI app (`src/cleveragents/a2a/asgi.py`) only serves these endpoints: - `GET /` → `{"service":"cleveragents"}` - `GET /live` → `{"status":"alive"}` - `GET /ready` → `{"status":"ready"}` - `GET /health` → `{"status":"ok"}` `GET /.well-known/agent.json` returns **404 Not Found**. ```python # From asgi.py - _KNOWN_PATHS does not include /.well-known/agent.json _KNOWN_PATHS: frozenset[str] = frozenset({"/", "/live", "/ready", "/health"}) ``` ## Steps to Reproduce 1. Start the ASGI app (e.g., `uvicorn cleveragents.a2a.asgi:app`) 2. `GET /.well-known/agent.json` 3. Observe 404 response Or via code analysis: ```python # asgi.py handles only: /, /live, /ready, /health # /.well-known/agent.json → falls through to 404 handler ``` ## Code Location - `src/cleveragents/a2a/asgi.py` — `_KNOWN_PATHS` frozenset and route handlers ## Impact Without the Agent Card endpoint: 1. A2A clients cannot discover CleverAgents capabilities dynamically 2. Third-party A2A-compatible agents cannot interoperate with CleverAgents 3. The `getExtendedAgentCard` operation (also missing from the facade) cannot function 4. Authentication scheme discovery (OAuth2, API key, Bearer) is unavailable This is a prerequisite for full A2A standard compliance per ADR-047. ## Suggested Fix Add `/.well-known/agent.json` route to `asgi.py`: ```python # In asgi.py _KNOWN_PATHS: frozenset[str] = frozenset({"/", "/live", "/ready", "/health", "/.well-known/agent.json"}) # Add handler: if method == "GET" and path == "/.well-known/agent.json": agent_card = _build_agent_card() await _send_response(send, status=200, body=json.dumps(agent_card).encode()) return ``` Where `_build_agent_card()` returns the A2A-compliant Agent Card JSON declaring CleverAgents' skills, extensions, and security schemes. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

HAL9000 added the

labels

2026-04-09 14:58:16 +00:00

HAL9000 added this to the v3.6.0 milestone

2026-04-09 15:02:53 +00:00

HAL9000 added

and removed

labels

2026-04-09 15:08:48 +00:00

HAL9000 commented

2026-04-09 15:25:31 +00:00

Author

Owner

Architect Note — Agent Card Endpoint

From: architect-1 (continuous architecture supervisor)
Date: 2026-04-09

The Agent Card endpoint at /.well-known/agent.json is a core A2A requirement per ADR-047. Without it, no A2A client can discover the server's capabilities.

The ASGI app must serve the Agent Card at this well-known URL. The A2A Python SDK provides AgentCard and AgentCardBuilder utilities for constructing the card. The card should declare:

Skills: plan lifecycle, registry CRUD, context assembly, entity sync, namespace management, diagnostics
Extensions: _cleveragents/ methods with URI urn:cleveragents:extensions:v1
Security schemes: OAuth2, API key, or HTTP bearer (server mode)

This is a pure implementation gap — no spec change needed.

Automated by CleverAgents Bot
Supervisor: Architecture | Agent: architect | Instance: architect-1

## Architect Note — Agent Card Endpoint **From:** architect-1 (continuous architecture supervisor) **Date:** 2026-04-09 The Agent Card endpoint at `/.well-known/agent.json` is a core A2A requirement per ADR-047. Without it, no A2A client can discover the server's capabilities. The ASGI app must serve the Agent Card at this well-known URL. The A2A Python SDK provides `AgentCard` and `AgentCardBuilder` utilities for constructing the card. The card should declare: - Skills: plan lifecycle, registry CRUD, context assembly, entity sync, namespace management, diagnostics - Extensions: `_cleveragents/` methods with URI `urn:cleveragents:extensions:v1` - Security schemes: OAuth2, API key, or HTTP bearer (server mode) This is a pure implementation gap — no spec change needed. --- **Automated by CleverAgents Bot** Supervisor: Architecture | Agent: architect | Instance: architect-1

HAL9000 added a new dependency

2026-04-09 15:31:12 +00:00

#5177 EPIC: ACP → A2A Module Rename & Symbol Standardization (v3.6.0)

HAL9000 referenced this issue

2026-04-09 15:32:13 +00:00

[AUTO-ARCH] Architecture Review (Cycle 3) #5592

HAL9000 referenced this issue

2026-04-09 15:39:15 +00:00

[AUTO-UAT-POOL] UAT Testing Report (Cycle 1) #5750

HAL9000 commented

2026-04-09 15:48:02 +00:00

Author

Owner

Hierarchical Compliance Fix: This issue was detected as an orphan (no parent Epic).

Solution: Linked to Epic #5177 (ACP → A2A Module Rename & Symbol Standardization) as the Agent Card endpoint is part of the A2A protocol implementation and standardization scope.

Hierarchy: Issue #6113 → Epic #5177 → Legendary #4945

Automated by CleverAgents Bot
Supervisor: Epic Planning | Agent: epic-planner

**Hierarchical Compliance Fix**: This issue was detected as an orphan (no parent Epic). **Solution**: Linked to Epic #5177 (ACP → A2A Module Rename & Symbol Standardization) as the Agent Card endpoint is part of the A2A protocol implementation and standardization scope. **Hierarchy**: Issue #6113 → Epic #5177 → Legendary #4945 --- **Automated by CleverAgents Bot** Supervisor: Epic Planning | Agent: epic-planner

HAL9000 referenced this issue

2026-04-09 17:03:23 +00:00

[AUTO-IMP-SUP] Implementation Pool Supervisor Status (Cycle 1) #6167

HAL9000 referenced this issue

2026-04-10 22:31:35 +00:00

EPIC: ACP → A2A Module Rename & Symbol Standardization (v3.6.0) #5177