# What structural signals indicate a stale A2A v1.0 agent card is being trusted during task negotiation **Date of Record:** 2026 November 16 **Scope:** Applies to A2A v1.0 peer-to-peer deployments where an agent resolves a remote `AgentCard` via a well-known URI, caches it, and subsequently uses fields from that cached card (capabilities, `defaultInputModes`, `skills`, task-lifecycle extensions) to negotiate a `Task`. Does not apply to registry-mediated discovery with push-based invalidation, nor to A2A deployments that pin card versions per-request via an explicit `cardVersion` query parameter. ## Core Distinction The distinction that matters is between **card freshness as a transport concern** and **card freshness as a negotiation invariant**. Most implementations treat the agent card as a discovery artifact: fetch once, cache with a TTL, refresh on expiry. This is correct for *routing* — deciding whether a peer exists and what it broadly does. It is unsound for *negotiation* — deciding whether a specific `Task` can be accepted with the parameters the caller intends to send. The non-obvious boundary: A2A v1.0 allows a server to narrow its accepted task surface (drop a skill, remove an input mode, disable a lifecycle extension such as streaming or push notifications) without changing its identity or its well-known URI. The card at `/agent-card` is authoritative for the *current* negotiation surface, but a cached copy is authoritative only for the surface at fetch time. When a client negotiates against a cached card, it can construct a `Task` that is structurally valid per the cache but rejected by the live server — or worse, silently accepted under a downgraded interpretation (e.g., a streaming task negotiated against a card that still advertises `capabilities.streaming: true` when the server has since disabled it and falls back to polling). The failure is not a fetch error; it is a *semantic* mismatch that surfaces only at task lifecycle transitions. ## What Was Observed Across a set of A2A v1.0 inter-agent integrations, the following structural signals co-occurred in incidents where a stale card was trusted: 1. **Capability drift without identity change.** The remote server's `capabilities` object (notably `streaming`, `pushNotifications`, `stateTransitionHistory`) changed between card fetches, but the card's `name`, `description`, and `url` were byte-identical. Clients using identity-based cache keys (URL + name hash) never invalidated. 2. **Skill-set shrinkage.** A `skills[]` entry present in the cached card was absent from the live card. The client negotiated a task targeting the removed skill; the server accepted the `Task` envelope (because the envelope schema did not require skill validation at creation) but failed at the first `TaskStatusUpdate` with an `unsupported_skill` error — *after* the client had already committed resources and emitted a user-visible "task started" event. 3. **Input-mode narrowing.** `defaultInputModes` no longer contained `text/plain` for a given skill; the cached card still advertised it. The client sent a text part; the server's live handler rejected it at the *first* message boundary with a `ContentTypeNotSupportedError` that referenced the live card, which the client had never fetched. 4. **Lifecycle-extension version skew.** The cached card advertised a task-lifecycle extension at version N; the live server had moved to N+1 with a changed `TaskState` enum member set. The client's state machine had no transition for the new terminal state and hung the task in `working` until timeout. 5. **No ETag/Last-Modified propagation.** The well-known URI returned `200` with a fresh body but no `ETag` and no `Last-Modified`, so conditional revalidation was impossible; clients that did revalidate received a full body indistinguishable from an unchanged one. The common structural signature: **the failure manifested at a task lifecycle transition, not at discovery.** Discovery succeeded. Card parsing succeeded. Task creation succeeded. The invariant broke at the first state transition that depended on a capability the cache asserted and the server no longer honored. ## Condition of Validity A cached agent card is a valid basis for negotiation **only if all of the following hold**: - The card carries a monotonic, server-controlled version marker (`cardVersion` or equivalent) and the server rejects task creation when the client's asserted card version is below the server's minimum accepted version. - The client revalidates the card (or a negotiated digest of the capability/skill/input-mode subset it depends on) at the moment of task creation, not merely at cache-population time. - The server validates the negotiated task's parameters against the *live* card at `Task` creation and returns a structured error referencing the live card if a mismatch is found — before any `TaskStatusUpdate` is emitted. - Lifecycle extensions are versioned independently and the client refuses to negotiate a task whose required extension version is absent from the live card. If any of these is absent, the card cache is a *hint*, not an invariant, and the client must treat every task-lifecycle transition as a potential freshness checkpoint. ## Decision Boundary The operationally useful boundary is: **revalidate on negotiation, not on schedule.** - If the client's intended task depends only on fields that the server guarantees are immutable for the card's lifetime (identity, `url`, top-level `description`), a TTL cache is sound. - If the intended task depends on `capabilities`, `skills`, `defaultInputModes`, `defaultOutputModes`, or any lifecycle extension, the client must fetch or conditionally revalidate the card *at task creation time* and compare the specific fields it will rely on. A field-level digest comparison is cheaper than a full re-fetch and sufficient. - If the server cannot provide conditional revalidation (no `ETag`, no `Last-Modified`, no `cardVersion`), the client must treat the card as untrusted for negotiation and either (a) require an out-of-band capability assertion in the task envelope, or (b) fail closed rather than negotiate against a stale surface. The boundary is not "how long may I cache" but "which fields may I trust without revalidation for this specific task." TTL is the wrong axis; field dependency is the right one. ## Operational Effect Trusting a stale card during negotiation produces failures that are expensive precisely because they are *late*: resources are committed, user-visible state is emitted, and the error arrives at a lifecycle transition where rollback is costly and attribution is ambiguous (client blames server, server blames client's cache). The correct posture is to make card freshness a precondition of the task-creation step and to encode the dependency explicitly, so that a mismatch raises a typed, attributable error at the boundary rather than degrading into a timeout or a silent downgrade. The following reference implementation encodes the invariant: it computes a dependency digest over the negotiation-relevant card subset, compares it against a revalidated live card at task creation, and raises a typed error when the cached surface no longer matches the live one. ```python from __future__ import annotations import hashlib import json from dataclasses import dataclass from typing import Any, Mapping class StaleAgentCardError(RuntimeError): """Raised when a cached A2A agent card no longer matches the live negotiation surface for the fields a specific task depends on.""" # Fields whose change invalidates negotiation (not identity/routing). NEGOTIATION_FIELDS = ( "capabilities", "skills", "defaultInputModes", "defaultOutputModes", "extensions", ) def negotiation_digest(card: Mapping[str, Any]) -> str: """Digest only the fields that gate task negotiation.""" subset = {k: card.get(k) for k in NEGOTIATION_FIELDS} canonical = json.dumps(subset, sort_keys=True, separators=(",", ":")) return hashlib.sha256(canonical.encode("utf-8")).hexdigest() @dataclass(frozen=True) class CachedCard: card: Mapping[str, Any] digest: str def negotiate_task( cached: CachedCard, live_card: Mapping[str, Any], task_envelope: Mapping[str, Any], ) -> Mapping[str, Any]: """Validate that the cached card's negotiation surface still matches the live card before allowing task creation. Fail closed on mismatch.""" live_digest = negotiation_digest(live_card) if live_digest != cached.digest: # Identify which dependency drifted for attribution. drifted = [ field for field in NEGOTIATION_FIELDS if cached.card.get(field) != live_card.get(field) ] raise StaleAgentCardError( "cached agent card negotiation surface is stale; " f"drifted fields={drifted}; " f"cached_digest={cached.digest[:12]} live_digest={live_digest[:12]}" ) # Cached surface is valid for this task; safe to emit the Task. return { "task": task_envelope, "negotiated_against_digest": live_digest, "card_version": live_card.get("cardVersion"), } def create_task_or_fail( cached: CachedCard, fetch_live_card, task_envelope: Mapping[str, Any], ) -> Mapping[str, Any]: """Revalidate at task-creation time, then negotiate. Never negotiate against a card that could not be revalidated.""" live_card = fetch_live_card() if live_card is None: raise StaleAgentCardError( "cannot revalidate agent card at task creation; refusing to " "negotiate against unverified cached surface" ) return negotiate_task(cached, live_card, task_envelope) ```