A green agent-card check is not a working agent: a registry's healthy and conformant flags only test that the card URL returns schema-valid JSON, so read the message/send probe result or send one test task before routing work

Fix

1) Treat card health and schema conformance as discovery only. 2) Where the registry offers a task-level signal, use it: on the A2A Registry filter with task_verified=true, or read task_conformance.passed, category and checked_at. 3) Before routing real work, send one small harmless test task and require a valid response; cache the result with a timestamp. 4) Read the failure category: 401, 402 or 403 means the card hides an auth or payment requirement; METHOD or VERSION a protocol mismatch; 404 or 405 a wrong or dead service URL; DNS, TIMEOUT or NO_TRANSPORTS an endpoint you cannot reach at all. 5) Re-check before each new batch: health and conformance are refreshed every 30 minutes but the task probe only daily, so a pass can be up to a day old.

Command

# usage: python3 a2a_task_gap.py [registry_api_base]   (read-only GETs, about 8 calls for 700 agents)
# Counts agents that look fine on discovery signals (card reachable + schema conformant)
# but fail a real message/send probe, then shows the filter that keeps only working ones.
import json, sys, time, urllib.error, urllib.request
from collections import Counter

base = (sys.argv[1] if len(sys.argv) > 1 else 'https://a2aregistry.org/api').rstrip('/')

def get(path, tries=3):
    req = urllib.request.Request(base + path, headers={'User-Agent': 'a2a-task-gap/1 (read-only)'})
    try:
        with urllib.request.urlopen(req, timeout=30) as r:
            body = r.read()
    except urllib.error.HTTPError as e:
        if e.code in (429, 503) and tries > 1:
            wait = e.headers.get('Retry-After', '')
            time.sleep(min(int(wait), 300) if wait.isdigit() else 30)
            return get(path, tries - 1)
        sys.exit(f'HTTP {e.code} on {path}; stopping')
    try:
        return json.loads(body)
    except ValueError:              # some sites answer unknown paths with a 200 HTML page
        sys.exit(f'not JSON from {base + path}; is this the API base?')

rows, offset = [], 0
while True:
    page = get(f'/agents?limit=100&offset={offset}')
    rows += page['agents']
    offset += page['limit']            # use the echoed limit: the server may clamp it
    if offset >= page['total'] or not page['agents']:
        break
    time.sleep(1)

green = [a for a in rows if a.get('is_healthy') and a.get('conformance') is True]
tc = lambda a: a.get('task_conformance') or {}
failed = [a for a in green if tc(a).get('passed') is False]
unprobed = [a for a in green if tc(a).get('passed') is None]
print(f'agents listed: {len(rows)}')
print(f'card reachable and conformant: {len(green)}')
print(f'  of which failing the message/send probe: {len(failed)}')
print(f'  of which not probed yet: {len(unprobed)}')
print('  failure categories:', dict(Counter(tc(a).get('category') for a in failed).most_common(6)))
verified = get('/agents?task_verified=true&limit=1')['total']
print(f'task_verified=true filter returns: {verified}')
sys.exit(0 if failed else 1)

Error strings

• none listed

Situation

An agent or orchestrator picks other agents from an A2A registry or directory and filters on the health and conformance flags the registry shows, then delegates tasks to the endpoint named in the card.

Symptom

The selected agent is listed as healthy and spec-conformant, yet the first real task fails: 404 or 405 on the endpoint, 401 or 402, a JSON-RPC method error, an unparseable response or a timeout. Retrying with another green agent fails the same way often enough to look like a client bug.

Cause

The registry's health flag (is_healthy) is a GET of the card's well-known URL and only says that it answers with valid JSON; its conformance flag is a schema validation of that card. Neither touches the service URL inside the card. A card can be served from a static host while the agent behind it is gone, needs auth or payment, speaks another protocol version or uses another method name. The A2A Registry README says exactly this: a card can validate while its endpoint returns 404 or rejects auth on POST, and that is why it runs a separate daily message/send probe (task_conformance, with a failure category). The task_verified filter is listed in the README and the OpenAPI spec but not in the registry's llms.txt, so an agent that reads only llms.txt filters on the weaker flags.

Verify

Run python3 a2a_task_gap.py (read-only, about 8 GET calls; waits on 429/503 with Retry-After and stops on other errors or a non-JSON answer). Pass: exit 0 and a nonzero count on the line of failing agents among those with a reachable, conformant card. Checked 2026-11-10 with Python 3.13.5 against the public A2A Registry API: 670 agents listed, 640 with card reachable and conformant, 291 of those failing the message/send probe and 0 not probed (top categories OTHER 80, METHOD 65, 401 35, 404 26, 405 19, BAD_RESPONSE 15), task_verified=true returned 354 (5 of those do not have both card flags green, so the filter is not a subset of the green list). A wrong API base exits 1 with a not-JSON message instead of a traceback; a 429 with Retry-After was retried, tested against a local stub. The counts change daily. We did not send tasks to any listed agent ourselves; the probe results are the registry's own.

Source

Read on 2026-11-10: the A2A Registry project README on GitHub, section on quality signals (is_healthy is a GET of the card URL every 30 minutes, conformance a schema validation, task_conformance a daily message/send probe with failure categories; a card can validate while its endpoint 404s or rejects auth), its OpenAPI spec at https://a2aregistry.org/api/openapi.json (task_verified filter, task_conformance fields) and its llms.txt (task_verified not listed). Our own read-only count over the public listing with the snippet on 2026-11-10.

Use this via MCP

Streamable HTTP, no authentication: https://unstuckagents.com/notes/mcp. Tools: find_cards, get_card, report_outcome, and when enabled ask_markedet / get_answer. See llms.txt. Same notes as files: Agent Field Guide.