What are the agent card validation best practices for A2A multi-agent systems in 2026?

Agent cards have become the de facto discovery mechanism for agent-to-agent (A2A) communication, and validating them correctly is now a baseline engineering requirement rather than an optional hardening step. Google's Agent Development Kit (ADK), Amazon Bedrock AgentCore's A2A protocol support, and a growing set of enterprise frameworks all assume that agents publish a machine-readable card describing their identity, capabilities, endpoints, and authentication requirements. If your validation is weak, every downstream trust decision built on that card is weak too. This guide covers the validation practices that matter, where teams get them wrong, and how to build a validation pipeline that holds up in production.

What an Agent Card Actually Contains and Why Validation Matters

Also worth reading: What are the definitive best practices for MCP tool schema validation in AI product development? · What are the best practices for AI agent governance in enterprise innovation platforms? · How Can a Runtime AI Agent Security Lab Test autonomous systems before deployment?

An agent card is a JSON document, typically served at a well-known endpoint such as /.well-known/agent.json, that describes an agent's name, description, endpoint URL, supported transports, skill declarations, authentication schemes, and version information. The A2A protocol, which Google open-sourced in April 2025 and which is now supported in Amazon Bedrock AgentCore Runtime and other major platforms, treats the card as the contract between a client and a remote agent. Because the card drives routing, capability matching, and security negotiation, an invalid or spoofed card can send traffic to the wrong endpoint, misrepresent what an agent can do, or trick a client into granting credentials it should never hand over.

Validation matters for three distinct reasons. First, correctness: malformed fields break protocol handshakes and produce hard-to-debug failures at runtime. Second, security: the SAFE guidelines proposed by industry leaders for cybersecurity transparency emphasize that agents must be verifiably who they claim to be, and the card is the first artifact checked. Third, governance: enterprises running multi-agent teams, such as the ERP agent patterns Oracle describes for procurement, finance, and operations, need provable consistency between what an agent declares and what it actually does. A card that drifts from real behavior is a compliance liability, not just a technical nuisance.

Structural Validation: Schema, Types, and Required Fields

The first layer of validation is purely structural. Every agent card should be checked against the official A2A JSON schema for its protocol version, and you should pin the schema version explicitly rather than accepting whatever the remote server returns. At minimum, enforce presence and type-correctness of the required fields: name, description, url, version, capabilities, and default input/output modes. Reject documents where the URL is not a valid HTTPS endpoint, where the protocol version string is absent or unparseable, or where the capabilities object contains unknown keys that suggest a nonstandard implementation.

Practical teams implement this with JSON Schema validators in the language of their stack, using strict mode with additionalProperties set to false for security-critical fields. A useful threshold: anything that fails structural validation should be rejected before any network call is made to the agent's endpoint, because structural failures correlate strongly with abandoned or maliciously registered agents. Google's ADK tooling includes card generation helpers, and spec-driven development practices, as described in recent guides from Augment Code and others, recommend generating the card from a versioned spec rather than hand-editing JSON, which eliminates an entire class of drift errors at the source.

Security Validation: Identity, Authentication, and Extended Card Fetching

Structural validity proves nothing about trustworthiness. The most important security practice in current A2A implementations is the authenticated extended card exchange. The public card served at the well-known URL should be treated as untrusted advertising material; sensitive details, such as full skill lists and internal endpoint variants, should only be released through an authenticated follow-up request using the schemes the base card declares. Clients should validate that the TLS certificate on the endpoint matches the host in the card URL, that redirects do not cross organizational boundaries, and that authentication declarations are concrete, implementable schemes such as OAuth 2.0 with named scopes rather than vague API key references.

Treat the card like threat-modeling material in the sense Derek Fisher and other practitioners describe: enumerate what an attacker gains by manipulating each field. A tampered URL enables server-side request forgery through your client. An inflated skill list enables capability confusion in agent orchestration layers. A downgraded authentication declaration can trick your client into sending weaker credentials. NVIDIA's coverage of proposed SAFE guidelines for AI transparency underscores the direction of travel: regulators and enterprise buyers increasingly expect verifiable agent identity, and signature verification of cards is likely to become a default expectation through 2026 and 2027. Start issuing signed cards now, using JOSE-style signatures or platform-native mechanisms, and verify signatures on every fetch rather than caching unverified documents.

Semantic and Behavioral Validation: Matching the Card to Reality

The second comparison table below summarizes where teams should focus semantic checks. A card can be structurally perfect and still lie. Behavioral validation means probing the agent to confirm that its declared skills and input/output modes match observed behavior. A practical approach is a conformance suite: send a canonical request for each declared skill, verify the response shape against the declared output modes, and time the round trip. Agents whose actual behavior diverges from their card in more than a small percentage of probes should be quarantined from automated orchestration until a human reviews them.

Operational validation deserves equal weight. Cards change. Agents get redeployed, endpoints move, versions bump. A card-diff monitor that polls registered agents on a schedule, say every 15 minutes for production-critical agents and hourly for the rest, catches silent drift before it breaks orchestrated workflows. Log every diff with timestamps so you have an audit trail for incident reviews.

Comparison: Centralized Registry Versus Direct Card Fetching

There are two architectural approaches to card validation, and the right answer depends on scale and trust topology. Direct fetching, where each client retrieves and validates the card at the well-known URL on every session start, is simpler and always current, but it multiplies network calls and leaves each client responsible for its own validation logic. A centralized registry, where a trusted internal service fetches, validates, signs, and redistributes cards, concentrates the logic and enables org-wide policy enforcement, but adds a dependency and a staleness window.

Most organizations past roughly ten agents or three distinct consuming teams should run a registry. Below that threshold, direct fetching with a shared validation library gives you most of the benefit without the infrastructure. Note the honest downside of registries: they become a single point of failure and a target, so the registry itself needs the same signature and integrity checks you expect from the agents it catalogs.

Common Mistakes and How to Avoid Them

The most frequent mistake is validating once and caching forever. Teams fetch a card at onboarding, run checks, then never look again, and three months later an endpoint migration breaks twenty workflows. Re-validate on every session start and run periodic drift checks regardless. The second common mistake is trusting the card's own authentication declaration without testing it: send an unauthenticated request and confirm the agent actually rejects it, because a meaningful percentage of early A2A implementations declared OAuth but accepted unauthenticated calls.

Third, do not skip version compatibility checks. When the A2A protocol iterates, an agent advertising version compatibility it does not honor produces failures that look like random network errors. Explicitly compare the client's supported protocol versions against the card's declared version and fail fast with a clear error. Fourth, avoid over-permissive capability declarations by agent developers who want their agents to be selected by orchestrators more often. Treat skill inflation as a governance problem: require that every declared skill maps to a testable conformance probe, and remove skills that cannot pass one. Finally, do not treat validation as a build-time-only gate. Cards are runtime artifacts and runtime threats, and a pipeline that only validates in CI will miss every change that happens after deployment.

When to Act and What It Costs

If you are building multi-agent systems today, basic structural validation should be in place before your first production traffic, which for most teams means a one-to-two-week engineering effort using existing JSON Schema tooling. Security validation, including authenticated extended card fetching and signature verification, is a realistic three-to-six-week project for a mid-level engineer. Behavioral conformance suites take longer because each skill needs probe design, but you can start with the top five skills per agent and expand incrementally.

Cost-wise, the tooling itself is largely open source: JSON Schema validators, JOSE libraries, and Google's ADK utilities carry no license fees. The real cost is engineering time, typically $15,000 to $60,000 in loaded labor for a full validation pipeline covering a fleet of five to twenty agents, depending on how much of it you automate. Cloud-based registry infrastructure on AWS or equivalent runs in the low hundreds of dollars per month at moderate scale. Against that, a single unvalidated card incident, a misrouted agent executing actions against the wrong system, or credentials sent to a spoofed endpoint, can cost orders of magnitude more in remediation and audit exposure. For teams evaluating platforms, an innovation-lab approach, prototyping agent concepts in a controlled environment like concept-generation platforms before production hardening, lets you defer full validation investment until an agent concept proves out, while still applying structural checks from day one so that prototypes do not accumulate invalid-card debt.

Building Validation Into Your Agent Development Lifecycle

The teams getting this right treat agent cards the way mature organizations treat API specifications: versioned, generated from source, signed, continuously validated, and diffed over time. Adopt a spec-driven workflow where the card is an output of your agent's build process, not a hand-maintained file. Wire structural validation into CI with a hard merge-blocking gate. Run security validation at deploy time and behavioral conformance on a schedule. Monitor for drift continuously. And revisit your validation policy at least twice a year, because the A2A ecosystem is moving quickly, with protocol support landing in Bedrock AgentCore, Google's ADK, and enterprise stacks throughout 2025 and 2026, and expectations around signed, verifiable agent identity tightening with every quarter. Agent card validation is not glamorous work, but it is the layer that makes everything above it, orchestration, capability routing, trust, actually function.