Blog

What an A2A agent card is for

An A2A Agent Card describes a service's identity, capabilities, and interfaces. Check the advertised service as well as the document.

author: George Jieh
published: 2026-10-14
reading: 4 min

Before a client sends work to another agent, it needs to know what that service offers and how to reach it. An A2A Agent Card publishes that description: identity, capabilities, skills, interfaces, and authentication requirements (A2A Project, "Agent2Agent Protocol Specification").

For a site owner, the maintenance problem is familiar. A card can outlive the endpoint it describes. MachineRead looks for candidate cards when A2A is in scope, so a finding should lead to inspection of the advertised service rather than stand in for a connection test.

The card is declarative metadata

The released A2A v1.0.0 specification defines an Agent Card as "a JSON metadata document published by an A2A Server" that describes identity, capabilities, skills, a service endpoint, and authentication requirements (A2A Project, "Agent2Agent Protocol Specification").

That gives a client somewhere to begin. It can read the advertised interfaces and requirements before attempting a connection. If the card is stale, however, those instructions may lead to a retired endpoint or an authentication flow that no longer works. Inspecting the document and testing the service are separate jobs.

The released proto is the stronger source

For A2A v1.0.0, the specification identifies spec/a2a.proto as the single authoritative normative definition, while generated JSON artifacts and schemas are non-normative convenience outputs (A2A Project, "Agent2Agent Protocol Specification"). That hierarchy matters when deciding how strong a validation claim can be.

The tagged proto's AgentCard definition requires fields such as name, description, ordered supported interfaces, version, capabilities, default input and output modes, and skills. Security-related fields can declare authentication requirements (A2A Project, a2a.proto). A complete A2A conformance claim would need to be measured against that stronger definition and the service behavior behind it.

MachineRead's Essentials checks do not make that complete claim. They keep to a smaller question: did configured target paths return enough parseable JSON evidence to be worth reporting?

What MachineRead checks

MachineRead's strict readiness probe includes A2A only when protocol scope is enabled or the resolved applicability includes the a2a family. In that case it fetches three candidate paths on the audited target: /.well-known/agent-card.json, /.well-known/a2a-agent.json, and /.well-known/agent.json.

For strict readiness, the response has to look like JSON or linkset content, parse as an object or array, avoid a generic error-only object, and include the top-level name key for the A2A probe. That is intentionally below full AgentCard-schema validation.

The report-row machine-surface discovery path is broader and weaker. It uses the same three candidate paths, but it accepts a response of at least 20 non-whitespace characters that parses as a JSON object or array. Unlike the strict readiness probe, it does not require name.

Those two screens are enough for a bounded audit signal. They are not enough to say that the target has a valid A2A v1.0.0 AgentCard, a live endpoint, working authentication, compatible clients, or successful task execution.

How to use the finding

Treat an A2A card finding as a lead. Open the returned document. Check which path produced it, whether the top-level identity and version fields make sense, whether the advertised endpoint matches the site owner's intended integration surface, and whether the listed skills are specific enough to test.

Then test the runtime path only if the site owner actually intends A2A to work. That means checking endpoint reachability, authentication, client compatibility, request and response behavior, and task-level outcomes with a real A2A client or conformance process. Do not ask a static discovery check to answer those questions.

Only investigate a missing card if the site is intended to offer an A2A service. An ordinary publication or brochure site may have no use for one.

Works Cited

A2A Project. "Agent2Agent Protocol Specification." A2A Protocol Specification, version 1.0.0, 12 Mar. 2026, https://a2a-protocol.org/v1.0.0/specification/. Accessed 9 Sept. 2026.

A2A Project. a2a.proto. Agent2Agent Protocol, version 1.0.0, GitHub, https://raw.githubusercontent.com/a2aproject/A2A/v1.0.0/specification/a2a.proto. Accessed 9 Sept. 2026.