Inputs
Example
https://agent.example/.well-known/agent-card.json -> required fields, skills, protocol bindings, capabilities, and security metadata.
A2A Agent Card Validator
Validate A2A Agent Card discovery JSON, skills, interfaces, capabilities, and deployment metadata.
Use it to inspect version-aware A2A v0.2, v0.3, or v1.0 card structure and discovery evidence without invoking the agent endpoint.
The contract file other agents read first
In the A2A protocol, an Agent Card is the entire first impression: a JSON document at a well-known URL that tells other agents who you are, which skills you offer, which endpoints and transports you speak, and how callers must authenticate. Consuming agents parse it mechanically. A missing required field, a skill without a description, or auth metadata that contradicts your actual deployment does not produce a friendly error on the other side — it produces silent incompatibility, and the calling agent simply moves on.
This validator first recognizes the card shape as A2A v0.2, v0.3, or v1.0, and reports an ambiguous version instead of forcing mixed fields through an arbitrary schema. It then applies that version's identity, transport/interface, skill, capability, security, and discovery-path rules while preserving unknown extension fields.
Validating a card before and after publishing
While drafting, paste the JSON directly and fix errors before warnings: errors are the fields a conforming consumer is entitled to rely on, warnings are where interoperability gets quietly worse. Pay particular attention to skill descriptions — they are what a selecting agent, or the model behind it, reasons over. A vague skill description is the agent-world equivalent of a broken link: syntactically fine, practically useless.
After deployment, fetch the card from its public well-known URL rather than pasting from your repository, because the interesting bugs live in the serving path: a redirect that strips the path, a proxy rewriting content types, an old version cached at the edge, or TLS terminating on a name the card does not mention. The fetched card is the one every other agent sees; validating anything else is validating a hope.
Discovery checks only, never live invocation
Pasted JSON stays in the browser, and live fetches run through the same-origin helper against the public card URL only. The validator never contacts the agent behind the card: no skill invocation, no task submission, no JSON-RPC traffic, no callback execution. It checks the practical fields this page can verify locally — treat a pass as a solid preflight, then confirm conformance against the official A2A schema and your implementation's own tests.
Frequently asked questions
Where does the card have to live?
For v0.2 the historical well-known path is /.well-known/agent.json. v0.3 and v1.0 use /.well-known/agent-card.json. An explicit card URL can also be validated, but that is reported separately from successful well-known discovery.
Does validating the card test my agent?
No. A valid result proves only the checked JSON structure and retrieval evidence. It does not invoke an endpoint, prove authentication, validate protocol behavior, or cryptographically verify a declared signature.
What belongs in the card and what must never be in it?
Identity, skills, transports, endpoint URLs, and authentication requirements belong. Secrets never do: no API keys, no tokens, no internal hostnames. The card is public by definition — write it assuming adversaries read it too.
How granular should skills be?
Granular enough that a consuming agent can choose between them by description alone. One do-everything skill forces callers to guess; a dozen near-identical skills force them to disambiguate. Skill boundaries are API design, with a model as the reader.
Why declare authentication in the card at all?
So callers can decide whether they can talk to you before the first request fails. Declared schemes must match the deployment exactly — advertising OAuth while enforcing API keys costs every consumer one confusing round-trip, or the integration entirely.
How often should the card change?
Whenever skills, endpoints, transports, or auth change — atomically with the deployment, treated as an API contract under version control. A stale card teaches other agents wrong facts about you, and they act on those facts.