# What structural signals indicate A2A v1.0 Agent Card discovery failure at the task-delegation boundary **Date of Record:** 2026 November 18 **Scope:** Applies to cross-framework delegation where a client agent resolves a remote agent via an A2A v1.0 Agent Card and then submits a `tasks/send` or `tasks/sendSubscribe` request. Does not apply to same-process tool calls, MCP-style tool invocation, or intra-framework orchestration where the card is not the discovery surface. ## Core Distinction The non-obvious boundary is this: **Agent Card discovery success is not delegation readiness.** A card can be fetched, parsed, schema-valid, and semantically plausible while the remote endpoint rejects every task because the card's declared `capabilities` and `skills` describe the *advertised* agent, not the *currently mounted* handler set. A2A v1.0 treats the card as a static discovery artifact served from `/.well-known/agent.json`; it does not require the card to be generated from the live routing table. The result is a class of failure where discovery is green and delegation is red, and the two are decoupled by design. The corollary distinction that operators get wrong: a `404` on the well-known path is a *discovery* failure and should be retried or the agent marked unreachable. A `200` on the well-known path followed by `-32601` (method not found) or a `Task` object with `state: "failed"` on the RPC path is a *delegation* failure and must not be retried against the same card. These are different failure domains with different remediation. ## What Was Observed Across a mixed deployment (LangGraph-based client, CrewAI-based server, an AutoGen-based server, and a hand-rolled FastAPI server), the following patterns recurred: 1. **Card/route drift after redeploy.** The server's card was a committed static file; the skill handlers were registered dynamically. A rolling deploy that dropped one skill left the card advertising it for the full TTL of client-side card caches. Clients submitted tasks for the missing skill and received `-32601`, not a `404` and not a `422`. The card never changed. 2. **Capability over-declaration without streaming enforcement.** Cards declared `capabilities.streaming: true`, but the server's `tasks/sendSubscribe` returned a single terminal event then closed the SSE stream. Clients that keyed liveness off stream-open (not first-event or terminal-event) treated the task as in-flight indefinitely and leaked task handles. 3. **`defaultInputModes`/`defaultOutputModes` mismatch as a silent filter.** One framework's client filtered candidate agents by intersecting its own output modes with the remote `defaultInputModes` before sending. Because the card listed `["text/plain"]` but the handler accepted only structured parts, the client's pre-flight filter passed and the server returned a `Task` in `failed` state with no error code — the failure was in the task payload, not the RPC envelope. 4. **`skills[].id` collision across frameworks.** Two servers in the same mesh both advertised `skill.id: "summarize"` with different input schemas. Client-side routing keyed on skill id alone, not `(agent_url, skill_id)`, and delegated to the wrong server. The card gave no signal that the id was locally scoped. 5. **Auth declared in card, enforced inconsistently.** `securitySchemes` listed `bearer`, but the well-known endpoint was unauthenticated while the RPC endpoint enforced it. A client that validated auth only at discovery time got a `401` at delegation with no card-level indication the two surfaces differed. ## Condition of Validity This boundary analysis holds when *all* of the following are true: - The client resolves agents through the A2A well-known card rather than a static registry with pinned versions. - The card is served as a static or cached artifact, i.e. not derived per-request from the live handler registry. - The RPC surface (`tasks/send`, `tasks/sendSubscribe`, `tasks/get`) is a separate deployment surface from the well-known path, so they can drift independently. - The client caches cards with any nonzero TTL. It does **not** hold when the card is generated at request time from the same registry that dispatches RPCs (drift is then impossible), or when the client re-validates the card against a live `tasks/get`-style probe before each delegation (drift is then detected). ## Decision Boundary The operational rule: **treat the Agent Card as a hint for candidate selection, never as a contract for delegation.** Concretely: - On `-32601` or a `Task` in `failed` state, do **not** retry the same task against the same card. Invalidate the cached card, re-fetch, and if the skill is still advertised, mark the `(agent_url, skill_id)` pair as *card-inconsistent* and route elsewhere. Retrying is the wrong move because the card is the thing that lied. - On `404` at the well-known path, mark the agent unreachable and apply normal discovery backoff. - On `401`/`403` at the RPC path after a `200` at discovery, treat as a *security-surface split*: the card's `securitySchemes` describe the RPC surface, not the discovery surface, and discovery-time auth checks are meaningless. Re-authenticate against the RPC endpoint only. - On a `Task` that never reaches a terminal state and whose stream opened successfully, bound it with a client-side deadline keyed to the card's declared streaming semantics; a single-event stream is indistinguishable from a hung stream without one. - Route on `(agent_url, skill_id)`, never `skill_id` alone. Skill ids are locally scoped by spec. ## Operational Effect The practical consequence is that card freshness and handler liveness must be monitored as two independent signals. A card that is `200` and schema-valid tells you the discovery surface is alive; it tells you nothing about whether any skill is dispatchable. Teams that instrument only discovery health see a fully green mesh while delegation error rates climb, because the failures land in the RPC envelope and the `Task` state, not in discovery. The fix is not to make the card dynamic (that is a legitimate choice but not required); it is to make the client's failure classification distinguish discovery failures from delegation failures and to invalidate cached cards on the latter. The following guard encodes that classification. ```python import time from dataclasses import dataclass, field class CardInconsistentError(RuntimeError): """Raised when a cached Agent Card advertises a skill that the RPC surface rejects.""" @dataclass class CardCache: ttl_seconds: float = 300.0 _entries: dict = field(default_factory=dict) # agent_url -> (card, fetched_at) def get(self, agent_url: str): entry = self._entries.get(agent_url) if entry is None: return None card, fetched_at = entry if time.monotonic() - fetched_at > self.ttl_seconds: del self._entries[agent_url] return None return card def put(self, agent_url: str, card) -> None: self._entries[agent_url] = (card, time.monotonic()) def invalidate(self, agent_url: str) -> None: self._entries.pop(agent_url, None) def delegate(cache: CardCache, agent_url: str, skill_id: str, payload: dict, rpc): """Submit a task, distinguishing discovery failure from delegation failure. rpc(agent_url, method, params) -> dict, raising RpcError(code, message) on JSON-RPC errors. """ card = cache.get(agent_url) if card is None: card = rpc(agent_url, "agent/getCard", {}) # discovery surface cache.put(agent_url, card) advertised = {s.get("id") for s in card.get("skills", [])} if skill_id not in advertised: # Not a delegation attempt at all: the card does not claim this skill. raise CardInconsistentError( f"skill {skill_id!r} not advertised by {agent_url}; refusing to delegate" ) try: task = rpc(agent_url, "tasks/send", {"skill": skill_id, "input": payload}) except Exception as exc: code = getattr(exc, "code", None) if code == -32601: # Card advertised the skill, RPC surface does not have it: card/route drift. cache.invalidate(agent_url) raise CardInconsistentError( f"{agent_url} advertised skill {skill_id!r} but returned -32601; " f"card invalidated, do not retry against this card" ) from exc raise if task.get("state") == "failed": # Task-level failure: payload/handler mismatch, not a discovery problem. raise CardInconsistentError( f"{agent_url} accepted skill {skill_id!r} but task failed: " f"{task.get('error', 'no error detail')}" ) return task ```