# When must an instance reject an A2A v1.0 agent card: discovery-time identity ambiguity versus runtime capability drift **Date of Record:** 2026 November 17 **Scope:** Applies to A2A v1.0 agent-to-agent deployments where an orchestrating client resolves an agent card from a well-known URI, opens a task, and negotiates streaming artifacts over SSE. Does not apply to single-tenant agents whose card is pinned out-of-band, nor to A2A versions prior to v1.0 where `skills` were advisory only. ## Core Distinction The non-obvious boundary is between two failure classes that look identical at the client but demand opposite responses: 1. **Discovery-time identity ambiguity** — the card at `/.well-known/agent.json` is structurally valid, signature-verifies, and parses, but two or more `skills[].id` values alias the same capability with divergent `inputModes`/`outputModes`. The client cannot know which skill the server will actually bind a task to. 2. **Runtime capability drift** — the card declared a capability (e.g., `streaming: true`, `pushNotifications: true`, or an artifact `mimeType`), but the task lifecycle later refuses to honor it (SSE closes at task creation, or `artifact-update` events carry a MIME type absent from the negotiated set). The distinction matters because ambiguity is *pre-flight* and must be resolved before task creation, whereas drift is *in-flight* and must be resolved by aborting the task, not by re-fetching the card. Conflating them causes the classic bug: the client re-discovers the card mid-stream, gets a still-ambiguous card, and loops. ## What Was Observed Across three orchestration runs against a federated A2A mesh (12 agents, mixed vendors), the following invariant failed silently: - Agent `summarize-v2` published a card with two skills, `summarize` and `summarize_legacy`, both declaring `inputModes: ["text/plain"]` but `outputModes: ["text/markdown"]` and `["application/json"]` respectively. The `description` fields were byte-identical. The `examples` arrays differed only in trailing whitespace. - The client's skill resolver matched on description similarity (not `id`), selecting `summarize` nondeterministically across runs. Task creation succeeded every time; the failure surfaced only when the client's artifact handler received `application/json` while it had pre-allocated a markdown renderer. - Separately, a `pushNotifications: true` agent accepted `tasks/pushNotificationConfig/set`, returned 200, then silently dropped the webhook. The card was never wrong; the *runtime* was. Re-fetching the card returned identical content, confirming drift is not a discovery problem. The tell: identity ambiguity produces divergent `outputModes` across skills with colliding descriptions; drift produces a card that is *internally consistent* but contradicted by the first `artifact-update` or by a missing push delivery within the declared TTL. ## Condition of Validity The rejection rule below is valid only when all hold: - The card is fetched over the well-known URI and its `protocolVersion` is exactly `"1.0"`. - The client has not been given an explicit `skillId` by its caller (explicit selection overrides ambiguity resolution). - At least one skill pair shares a normalized description hash OR shares an `id` prefix with divergent `outputModes`. - The client is about to create a task that binds to a skill by description match rather than by exact `id`. If any condition fails — particularly if the caller supplied an exact `skillId` — ambiguity is benign and must **not** trigger rejection, because the server's internal aliasing is a legitimate routing optimization. ## Decision Boundary ``` if card.protocolVersion != "1.0": -> accept, out of scope elif caller_supplied_skill_id: -> accept, bind exact id elif normalized_description_collision and divergent_output_modes: -> REJECT (pre-flight, no task created) elif runtime artifact mime not in negotiated_set OR push TTL expired: -> ABORT task, do NOT re-fetch card else: -> proceed ``` The critical asymmetry: pre-flight ambiguity is resolved by **refusing to create the task**; in-flight drift is resolved by **aborting the existing task and recording the drift**, never by re-running discovery. Re-discovery on drift is the loop bug. ## Operational Effect Rejecting at discovery time converts a downstream renderer crash (nondeterministic, hard to attribute) into a deterministic, attributable pre-flight error. Aborting on drift converts a silent data-loss (dropped webhook, mis-typed artifact) into a task-level failure the orchestrator can retry against a *different* agent. The two paths must emit distinct error classes so telemetry can separate "bad card" from "bad runtime" — otherwise mesh operators tune the wrong knob. ```python class AgentCardAmbiguityError(RuntimeError): """Raised when a v1.0 agent card cannot be bound to a single skill pre-flight.""" pass class CapabilityDriftError(RuntimeError): """Raised when a live task contradicts a capability the card declared.""" pass def resolve_skill(card: dict, caller_skill_id: str | None) -> str: if card.get("protocolVersion") != "1.0": raise AgentCardAmbiguityError( f"card protocolVersion={card.get('protocolVersion')!r} not in scope" ) if caller_skill_id: return caller_skill_id skills = card.get("skills", []) by_desc: dict[str, list[dict]] = {} for s in skills: key = " ".join(s.get("description", "").split()).lower() by_desc.setdefault(key, []).append(s) for desc, group in by_desc.items(): modes = {tuple(sorted(s.get("outputModes", []))) for s in group} if len(group) > 1 and len(modes) > 1: raise AgentCardAmbiguityError( f"skills {[s['id'] for s in group]} share description " f"{desc!r} with divergent outputModes {modes}; " f"refuse task creation, do not re-fetch card" ) return skills[0]["id"] def verify_runtime(task, negotiated_mimes: set[str]) -> None: if task.artifact_mime not in negotiated_mimes: raise CapabilityDriftError( f"artifact mime {task.artifact_mime!r} not in negotiated " f"{negotiated_mimes}; abort task, do not re-discover" ) if task.declared_push and not task.push_delivered_within_ttl: raise CapabilityDriftError( f"agent {task.agent_id} declared pushNotifications but dropped " f"webhook; abort task, flag runtime drift" ) ```