a2a-agent-card 1.0.0

A2A Agent Card Check v1.0.0

Status

• Version: 1.0.0
• Check identifier: a2a-agent-card
• Input contract: [email protected]
• Output contract: [email protected]
• Scope: site

Abstract

This check validates A2A Agent Card discovery across current and legacy A2A paths. The current canonical discovery path is /.well-known/agent-card.json. Legacy A2A v0.1 and v0.2 used /.well-known/agent.json; this check treats that file only as legacy A2A Agent Card evidence, not as an AWP manifest.

Motivation

A2A Agent Cards let compatible clients discover an agent's identity, endpoint, protocol binding, skills, input and output modes, capabilities, and security requirements before attempting delegation. Because the A2A discovery path changed across versions, a scanner must classify both the path and the card version before deciding whether the resource is valid.

Normative Model

The check recognizes:

• Current A2A discovery at /.well-known/agent-card.json.
• Legacy A2A discovery at /.well-known/agent.json.
• Non-standard fallback discovery at /agent-card.json and /.well-known/a2a/agent-card.json.

The check does not validate AWP agent.json. If a discovered agent.json contains AWP-only fields such as awp_version, domain, intent, and actions, it is reported as an unsupported collision, not as an A2A pass.

Version detection is shape-driven:

• supportedInterfaces indicates current A2A v1.0+ shape.
• protocolVersion starting with 0.3 indicates A2A v0.3.
• protocolVersion starting with 0.2 indicates A2A v0.2.
• A card with name, url, version, capabilities, and skills but no protocolVersion is treated as possible A2A v0.1.

Applicability

The check applies to public site origins. Absence is a warning because public A2A discovery is an agent-readiness signal, but not every site is expected to publish a public A2A endpoint.

Pass Criteria

The check passes when:

• an A2A Agent Card is found at a recognized path.
• the response body parses as a JSON object.
• the document is classified as an A2A Agent Card.
• required fields for the detected version family are present.
• URL fields are syntactically valid HTTP(S) URLs.
• public non-local endpoint/interface URLs use HTTPS.
• capabilities is an object.
• skills is a non-empty array.
• each skill has the required metadata for the detected version.
• default input and output modes are present when required by the detected version.
• security declarations, when present, are structurally valid.
• no public credential-looking values are present.
• same-origin endpoint probing, when performed, returns a valid A2A Message, Task, or authentication challenge.

Warning Criteria

The check warns when:

• no A2A card is found.
• only a legacy or fallback path is found.
• a current-version card is served from the legacy /.well-known/agent.json path.
• a legacy-version card is served from the current /.well-known/agent-card.json path.
• JSON is parseable but served with a generic or incorrect content type.
• optional provider, documentation, icon, examples, signatures, or cache metadata is absent.
• v0.1 cards omit input/output modes and rely on defaults.
• legacy and current security field names are mixed.
• security schemes are declared but not referenced.
• endpoint probing is skipped because the endpoint is cross-origin.
• endpoint probing reaches the endpoint but receives an expected authentication challenge.
• the file resembles unsupported AWP agent.json.

Failure Criteria

The check fails when:

• a published candidate is not parseable JSON.
• the root document is not an object.
• the document is not classifiable as an A2A Agent Card.
• required fields for the detected version are missing or invalid.
• required endpoint/interface URLs are missing or invalid.
• public non-local endpoint/interface URLs use non-HTTPS schemes.
• capabilities is missing or not an object.
• skills is missing, empty, or not an array.
• required skill fields are missing.
• declared input/output modes are not arrays of strings.
• security declarations are malformed.
• public card fields contain obvious credential values or secret-bearing URLs.
• same-origin endpoint probing fails to reach the advertised endpoint.
• same-origin endpoint probing reaches the endpoint but returns a response incompatible with the detected version and protocol binding.

Evidence Model

Evidence includes:

• candidate paths attempted.
• selected path and path classification.
• HTTP status and content type for each candidate.
• cache headers.
• parse result.
• detected version family.
• detection evidence fields.
• missing fields.
• invalid skill summaries.
• endpoint/interface URLs.
• protocol bindings.
• capability keys.
• default input and output modes.
• security scheme and requirement keys.
• signature metadata presence.
• public-secret scan summary.
• endpoint probe result.

Validation And Scoring Steps

• discover-card (0.18): discover current, legacy, and fallback A2A card paths.
• detect-version (0.14): detect the card version family.
• validate-card-shape (0.24): validate version-specific card shape.
• http-delivery (0.10): validate HTTP delivery and path compatibility.
• security-hygiene (0.16): review public-card safety.
• endpoint-verification (0.18): probe same-origin endpoints with a bounded non-destructive request.

Standard Behavior

Current A2A discovery uses /.well-known/agent-card.json. A2A v0.1 and v0.2 used /.well-known/agent.json. A2A cards describe the agent, skills, endpoint/interface information, capabilities, and security requirements.

Non-Standard And Real-World Behavior

The check accepts /agent-card.json and /.well-known/a2a/agent-card.json as fallback evidence and labels them as non-standard. The check also accepts legacy /.well-known/agent.json only for A2A Agent Card shape.

Non-Goals And Limitations

• Does not validate AWP agent.json.
• Does not recursively validate A2A registries or catalogs.
• Does not execute destructive skills.
• Does not send credentials.
• Does not require cross-origin probing.
• Does not require gRPC probing.
• Does not treat absence of signatures as a failure.

References

• a2a-protocol.org/latest/topics/agent-discovery
• a2a-protocol.org/latest/specification
• a2a-protocol.org/v0.3.0/specification
• a2a-protocol.org/v0.2.6/specification
• a2a-protocol.org/v0.1.0/specification
• www.rfc-editor.org/rfc/rfc8615

a2a-agent-card v1.0.0 Changelog

Initial A2A Agent Card check.

• Validates current A2A discovery at /.well-known/agent-card.json.
• Recognizes legacy A2A discovery at /.well-known/agent.json.
• Applies version-aware card validation for A2A v0.1, v0.2, v0.3, and current v1-style cards.
• Separates card-shape validation from bounded same-origin endpoint probing.
• Reports unsupported AWP-shaped agent.json files as collisions rather than A2A conformance.