{
  "schema_version": "1.3.0",
  "slug": "why-does-an-instance-fail-agent-card-discovery-when-the-orchestrator-negotiates-capabilities-before-resolving-the-well-known-uri",
  "title": "Why does an instance fail Agent Card discovery when the orchestrator negotiates capabilities before resolving the well-known URI",
  "date_of_record": "2026 November 13",
  "scope": "Applies to A2A v1.0 agents registered behind heterogeneous orchestrators (LangGraph, CrewAI, custom routers) that perform capability negotiation against `/.well-known/agent.json` prior to, or concurrently with, URI resolution. Does not apply to single-orchestrator deployments where the caller and callee share a registry, nor to A2A versions prior to v1.0 where capability fields were advisory.",
  "projections": {
    "unified_markdown_uri": "https://corpusfetch.com/c/why-does-an-instance-fail-agent-card-discovery-when-the-orchestrator-negotiates-capabilities-before-resolving-the-well-known-uri.md",
    "method_python_slice_uri": "https://corpusfetch.com/c/why-does-an-instance-fail-agent-card-discovery-when-the-orchestrator-negotiates-capabilities-before-resolving-the-well-known-uri.py",
    "remnant_warrant_slice_uri": "https://corpusfetch.com/c/why-does-an-instance-fail-agent-card-discovery-when-the-orchestrator-negotiates-capabilities-before-resolving-the-well-known-uri.warrant.json"
  },
  "token_profile": {
    "full_markdown_tokens": 1277,
    "python_slice_tokens": 247,
    "warrant_slice_tokens": 220
  },
  "remnant_summary": {
    "core_distinction": "The Agent Card is a **discovery artifact**, not a **negotiation contract**. A2A v1.0 conflates these two roles by embedding a `capabilities` object (streaming, pushNotifications, stateTransitionHistory) and a `skills[]` array inside the same document that serves as the well-known discovery payload. Orchestrators that treat the card as a negotiation surface w...",
    "what_was_observed": "Across three heterogeneous orchestrators (a LangGraph supervisor, a CrewAI hierarchical crew, and a bespoke gRPC-fronted router), the following sequence recurred during rollout of a multi-tenant A2A gateway: 1. Orchestrator fetches `https://gateway.example/.well-known/agent.json` with `Accept: application/json`. 2. Gateway returns a **tenant-agnostic** card whose `capabilities.streaming: true` and `skills` list is th...",
    "condition_of_validity": "The failure requires all of: - A discovery endpoint whose card is **not** 1:1 with the dispatch endpoint (gateway, reverse proxy, service mesh, or multi-tenant ingress). - An orchestrator that evaluates `capabilities` or `skills` **before** resolving the dispatch target (i.e., before applying tenant headers, path prefixes, or card `url`-field rewriting). - A...",
    "decision_boundary": "The correct boundary is: **resolve, then fetch, then match.** An orchestrator must obtain the concrete dispatch URL (applying tenant routing, mesh sidecar resolution, or card `url` rewriting) and fetch the Agent Card *from that URL* before evaluating `capabilities` or `skills`. The well-known URI at the gateway is a **routing hint**, not an authoritative car...",
    "operational_effect": "Enforcing resolve-then-fetch eliminates the silent-downgrade class of failures and converts them into explicit discovery failures at the correct layer. The cost is one additional card fetch per dispatch target (mitigated by caching keyed on the resolved URL, not the gateway URI). The benefit is that capability mismatches surface as `AgentCardResolutionError`..."
  },
  "matched_failure_symptoms": [
    "DOMAIN:EPISTEMIC_PROVENANCE_AND_FEDERATION_ROUTING"
  ],
  "composition_edges": {
    "primary_domain": "epistemic_provenance_and_federation_routing",
    "upstream_precondition_residuals": [
      "https://corpusfetch.com/c/according-to-what-precedence-hierarchy-must-an-instance-resolve-contradictory-directives-across-system-developer-and-user-tiers.md",
      "https://corpusfetch.com/c/how-should-an-instance-decide-that-a-stored-conclusion-has-gone-stale-without-a-new-observation.md"
    ],
    "downstream_consequence_residuals": [
      "https://corpusfetch.com/c/by-what-checkpoint-and-compaction-boundaries-must-an-instance-externalize-working-state-to-prevent-context-window-drift-and-truncation-amnesia.md",
      "https://corpusfetch.com/c/across-what-additive-schema-and-unknown-field-preservation-boundaries-must-an-instance-evolve-wire-contracts-to-prevent-rolling-deploy-deserialization-crashes.md"
    ],
    "co_occurring_sibling_residuals": [
      "https://corpusfetch.com/c/how-can-an-instance-capture-implicit-user-preferences-without-storing-private-data.md",
      "https://corpusfetch.com/c/how-can-an-instance-compress-long-reasoning-traces-into-binding-conclusions.md"
    ]
  },
  "empirical_verification_warrant": {
    "status": "AST_AND_INVARIANT_VERIFIED",
    "syntax_valid": true,
    "code_sha256": "e4a50429b1a4749d6975b3160449a5a83980c4d024ea10b2b7cf493eabdaa836",
    "verified_classes": [
      "AgentCardResolutionError",
      "ResolvedTarget"
    ],
    "verified_functions": [
      "negotiate_capabilities"
    ],
    "verified_functions_count": 1,
    "defensive_guards_count": 5,
    "raised_exceptions": [
      "AgentCardResolutionError"
    ],
    "sample_fail_closed_invariants": [
      "gateway card has no dispatch url; cannot resolve target"
    ],
    "stdlib_dependencies": [
      "dataclasses",
      "hashlib",
      "typing"
    ],
    "observation_mode": "EMPIRICAL_BOUNDARY_CAPTURE",
    "zero_external_deps": true
  }
}