Agent Card validation errors explained, one by one

How to read the output

Every check below comes from the A2A specification. Findings come in three severities, and the distinction is not cosmetic:

• Error — the card cannot do its job. A client either cannot parse it, cannot find your endpoint, or cannot tell what you do. Fix all of these before publishing.
• Warning — the card works but under-delivers, or it contains something that will bite you. Some warnings are trivial; one of them (an embedded credential) is the most serious thing the validator can find.
• Pass — a check that had something to confirm. An empty pass list on a card with no errors usually means the document is far thinner than you think.

Checks run in layers, and later layers assume earlier ones held. That is why fixing the first error often removes several others at once — and why working bottom-up wastes time.

Layer 0 — JSON that will not parse

Invalid JSON: Unexpected token } in JSON at position 412

Nothing else runs until this passes. In hand-written cards the cause is almost always one of three things: a trailing comma after the last item in an array or object, a smart quote pasted in from a document, or a raw newline inside a string literal. JSON allows none of them.

Multi-line descriptions are the usual culprit. If you want a long description, keep it on one logical line and let your editor soft-wrap it, or build the card from code rather than editing JSON by hand.

Layer 1 — pre-1.0 fields

Top-level "url" is a pre-1.0 field.
A2A v1.0 moved it to supportedInterfaces[0].url.

Five top-level fields were relocated or renamed in v1.0. Finding any of them tells the validator this is a migration in progress, which changes how it reports everything downstream.

Layer 2 — identity

* downgraded to a warning on cards that still carry pre-1.0 fields, per the previous section.

The short-description warning is worth more than its severity suggests. This field is read by another agent's model to make a routing decision. "Invoice agent" is syntactically fine and practically useless; a description that names the inputs it expects and the cases it declines is what gets you correctly invoked — and, just as valuably, correctly skipped.

Layer 3 — interfaces and endpoints

This layer produces more errors than any other, because one array carries four separate requirements.

Missing service endpoint. A2A v1.0 requires supportedInterfaces[]
with at least one { url, protocolBinding, protocolVersion } entry.

Raised when there is no supportedInterfaces array and no legacy top-level url to fall back on. This is the finding to fix first: without it, nothing can address your agent at all.

Layer 4 — capabilities and content modes

The two mode fields are required by the specification but reported as warnings, and that gap is deliberate: a caller missing your mode list can still attempt a request and negotiate, whereas a caller missing your endpoint cannot do anything at all. Severity here tracks what breaks, not what the spec text says. Fix them anyway — guessing what to send is not a good first experience.

Layer 4b — skills

skills must include at least one skill describing what the agent can do.

A card with no skills describes an agent that accepts nothing. Then each skill is checked on four fields:

Missing tags is the most common error on real cards, because they were optional in pre-1.0 drafts. Tag with the words someone searching for the capability would use rather than your internal vocabulary: ["invoices", "reconciliation", "finance"], not ["fin-svc-v2"].

{
  "id": "reconcile-payment-batch",
  "name": "Reconcile a payment batch",
  "description": "Given a bank statement export, match each line to an open
                  invoice and report exceptions with reasons.",
  "tags": ["finance", "invoices", "reconciliation"],
  "examples": ["Reconcile yesterday's ACH batch against open invoices."]
}

Layer 5 — security metadata

Authentication is not declared. Add securitySchemes and security
requirements when the endpoint is not fully public.

Raised when the card declares neither securitySchemes nor security. That is correct for a genuinely open agent and a serious omission for anything else — a caller reading your card has no way to know a credential is needed until it gets a 401 it did not plan for.

The card appears to contain an API key (sk-...). Agent Cards are public
discovery documents; declare securitySchemes instead of embedding credentials.

This one is a warning by severity and an incident by consequence. The scan looks for the recognisable shapes — sk-… keys, JWTs, AWS access key ids, GitHub tokens, bearer headers — anywhere in the serialised document, including inside descriptions and examples where they usually arrive by copy-paste.

Layer 6 — provider and signatures

Nothing in this layer blocks a request, which is exactly why it gets skipped. It is also what a human decides with: an unsigned card from an unnamed provider is hard to justify approving in a partner review, however valid the JSON is.

If your card carries signatures, the validator confirms their presence as a pass. Verifying them is a separate operation — a JWS over the card canonicalised per RFC 8785 — but publishing them at all signals that the document is meant to be checked.

Triage order

Work top-down. Each step assumes the previous one holds, so this order minimises re-runs:

1. Make it parse. Nothing else runs until it does.
2. Restructure the transport section. If pre-1.0 field warnings appear, fix supportedInterfaces before anything else — it silently changes the severity of later findings.
3. Clear every error. Identity, interfaces, capabilities, skills. These are the interoperability blockers.
4. Deal with any credential warning immediately, regardless of where it sits in the list.
5. Close the remaining warnings. Modes, security declarations, provider metadata — each one is a question a caller would otherwise have to ask you.
6. Check the live URL. Validation covers the document — including that it sits at the RFC 8615 well-known path; the well-known URL checker covers the delivery — path, status code and content type on your real domain.

Paste your card into the Agent Card validator to run all of these at once, or read the schema reference for the field-level detail behind any single message.