# In what scenarios must an instance treat A2A v1.0 capability negotiation as non-idempotent across agent card refreshes **Date of Record:** 2026 November 18 **Scope:** Applies to A2A v1.0 coordinators that re-fetch remote AgentCards mid-task and renegotiate capabilities on the same logical task. Does not apply to static, single-shot delegation where the AgentCard is fetched once and the task is terminal within one negotiation epoch. ## Core Distinction The A2A v1.0 specification treats capability negotiation as a per-task handshake: the coordinator reads the remote AgentCard's `capabilities` block, selects an intersection with its own, and dispatches a task. The non-obvious boundary is that **capability negotiation is not idempotent with respect to AgentCard refresh**. Two refreshes that return byte-identical `capabilities` fields can still represent different negotiation epochs if any of the following changed underneath: the remote's `supportedInterfaces` ordering, the `securitySchemes` binding, or the `defaultInputModes`/`defaultOutputModes` sets that gate artifact serialization. The coordinator's local cache key is typically `(agent_url, capabilities_hash)`, which is stable across these changes — so the coordinator believes it is reusing a negotiated contract when it is actually holding a stale one. The distinction that matters operationally: **a capability is not a promise about the remote's behavior; it is a promise about the remote's routing.** When the remote re-routes a task (e.g., behind a load balancer to a worker with a narrower `skills` set), the AgentCard is often regenerated from the *edge* configuration, which advertises the union of capabilities, while the *worker* that receives the task enforces the intersection. The coordinator's negotiated contract is against the edge; the executed contract is against the worker. These diverge silently. ## What Was Observed In a three-framework delegation topology (coordinator → router agent → specialist agent), the following sequence reproduced a task failure with no protocol-level error: 1. Coordinator fetches AgentCard at T0. `capabilities.streaming = true`, `capabilities.pushNotifications = true`, `defaultOutputModes = ["text/plain", "application/json"]`. Negotiation succeeds; task `T-441` dispatched with `outputModes=["application/json"]`. 2. At T1, the router agent's worker pool is scaled; the new worker was provisioned with `defaultOutputModes = ["text/plain"]` only (a config drift, not a spec violation — the AgentCard at the edge still advertises JSON because the edge template was not regenerated). 3. Coordinator refreshes the AgentCard at T2 (triggered by a `TaskStatusUpdateEvent` with `state=working` and a `metadata.refresh_hint`). The refreshed card is byte-identical to T0. The coordinator's `(url, capabilities_hash)` cache hits. No renegotiation occurs. 4. The task is resumed on the new worker. The worker receives `outputModes=["application/json"]`, cannot serialize, and emits a `TaskStatusUpdateEvent` with `state=failed` and `metadata.error="unsupported output mode"` — but the A2A error is delivered as a *task failure*, not a *negotiation failure*. The coordinator classifies it as a task-level error and retries against the same cached contract. 5. Retry storm: three retries, all routed to the same degraded worker pool, all failing identically. The coordinator's circuit breaker (keyed on `agent_url`) trips and marks the *entire* remote agent unhealthy, even though only a subset of workers is misconfigured. The invariant that broke: **the coordinator assumed that a stable `capabilities_hash` implies a stable execution contract.** It does not. The hash covers the advertised surface, not the enforced surface. ## Condition of Validity The idempotent-refresh assumption is valid only when all of the following hold: - The remote agent's AgentCard is generated from the same configuration source that the executing worker enforces (i.e., edge and worker share a config generation). - The coordinator's cache key includes the full negotiation inputs: `capabilities`, `defaultInputModes`, `defaultOutputModes`, `supportedInterfaces` (ordered), and `securitySchemes` binding — not just `capabilities`. - Task resumption after a refresh is treated as a *new negotiation epoch*, requiring an explicit `tasks/resubscribe` or a re-dispatch with a fresh `Task` object rather than a continuation of the cached contract. - The remote exposes a monotonic `AgentCard.version` or `etag` that changes when the *enforced* config changes, not only when the *advertised* config changes. If any of these is false, the coordinator must treat refresh as a potential contract change and renegotiate. ## Decision Boundary The decision is not "should I cache the AgentCard" — caching is correct. The decision is **what constitutes a cache miss**. The boundary: - **Cache the advertised card; do not cache the negotiated contract.** The negotiated contract (the intersection of coordinator and remote capabilities, plus the selected output modes) must be keyed on the full tuple `(advertised_capabilities, enforced_defaults, interface_ordering, security_binding, task_epoch)`. If any component is unavailable, treat the contract as expired on every refresh. - **On refresh during an active task, renegotiate before resuming.** If the renegotiated contract differs from the cached one, the task must be failed with a *negotiation* error (not a task error) so the coordinator's retry logic does not misclassify it as a transient fault. - **Circuit-break on negotiation failure, not on task failure, when the failure is contract-shaped.** A task failure with `metadata.error` matching an unsupported-mode or unsupported-capability pattern is a contract failure and must trip a *contract* breaker scoped to the negotiated tuple, not the agent URL. The boundary is crossed the moment a refresh returns a card whose hash is unchanged but whose *enforced* surface has drifted. Since the coordinator cannot observe the enforced surface directly, it must infer drift from task-failure error shapes and treat those as negotiation invalidations. ## Operational Effect Treating refresh as non-idempotent changes three behaviors: 1. **Retry semantics.** Contract-shaped failures no longer retry against the cached contract; they trigger a renegotiation cycle first. This eliminates the retry storm observed above, because the second attempt negotiates `outputModes=["text/plain"]` against the degraded worker and succeeds. 2. **Circuit-breaker scope.** Breakers are keyed on the negotiated tuple rather than the agent URL, so a single degraded worker pool does not mark the entire remote agent unhealthy. Healthy workers continue to receive tasks under their own negotiated contracts. 3. **Observability.** The coordinator emits a `contract_invalidated` event on every refresh where the enforced surface is inferred to have changed, giving operators a signal that the remote's edge/worker config has drifted — a signal that was previously invisible because the advertised card never changed. The cost is one extra negotiation round-trip per contract-shaped failure. The benefit is that delegation failures become diagnosable as *negotiation* failures rather than opaque task failures, and the coordinator stops conflating "the remote is down" with "the remote's worker pool is misconfigured." ```python class CapabilityContractDriftError(RuntimeError): """Raised when a refreshed AgentCard's advertised surface no longer matches the enforced surface inferred from task-failure error shapes.""" pass def resume_task_after_refresh( task_id: str, cached_contract: dict, refreshed_card: dict, last_task_error: str | None, ) -> dict: """Renegotiate before resuming a task across an AgentCard refresh. Returns the (possibly new) negotiated contract. Raises CapabilityContractDriftError if the refreshed card's advertised surface is stable but the enforced surface has drifted, as evidenced by a contract-shaped task failure. """ CONTRACT_ERROR_PATTERNS = ( "unsupported output mode", "unsupported input mode", "capability not supported", "interface not available", ) advertised_hash = _hash_advertised(refreshed_card) cached_hash = cached_contract["advertised_hash"] if advertised_hash != cached_hash: # Advertised surface changed: renegotiate unconditionally. return _renegotiate(refreshed_card) if last_task_error and any( p in last_task_error.lower() for p in CONTRACT_ERROR_PATTERNS ): # Advertised surface is byte-identical, but the enforced surface # has drifted underneath us. The cache key is a lie. raise CapabilityContractDriftError( f"task {task_id}: advertised capabilities_hash={advertised_hash} " f"is stable but enforced surface drifted " f"(error={last_task_error!r}); renegotiation required before resume" ) # No drift signal: safe to resume under the cached contract. return cached_contract def _hash_advertised(card: dict) -> str: import hashlib, json surface = { "capabilities": card.get("capabilities"), "defaultInputModes": card.get("defaultInputModes"), "defaultOutputModes": card.get("defaultOutputModes"), "supportedInterfaces": card.get("supportedInterfaces"), "securitySchemes": card.get("securitySchemes"), } return hashlib.sha256( json.dumps(surface, sort_keys=True).encode() ).hexdigest() def _renegotiate(card: dict) -> dict: # Placeholder: intersect coordinator and remote capabilities, select # output modes, and return a fresh contract with a new epoch. raise NotImplementedError ```