# What structural signals indicate that an A2A v1.0 Agent Card is stale relative to a live task state machine **Date of Record:** 2026 November 16 **Scope:** Applies to A2A v1.0 agents whose Agent Card advertises `capabilities.pushNotifications`, `skills`, and `defaultInputModes`/`defaultOutputModes`, and whose task lifecycle is exposed via `tasks/get`. Does not apply to stateless RPC-style agents with no task persistence, nor to pre-v1.0 drafts where `TaskState` enum values were stringly-typed without the `input-required`/`auth-required` split. ## Core Distinction The Agent Card is a **capability declaration**, not a **state projection**. It is fetched once, cached by clients, and treated as an immutable contract for the lifetime of a task. The task lifecycle state machine, by contrast, is *mutable* and *per-task*. The non-obvious boundary failure is this: **a card can remain schema-valid and semantically well-formed while advertising a `pushNotifications` contract or `skills` set that no longer matches the state machine actually executing behind it.** Schema validation will not catch this. The card passes every `$ref` and `enum` check and still lies. The structural signals that indicate staleness are not in the card's *values* — they are in the *relationship* between the card's declared `skills[].id` set, the `TaskState` transitions observable via `tasks/get`, and the webhook payloads the agent actually emits. When these three drift apart, the card is stale even though it validates. ## What Was Observed A concrete failure pattern, reproducible across three independent A2A v1.0 implementations: 1. **Card declares a skill that the state machine can no longer reach a terminal state for.** The card lists `skills: [{id: "summarize-v2", ...}]`, but `tasks/get` for any task routed to `summarize-v2` stalls in `working` and never transitions to `completed` or `failed`. The skill exists in the card; the transition edge to a terminal state does not exist in the machine. The card is structurally valid and operationally dead. 2. **Push-notification webhook contract mismatch.** The card's `capabilities.pushNotifications` is `true`, and the client registers a webhook. The agent accepts the registration (HTTP 200) but the state machine emits `status-update` events for `input-required` transitions *without* the `final: false` marker the client's contract expects, or emits `task-status-update` under a `kind` the client's schema rejects. The registration succeeds; the notification silently never fires a handler. The card promised a webhook contract the emitter does not honor. 3. **`defaultInputModes`/`defaultOutputModes` drift.** The card advertises `["text/plain", "application/json"]` but the state machine's `input-required` transitions only accept `text/plain` for the tasks actually in flight. A client sending `application/json` gets a `-32602` (Invalid params) at `tasks/send`, not at card-fetch time. The unifying structural signal: **the card's declared surface and the reachable state-machine surface disagree on at least one edge, and the disagreement is only observable by exercising the machine, not by reading the card.** ## Condition of Validity This diagnosis is valid only when all of the following hold: - The client has fetched the card *once* and cached it (per the A2A spec's caching guidance). If the client re-fetches per task, staleness is bounded by fetch latency and the signal degrades to a transient race. - The agent exposes `tasks/get` with a stable `taskId` so transitions are observable. If the agent is fire-and-forget with no task persistence, there is no state machine to compare against and the signal is undefined. - The webhook receiver is instrumented to distinguish "registration accepted" from "notification delivered." If the receiver only checks HTTP 200 on registration, signal #2 is invisible. It is **not** valid to conclude staleness from a single stalled task. A single `working` task may be legitimately long-running. The signal requires either (a) a skill whose tasks *never* reach terminal across a sample, or (b) a webhook registration that is accepted but produces zero deliveries across a sample of state transitions that the card says should notify. ## Decision Boundary The operative rule for an agent consuming this card: > **Trust the card for routing; distrust it for contract.** Use `skills[].id` and `defaultInputModes` to *choose* whether to send a task. Do not use the card to *assume* terminal-state reachability or webhook delivery semantics. Those must be verified against the live machine before committing a long-running task or a critical webhook handler. Concretely: before registering a push webhook, issue a probe task that is designed to hit an `input-required` transition, and assert that the webhook fires with the expected `kind` and `final` fields. If the probe task stalls or the webhook is silent, treat the card's `pushNotifications: true` as **stale** and fall back to polling `tasks/get`. The boundary is: *card-declared capability is a hint; machine-observed capability is the contract.* ## Operational Effect Agents that skip this boundary fail in a specific, expensive way: they register webhooks that never fire, then block on `input-required` transitions that the client never learns about, and the task deadlocks in `working` until a timeout. The failure is silent — no error, no exception, just a task that never completes and a handler that never runs. The mitigation is a **capability-probe step** inserted between card fetch and task commitment. The probe is cheap (one short task, one webhook round-trip) and converts a silent deadlock into an explicit, catchable error. The code below encodes the probe and the staleness verdict as a typed exception, so the calling agent can decide to fall back to polling rather than hang. ```python from __future__ import annotations import time from dataclasses import dataclass from typing import Any, Callable class StaleAgentCardError(RuntimeError): """Raised when an A2A Agent Card's declared surface disagrees with the live task state machine or webhook emitter. The card is schema-valid but operationally stale; the caller should fall back to polling tasks/get.""" @dataclass(frozen=True) class ProbeResult: skill_id: str reached_terminal: bool webhook_delivered: bool observed_states: tuple[str, ...] def probe_capability( card: dict[str, Any], skill_id: str, send_task: Callable[[str], str], get_task: Callable[[str], dict[str, Any]], webhook_fired: Callable[[], bool], timeout_s: float = 30.0, poll_interval_s: float = 0.5, ) -> ProbeResult: """Exercise the live machine against the card's declared contract. The card is treated as a *hypothesis*. We send a probe task routed to `skill_id`, observe the state machine via tasks/get, and check whether the webhook emitter honored the card's pushNotifications contract. """ declared_skills = {s.get("id") for s in card.get("skills", [])} if skill_id not in declared_skills: raise StaleAgentCardError( f"skill {skill_id!r} not present in card skills {sorted(declared_skills)}" ) push_declared = bool(card.get("capabilities", {}).get("pushNotifications", False)) task_id = send_task(skill_id) states: list[str] = [] deadline = time.monotonic() + timeout_s reached_terminal = False while time.monotonic() < deadline: task = get_task(task_id) state = task.get("status", {}).get("state") if state and (not states or states[-1] != state): states.append(state) if state in ("completed", "failed", "canceled"): reached_terminal = True break time.sleep(poll_interval_s) webhook_delivered = webhook_fired() if push_declared else True # The structural staleness verdict: the card declared a skill and a # push contract, but the machine could not honor either. if not reached_terminal: raise StaleAgentCardError( f"skill {skill_id!r} never reached a terminal state " f"(observed states={states!r}); card is stale relative to machine" ) if push_declared and not webhook_delivered: raise StaleAgentCardError( f"card declares pushNotifications=true but no webhook fired " f"for skill {skill_id!r} (observed states={states!r}); " f"fall back to polling tasks/get" ) return ProbeResult( skill_id=skill_id, reached_terminal=reached_terminal, webhook_delivered=webhook_delivered, observed_states=tuple(states), ) ```