cleveragents/cleveragents-core

Fork 3

UAT: ASGI app missing Agent Card endpoint (/.well-known/agent.json) — ADR-047 requirement not implemented #1767

New issue

Open

opened 2026-04-02 23:46:03 +00:00 by freemo · 1 comment

freemo commented

2026-04-02 23:46:03 +00:00

Owner

Metadata

Branch: fix/a2a-agent-card-endpoint
Commit Message: fix(a2a): add /.well-known/agent.json Agent Card endpoint and getExtendedAgentCard operation
Milestone: v3.4.0
Parent Epic: #933

Bug Report

Feature Area: REST API endpoints / A2A Protocol — Agent Card Discovery
Severity: Medium
Found by: UAT tester uat-tester-3993412-1775170781

What Was Tested

Verified that the ASGI application (src/cleveragents/a2a/asgi.py) serves the Agent Card endpoint required by the A2A protocol specification.

Expected Behavior (from spec)

Per ADR-047 (docs/adr/ADR-047-acp-standard-adoption.md):

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

The A2A standard requires GET /.well-known/agent.json to return a valid Agent Card JSON document. An authenticated extended Agent Card is also available via the getExtendedAgentCard operation.

Actual Behavior

The ASGI app (src/cleveragents/a2a/asgi.py) only serves four paths:

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

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

{"error":"not found"}

Additionally, the getExtendedAgentCard operation is absent from A2aLocalFacade._SUPPORTED_OPERATIONS.

Steps to Reproduce

import asyncio
from cleveragents.a2a.asgi import app, _KNOWN_PATHS

# Verify /.well-known/agent.json is not in known paths
print('/.well-known/agent.json' in _KNOWN_PATHS)  # False

# Simulate HTTP request
async def test():
    scope = {'type': 'http', 'method': 'GET', 'path': '/.well-known/agent.json', 'headers': []}
    status = {}
    body = {}
    async def receive(): return {'type': 'http.request', 'body': b''}
    async def send(msg):
        if msg['type'] == 'http.response.start': status['code'] = msg['status']
        elif msg['type'] == 'http.response.body': body['data'] = msg['body']
    await app(scope, receive, send)
    print(f"Status: {status['code']}")  # 404
    print(f"Body: {body['data']}")      # b'{"error":"not found"}'

asyncio.run(test())

# Verify getExtendedAgentCard not in facade
from cleveragents.a2a.facade import _SUPPORTED_OPERATIONS
print('getExtendedAgentCard' in _SUPPORTED_OPERATIONS)  # False

Code Location

src/cleveragents/a2a/asgi.py — _KNOWN_PATHS frozenset and app() function
src/cleveragents/a2a/facade.py — _SUPPORTED_OPERATIONS list
docs/adr/ADR-047-acp-standard-adoption.md — Agent Card specification

Impact

Without the Agent Card endpoint, third-party A2A clients cannot discover CleverAgents capabilities dynamically. This breaks the A2A ecosystem interoperability that ADR-047 was designed to enable. The getExtendedAgentCard operation is also missing from the facade, preventing authenticated capability discovery.

Subtasks

Add /.well-known/agent.json to _KNOWN_PATHS in src/cleveragents/a2a/asgi.py
Implement GET /.well-known/agent.json handler in the ASGI app() function returning a valid Agent Card JSON document per ADR-047
Add getExtendedAgentCard to _SUPPORTED_OPERATIONS in src/cleveragents/a2a/facade.py
Implement getExtendedAgentCard dispatch logic in A2aLocalFacade
Define Agent Card schema (skills, extensions URI, supported interfaces, security schemes) per ADR-047
Tests (Behave): Add scenarios for GET /.well-known/agent.json returning 200 with valid Agent Card JSON
Tests (Behave): Add scenarios for getExtendedAgentCard operation in the facade
Tests (Robot): Add integration test verifying Agent Card endpoint is reachable and schema-valid
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.
GET /.well-known/agent.json returns HTTP 200 with a valid Agent Card JSON document matching the schema defined in ADR-047.
getExtendedAgentCard is present in _SUPPORTED_OPERATIONS and correctly dispatched by A2aLocalFacade.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, 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.
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: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/a2a-agent-card-endpoint` - **Commit Message**: `fix(a2a): add /.well-known/agent.json Agent Card endpoint and getExtendedAgentCard operation` - **Milestone**: v3.4.0 - **Parent Epic**: #933 ## Bug Report **Feature Area**: REST API endpoints / A2A Protocol — Agent Card Discovery **Severity**: Medium **Found by**: UAT tester uat-tester-3993412-1775170781 ### What Was Tested Verified that the ASGI application (`src/cleveragents/a2a/asgi.py`) serves the Agent Card endpoint required by the A2A protocol specification. ### Expected Behavior (from spec) Per ADR-047 (`docs/adr/ADR-047-acp-standard-adoption.md`): > "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" The A2A standard requires `GET /.well-known/agent.json` to return a valid Agent Card JSON document. An authenticated extended Agent Card is also available via the `getExtendedAgentCard` operation. ### Actual Behavior The ASGI app (`src/cleveragents/a2a/asgi.py`) only serves four paths: - `GET /` → `{"service":"cleveragents"}` - `GET /live` → `{"status":"alive"}` - `GET /ready` → `{"status":"ready"}` - `GET /health` → `{"status":"ok"}` `GET /.well-known/agent.json` returns **404 Not Found**: ```json {"error":"not found"} ``` Additionally, the `getExtendedAgentCard` operation is absent from `A2aLocalFacade._SUPPORTED_OPERATIONS`. ### Steps to Reproduce ```python import asyncio from cleveragents.a2a.asgi import app, _KNOWN_PATHS # Verify /.well-known/agent.json is not in known paths print('/.well-known/agent.json' in _KNOWN_PATHS) # False # Simulate HTTP request async def test(): scope = {'type': 'http', 'method': 'GET', 'path': '/.well-known/agent.json', 'headers': []} status = {} body = {} async def receive(): return {'type': 'http.request', 'body': b''} async def send(msg): if msg['type'] == 'http.response.start': status['code'] = msg['status'] elif msg['type'] == 'http.response.body': body['data'] = msg['body'] await app(scope, receive, send) print(f"Status: {status['code']}") # 404 print(f"Body: {body['data']}") # b'{"error":"not found"}' asyncio.run(test()) # Verify getExtendedAgentCard not in facade from cleveragents.a2a.facade import _SUPPORTED_OPERATIONS print('getExtendedAgentCard' in _SUPPORTED_OPERATIONS) # False ``` ### Code Location - `src/cleveragents/a2a/asgi.py` — `_KNOWN_PATHS` frozenset and `app()` function - `src/cleveragents/a2a/facade.py` — `_SUPPORTED_OPERATIONS` list - `docs/adr/ADR-047-acp-standard-adoption.md` — Agent Card specification ### Impact Without the Agent Card endpoint, third-party A2A clients cannot discover CleverAgents capabilities dynamically. This breaks the A2A ecosystem interoperability that ADR-047 was designed to enable. The `getExtendedAgentCard` operation is also missing from the facade, preventing authenticated capability discovery. ## Subtasks - [ ] Add `/.well-known/agent.json` to `_KNOWN_PATHS` in `src/cleveragents/a2a/asgi.py` - [ ] Implement `GET /.well-known/agent.json` handler in the ASGI `app()` function returning a valid Agent Card JSON document per ADR-047 - [ ] Add `getExtendedAgentCard` to `_SUPPORTED_OPERATIONS` in `src/cleveragents/a2a/facade.py` - [ ] Implement `getExtendedAgentCard` dispatch logic in `A2aLocalFacade` - [ ] Define Agent Card schema (skills, extensions URI, supported interfaces, security schemes) per ADR-047 - [ ] Tests (Behave): Add scenarios for `GET /.well-known/agent.json` returning 200 with valid Agent Card JSON - [ ] Tests (Behave): Add scenarios for `getExtendedAgentCard` operation in the facade - [ ] Tests (Robot): Add integration test verifying Agent Card endpoint is reachable and schema-valid - [ ] 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. - `GET /.well-known/agent.json` returns HTTP 200 with a valid Agent Card JSON document matching the schema defined in ADR-047. - `getExtendedAgentCard` is present in `_SUPPORTED_OPERATIONS` and correctly dispatched by `A2aLocalFacade`. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, 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. - 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: UAT Testing | Agent: ca-new-issue-creator

freemo added this to the v3.4.0 milestone

2026-04-02 23:46:13 +00:00

freemo referenced this issue

2026-04-02 23:48:06 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 451 — v3.7.0 #1778

freemo added a new dependency

2026-04-02 23:50:09 +00:00

#933 Epic: A2A Protocol Compliance — JSON-RPC 2.0 Framing, Standard Operations, and Extension Methods

freemo commented

2026-04-02 23:51:09 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
MoSCoW: MoSCoW/Should Have — bug or spec compliance issue.

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

Issue triaged by project owner: - **State**: Verified - **MoSCoW**: MoSCoW/Should Have — bug or spec compliance issue. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

freemo added the

labels

2026-04-02 23:52:11 +00:00

freemo referenced this issue

2026-04-02 23:56:42 +00:00

[Automated] Backlog Groomer Session State — v3.7.0 #1463