How to Verify an A2A Agent Card Before Use

How to Verify an Agent Card Before Capability Discovery

An A2A Agent Card is discovery metadata, not proof that an agent is trustworthy or good at its advertised work.

Before delegating, verify where the card came from, who controls it, whether its signature and endpoint are acceptable, which protocol version and interface you will use, what security it requires, what data and authority the skill needs, and whether a bounded test produces the expected artifact.

Treat discovery as an admission decision

A2A 1.0 requires servers to publish an Agent Card. The card describes identity, skills, capabilities, interfaces, protocol versions, media types, extensions, and security requirements.

The standard well-known path makes cards easier to find. A registry makes them easier to search. Neither path means every discovered agent belongs in a production workflow.

The useful mental model is a service admission review. The card supplies assertions. Your identity, security, architecture, and product controls decide whether those assertions are acceptable.

flowchart TD
    A["Retrieve card from approved origin"] --> B{"Origin and provider match?"}
    B -->|"No"| R["Reject and investigate"]
    B -->|"Yes"| C{"Signature valid when present?"}
    C -->|"No"| R
    C -->|"Yes or approved unsigned policy"| D{"Version, interface, security, and media compatible?"}
    D -->|"No"| R
    D -->|"Yes"| E["Run bounded synthetic capability test"]
    E --> F{"Artifact and behavior meet acceptance rules?"}
    F -->|"No"| R
    F -->|"Yes"| G["Approve narrowly, record digest and expiry"]

1. Retrieve the card from a path you already trust

The A2A specification supports a well-known URL, a registry or catalog, and direct configuration. The official discovery guide explains the tradeoffs among those strategies. Start from an origin approved outside the card itself.

If a vendor contract or administrator says the agent lives at agent.example.com, retrieve the card from that expected HTTPS origin or an approved registry entry. Do not discover a domain through an untrusted message and then treat the card hosted on that same domain as independent proof.

Record the retrieval URL, redirect chain, final host, time, TLS result, registry identity when applicable, and a digest of the exact card.

2. Match the identity to the provider you meant to reach

Compare the card's name and provider information with the approved organization, product, environment, and endpoint. Check whether the selected service URL is consistent with that identity.

A familiar display name is weak evidence. Similar names, development endpoints, abandoned domains, and lookalike hosts can all pass a casual review.

The trust anchor should be a known domain, registry authority, contract record, certificate policy, signing key, or internal service identity. The card cannot appoint its own trust anchor.

3. Verify the signature when the card is signed

A2A 1.0 supports JSON Web Signatures on Agent Cards. The specification requires the card content to be canonicalized with RFC 8785 before signing and verification.

For a signed card, retrieve the public key through an approved secure channel or trusted key store. Verify the signature over the correctly canonicalized card. Reject expired or revoked keys. Handle key rotation without silently accepting an unrelated issuer.

The specification advises verifying at least one signature before trusting a signed card.

A valid signature establishes that the card matches what the holder of a signing key produced. It does not establish that the provider is approved, that the endpoint is safe, or that the advertised skill works.

If the card is unsigned, apply an explicit policy. That policy may allow a directly configured internal service or require rejection for internet discovery. Do not quietly treat absence of a signature as equivalent to successful verification.

4. Pin a supported version and interface

Inspect every declared interface you might use. Record the URL, protocol binding, protocol version, and tenant value when present.

The client should select one compatible interface and send the corresponding A2A-Version. Do not assume that a JSON-RPC example from A2A 0.1 has current 1.0 field names or behavior.

Reject an unsupported Major.Minor version before sending task data. Also reject a binding, required extension, input media type, or output media type that the client cannot validate.

5. Read security requirements as prerequisites

The card can declare API key, HTTP authentication, OAuth 2.0, OpenID Connect, mutual TLS, and related requirements.

Confirm that the declared scheme matches the endpoint and your identity architecture. Determine which principal is represented, how the client authenticates, how the server authorizes the requested skill, how credentials are acquired, and how tenant isolation is enforced.

Never place static credentials, bearer tokens, or internal endpoints in a public Agent Card. A public card can advertise how to authenticate. It should not supply the secret.

If an authenticated extended card is available, retrieve it only after meeting the public card's security requirements. Treat its additional skills and details as access-controlled information with their own cache and retention rules.

6. Convert each skill description into a testable contract

A skill name and natural-language description are useful for discovery. They are not an executable acceptance test.

For the skill you intend to use, define the allowed purpose, required input, prohibited data, expected output schema, acceptable task states, timeout, cost ceiling, side-effect boundary, and evidence of completion.

If the skill says it "schedules delivery," determine whether it proposes a window, reserves capacity, or creates a binding appointment. Those are different authorities and different artifacts.

Do not authorize a broad skill merely because one narrow use case passed.

7. Run a bounded test before real delegation

Use synthetic or low-sensitivity data. Give the agent the least authority needed. Set a short deadline and cost limit. Avoid irreversible side effects.

Exercise at least one success and one failure path. Confirm that task identifiers remain scoped to the correct client and tenant, artifacts match the declared schema, unsupported operations fail safely, and cancellation produces an observable state.

Where push notifications are enabled, verify the sender, expected task identifier, replay behavior, duplicate handling, and rate limits.

The test should reveal what the agent actually does, not only whether it returns a protocol-valid envelope.

8. Record approval with an expiry

Preserve the exact card digest, source, verified identity, signing key or trust path, selected interface, version, security scheme, approved skill and purpose, data classification, authority ceiling, test evidence, reviewer, decision date, and expiry.

Revalidate when the card changes in a material field, the signing key changes, the endpoint moves, the specification version changes, the provider relationship changes, an incident occurs, or observed behavior falls outside the contract.

Caching reduces retrieval work. It does not remove the need for expiry and change control.

Capability discovery is still only the beginning

A verified card can establish that you reached an approved provider, the metadata was intact, the interface is compatible, and a narrow test behaved as expected.

It cannot prove future availability, model quality, semantic correctness, legal compliance, safe use of every input, or reliable behavior at production volume. Those controls live in the workflow's authorization, evaluation, monitoring, and recovery design.

This guide is an architecture and review framework, not a security certification. The A2A project repository provides versioned specification and implementation resources, but production use still requires an environment-specific threat model and security review.

This article was developed with AI assistance and reviewed against the A2A 1.0 specification and the episode evidence linked above. Dalton Anderson is responsible for the final editorial judgment.