Agent Cards Explained

1 What an Agent Card is — and why the protocol needs one

The A2A v1.0 specification describes a world in which agents built on different frameworks, by different vendors, in different organisations, exchange tasks across boundaries. The first problem any cross-vendor protocol has to solve is how does the calling side know what the receiving side can do? A2A's answer is the Agent Card.

"Agents can advertise their capabilities using an 'Agent Card' in JSON format, allowing the client agent to identify the best agent that can perform a task and leverage A2A to communicate with the remote agent."

Concretely, an Agent Card is a JSON document. It has a defined schema. It is published at a stable URL — the well-known URL https://<host>/.well-known/agent-card.json by default. Every A2A-compliant client looks there first when asked to call an agent at a given host. The card declares who the agent is, what it can do, where to reach it, which input and output modes it accepts, how to authenticate, and who issued it.

That much was true in earlier drafts of A2A. What v1.0 adds — and what most of the 2026 conversation about Agent Cards is actually about — is that the card can be cryptographically signed. The receiver does not have to take "I am the marketing agent for example.com" on faith; it can verify a JWS signature against a key bound to the domain owner. Section 3 of this page walks through that mechanism in full.

The mailing-address analogy

The clean mental model is postal mail. The Agent Card is the agent's published mailing address and résumé in one document. The task — A2A's unit of work — is a letter sent to that address. The protocol does not dictate what the receiving agent does with the letter; it dictates what an envelope looks like, where to put the address, and how the post office tracks delivery. The Agent Card is the address book entry the sender consults before posting.

The analogy holds further: a postal address is public, but the contents of the envelope can be encrypted; the post office cannot tell whether you are dispatching a contract or a love letter. The same is true of A2A. The Agent Card publicly advertises that the agent accepts text and structured input on five named skills; the actual task contents flow over JSON-RPC 2.0 with whatever auth the card declared. Discovery is open; conversation is private.

What an Agent Card is not

It is not the agent. The card is metadata. The agent itself is whatever code runs behind the endpoint — a LangGraph plan, a CrewAI crew, a Microsoft Agent Framework workflow, an OpenAI Agents SDK process, an in-house Python service. The card describes; the agent acts. Anthropic's framing of "what an agent is" — a system using LLMs in a loop, with tools, until done — is orthogonal to the card. The card is the public face; the loop is the private implementation.

It is also not a session. Cards are static (or near-static) documents intended to be fetched, cached, and re-validated periodically — closer to a DNS record than to an HTTP response. A card might change every few weeks (new skill added, signing key rotated); it does not change per request.

2 The status of the spec and who is shipping it

A2A was announced by Google in April 2025 and donated to the Linux Foundation in June 2025. The Linux Foundation press release formalised the project transfer with a founding board including Amazon, Cisco, Google, Microsoft, Salesforce, SAP, ServiceNow, and Workday. By April 2026 the project's partners page tracks more than 150 supporting organisations.

"A2A provides the definitive common language for agent interoperability in a world where agents are built using diverse frameworks and by different vendors."

The reference implementation, JSON Schemas, and TypeScript types live at github.com/a2aproject/A2A; the spec at a2a-protocol.org/latest/specification/. Both Microsoft Agent Framework v1.0 and Google's Agent Development Kit ship A2A clients and servers; AWS Bedrock AgentCore Runtime hosts A2A endpoints; Salesforce Agentforce integrates A2A out of the box; Google Vertex AI Agent Builder exposes Model Garden through A2A. Adoption breadth is no longer the question; the question is depth of cross-vendor production deployments — and that is still early per Gartner's Hype Cycle for Agentic AI 2026 (17% deployed, 60%+ planning) and McKinsey's State of AI 2025 (23% scaling agentic AI in at least one function; only 39% reporting any EBIT impact).

The relevance for this page is that the Agent Card schema itself is now stable enough to design against. v1.0 fixed the field set; subsequent revisions will add — not break — fields. If you are building an A2A client or server in 2026 you can safely treat the v1.0 card schema as your contract.

3 The Agent Card schema — what is in the JSON

The v1.0 Agent Card is structured into four logical groups: identity, capabilities, auth, and provenance. The detailed walk-through lives on the companion page Agent Card Anatomy; this section is the index-level summary.

3.1 Identity fields

• name — a short human-readable name ("AcmeCorp Marketing Agent")
• description — one or two sentences on what the agent does
• url — the JSON-RPC endpoint where tasks are submitted
• protocolVersion — A2A version supported ("1.0")
• provider — the issuing organisation (name, url)
• iconUrl, documentationUrl — human-facing metadata

3.2 Capability fields

• capabilities — protocol-level flags such as streaming (server can push partial updates over Server-Sent Events), pushNotifications (server can post task results to a webhook), stateTransitionHistory (server retains a history of task state transitions for audit)
• defaultInputModes / defaultOutputModes — content types accepted and returned (text, file, structured)
• skills — the load-bearing array. Each skill is a named unit of capability with id, name, description, tags, examples, and per-skill inputModes / outputModes. A planner agent picks among skills the way a human picks among items on a menu.

3.3 Auth fields

• securitySchemes — OpenAPI 3.x compatible scheme definitions (Bearer, OAuth 2.0, OIDC, mutual TLS, API-Key)
• security — required scheme bindings per skill or globally

The deliberate alignment with OpenAPI 3.x security schemes is one of the cleanest design decisions in the spec: existing infrastructure for issuing, validating, and rotating Bearer / OAuth / mTLS credentials Just Works for A2A. There is no new auth scheme to learn.

3.4 Provenance fields

• signatures — array of JWS-format signatures over the JSON body, each with a protected header and a signature value
• extensions — optional vendor-specific metadata (Microsoft Entra Agent ID linkage, Google Agentspace catalog ID, Salesforce AgentExchange listing, AWS AgentCore deployment ARN)

A minimum viable Agent Card has name, description, url, protocolVersion, and one skill. A production-grade card adds capabilities flags, security schemes, signatures, and an icon. The Agent Card Anatomy companion page walks through a complete sample card field-by-field.

4 Signed Agent Cards — provenance for the agents economy

The single largest change in v1.0 is that Agent Cards can carry cryptographic signatures. The signature is a JWS — JSON Web Signature, RFC 7515 — applied over the canonicalised card body. Multiple signatures are allowed (a card might be signed both by the agent's host and by a third-party attestor).

The verification flow is direct. The receiver fetches the card from the well-known URL, extracts the signatures array, locates the signing key via either an embedded x5c certificate chain or a jwks_uri declared elsewhere on the host (typically /.well-known/jwks.json), validates the JWS, and checks that the key is bound to the domain serving the card. No central registry is involved; the trust root is DNS plus TLS plus a key the operator publishes.

Why signing matters — three concrete attacks the spec defends against

Impersonation. Without a signature, any host can publish a card claiming to be the marketing agent for example.com. With a signature bound to example.com's published key, only the actual operator of example.com can produce a valid card for that domain.

In-flight tampering. A man-in-the-middle that compromises a CDN or a corporate proxy could rewrite an Agent Card in transit. JWS over the canonicalised body makes any modification detectable.

Stale claims. Signing keys must rotate. The spec recommends short signing-key lifetimes and explicit JWKS expiry headers, so a card cached in the wild does not remain valid indefinitely after a key compromise. Operators run multiple active keys in parallel for a rotation window.

What signing does not solve

Signing solves identity attestation — who issued this card. It does not solve delegated authorisation — what the agent is authorised to do on whose behalf. That second problem is the explicit subject of NIST CAISI's 2026 work and the IETF AAuth draft.

"CAISI is establishing the first US government program dedicated explicitly to interoperability and security standards for agentic AI systems."

The IETF AAuth draft proposes an ID-JAG (ID JWT-Authorization Grant) flow that adds the missing primitive: an attestable, scope-bound token the calling agent carries in addition to a Signed Agent Card, encoding "I am acting on behalf of user U from organisation O with scopes S, time-boxed to T, and you can verify this against organisation O's issuer."

The Microsoft Entra Agent ID service launched in May 2025 is the first enterprise identity service to treat agents as first-class principals (not borrowed user identities). Entra Agent ID integrates with Conditional Access and Privileged Identity Management and validates Signed Agent Cards as part of agent enrolment. Where Entra Agent ID is the runtime principal, the Signed Agent Card is the public document; together they cover identity attestation. Cross-domain delegation is still pending AAuth.

5 Agent Card vs OpenAPI vs robots.txt vs llms.txt vs model cards vs MCP descriptors

The Agent Card pattern is not new. It inherits from a lineage of well-known machine-readable advertisement files that has been accumulating since the mid-1990s. Understanding where the Agent Card differs from each precedent is the fastest way to grasp what it is for.

What Agent Card borrows from each precedent

From OpenAPI: the JSON Schema vocabulary for security schemes, the field naming conventions, the principle that a single document at a stable URL fully describes the contract.

"Model cards are short documents accompanying trained machine learning models that provide benchmarked evaluation in a variety of conditions… and disclose the context in which models are intended to be used."

From Model Cards: the capability-and-context framing — name, intended use, evaluation, limitations. An Agent Card's skills array is the moral equivalent of a Model Card's "intended use cases" plus benchmarks; its tags field is the moral equivalent of "intended domains."

From robots.txt: the well-known path convention. Agents that need to find other agents at a host benefit from the same predictable location pattern that crawlers benefit from when checking a site's policy. RFC 9309 standardised robots.txt 28 years after de-facto adoption; A2A wisely did not wait.

From llms.txt: the recognition that machine-readable site content benefits from a canonical, human-curated index file. llms.txt is the LLM-facing equivalent for site content; Agent Card is the agent-facing equivalent for capability.

What Agent Card differs from each precedent in

Versus OpenAPI: Agent Card is task-oriented (skills, modalities, delegation) where OpenAPI is endpoint-oriented (paths, methods, schemas). An A2A agent typically exposes one HTTP endpoint behind a card that advertises ten skills; OpenAPI would describe one endpoint, the Agent Card describes the ten capabilities a planner agent can choose between.

Versus MCP server descriptors: MCP servers advertise capabilities through the initialize handshake at connection time — there is no published well-known artefact. The MCP 2026 Roadmap notes the design choice explicitly:

"The Tasks primitive shipped as an experimental feature and early production use has surfaced gaps including retry semantics when a task fails transiently, and expiry policies for how long results are retained after completion."

MCP capability discovery is dynamic and per-session; A2A capability discovery is static and per-document. The two protocols sit at different layers and made the right call for their respective layers — MCP for tool integration where the host is configured out-of-band, A2A for agent integration where the caller fetches the card cold.

Versus robots.txt + llms.txt: Agent Card is signed; robots.txt and llms.txt are not. The threat models differ — a malicious robots.txt can be ignored by a misbehaving crawler, but a malicious Agent Card actively misrepresents an agent's identity to a paying client. Cryptographic provenance is not a luxury in A2A's setting.

Versus model cards: Model Cards are documentation; Agent Cards are runtime contracts. Reading a Model Card tells you whether to trust a model for a task; reading an Agent Card tells you how to call an agent for a task. The lineage is intellectual; the operational role is different.

6 The Agent Card discovery flow — end to end

The canonical discovery flow in A2A v1.0 has six steps. The flow is pure HTTPS — no GRPC, no custom transport, no centralised registry — which is why every framework can implement it in a few hundred lines of code.

1. Resolve. The calling agent has a host (marketing.example.com) and wants to discover an agent there. It fetches https://marketing.example.com/.well-known/agent-card.json.
2. Fetch. Plain HTTPS GET. The response is the JSON Agent Card. Standard caching headers apply.
3. Validate signatures. The caller extracts the signatures array, locates the JWKS endpoint (typically /.well-known/jwks.json), validates each JWS, and verifies that the signing key is bound to marketing.example.com. Unsigned cards may be accepted in development; production callers should reject them.
4. Match capabilities. The caller iterates over skills, matching tags, descriptions, and input/output modes against the task it needs delegated. A reasoner-grade caller can use the LLM itself to choose; a deterministic caller can match against a pre-built mapping.
5. Authenticate. The caller selects one of the declared securitySchemes and obtains the appropriate credential — Bearer token, OAuth client-credentials grant, mTLS certificate, or API key — through whatever issuer the operator has configured.
6. Submit task. A JSON-RPC 2.0 tasks/send call to the url declared in the card. From here the A2A task lifecycle takes over (submitted → working → input-required → completed/failed/canceled).

Three publishing patterns observed in 2026

Pattern A — Well-known URI (the spec default). The agent host serves the card at /.well-known/agent-card.json. This is the design A2A inherits from RFC 9309 and is mandatory for spec-compliant deployments. Every A2A-aware client looks here first.

"This document specifies and extends the 'Robots Exclusion Protocol'… by which service owners can control how content served by their services may be accessed, if at all, by automatic clients known as crawlers."

Pattern B — Marketplace registry. The same JSON is also indexed in vendor catalogs. Salesforce AgentExchange launched March 2025 as a public marketplace for Agentforce-compatible agents; Google Agentspace indexes A2A endpoints across an enterprise; AWS Bedrock AgentCore exposes a marketplace of deployable agents; Microsoft Copilot Studio surfaces an agent gallery. In each case the marketplace consumes the same Agent Card JSON the host serves at the well-known URL — the marketplace is a registry over the canonical artefact, not a replacement for it.

Pattern C — Ad-hoc inline reference. A planner agent that already knows a peer's well-known URL can pass it inline when bootstrapping — useful for private fleets that do not publish to the open web. The card is fetched from a private intranet; the rest of the flow is unchanged. Many enterprise deployments in 2026 are pattern C even when patterns A and B are technically supported.

Caching and freshness

Cards are intended to be cached. Standard HTTP caching headers (Cache-Control, ETag) apply; the spec recommends a default cache lifetime in the order of hours. Cards that change frequently — a card whose skills array is dynamically generated from a per-tenant configuration — should declare short TTLs and signal updates via If-Modified-Since. Marketplace registries typically poll the well-known URL hourly to daily.

The full sample of card discovery and validation lives on the Agent Card Anatomy companion page, including a complete worked example with code.

7 The marketplace dimension — Agent Cards as catalog entries

The well-known URL is a sufficient discovery mechanism for two agents that already know about each other. It is not sufficient for the broader question every operator eventually asks: which agents exist, what do they cost, and which one should I delegate this task to? The 2026 answer to that question is the agent marketplace, and the unit of inventory is the Agent Card.

The first wave of marketplaces

• Salesforce AgentExchange (March 2025) — the first public marketplace for Agentforce-compatible agents. Listings include the full Agent Card plus pricing metadata and partner attestations.
• Google Agentspace — an enterprise-internal catalog over Agent Cards across a customer's tenant; integrates with Vertex AI Agent Builder and the Agent Development Kit.
• AWS Bedrock AgentCore Marketplace — listings for deployable A2A agents; AgentCore Runtime hosts the endpoint, the marketplace lists the card.
• Microsoft Copilot Studio agent gallery — Microsoft's catalog of agents addressable through Copilot Studio, paired with Entra Agent ID for principal management.
• Framework registries — LangGraph and CrewAI publish framework-side directories of A2A-aware agents.

Each of these marketplaces consumes the same canonical artefact: an Agent Card. The marketplace adds discovery (search, tag matching, partner attestation), commercial metadata (pricing, terms), and reviews; the underlying contract — the JSON document at the well-known URL — is unchanged. This is the design pattern the W3C calls "one document, many surfaces."

Why a marketplace needs Signed Cards

A marketplace operating without Signed Cards is a marketplace that cannot tell its users "this listing was issued by the vendor whose name appears on it." The single most important security property a public marketplace can advertise is that its listings are not impersonations. Salesforce AgentExchange, Google Agentspace, AWS AgentCore Marketplace, and Microsoft Copilot Studio agent gallery all rely on Signed Agent Cards as the trust root for listings. Unsigned listings are restricted to private or sandbox tiers.

The economic settlement gap

What the Agent Card schema does not include is pricing or settlement. v1.0 says nothing about how much a skill costs to invoke or how the calling and receiving organisations settle revenue. AgentsBooks treats this as the Shares primitive — substrate-level, out of scope for the wire protocol. Gartner's 2026 Hype Cycle places "agentic billing" at the Innovation Trigger; McKinsey's 2025 State of AI finds that workflow redesign is the biggest EBIT lever of agentic AI — both reinforcing that the protocol is the enabler, not the performer. The marketplace metadata layered on top of the Agent Card is where pricing and settlement live in 2026; the protocol stays clean.

The arXiv survey framing

"Two complementary communication protocols — the Model Context Protocol, which standardizes how agents access external tools and contextual data, and the Agent-to-Agent protocol, which governs peer coordination, negotiation, and delegation — establish an interoperable communication substrate that enables scalable, auditable, and policy-compliant reasoning across distributed agent collectives."

The marketplace is not the protocol's job — it is the substrate's. The Agent Card is what the substrate exposes to the marketplace. The protocol stays small and stable; the marketplace layer competes on discovery quality, commercial terms, and trust attestation.

8 Security considerations and the gaps v1.0 does not close

Identity attestation is solved for the host; many adjacent problems are not. Operators deploying A2A in 2026 should plan for four named threat vectors and the explicit gaps the spec acknowledges.

8.1 Threat vectors documented in 2026

Impersonation. Mitigated by Signed Agent Cards and JWKS validation. OWASP's LLM Top 10 and the OWASP Agentic AI Security project explicitly enumerate agent impersonation as an emerging threat category for 2025–2026 deployments.

Capability spoofing. A signed card can still declare skills the underlying agent does not actually implement — signing attests who issued the card, not that the agent performs the skill. Calling agents must treat skill descriptions as advertised, not guaranteed; production deployments validate via test invocations, vendor attestation, or marketplace-level functional verification.

Stale or revoked cards. JWKS endpoints must publish key rotation events; cards cached in marketplaces or by callers must be re-validated against fresh keys. The spec recommends short signing-key lifetimes and overlapping rotation windows. Operators that ignore this end up with valid-looking cards signed by compromised or expired keys.

Cross-domain delegation. The largest acknowledged gap. When agent A in organisation O acts on behalf of user U calling agent B in organisation O′, neither OAuth 2.1 nor OIDC currently provides a standard way to carry the agent's scoped permissions across the boundary. The IETF AAuth draft proposes the missing extension; it is not yet RFC. NIST CAISI names this as a foundational standards gap.

8.2 What goes wrong in practice

Three failure modes recur in real deployments. First, operators publish cards with overly broad skills declarations and discover that calling agents take them at their word — a card that says "I can do KYC" gets routed real KYC workloads it cannot actually handle. Second, signing keys are deployed once and never rotated, leaving the trust root brittle to compromise. Third, marketplaces accept unsigned cards in their public tier and end up shipping impersonated listings.

Each has a known fix: write conservative skill descriptions, automate key rotation, refuse unsigned cards in production tiers. The spec gives you the primitives; the operational discipline is yours.

8.3 The honest framing — what the protocol does not deliver

The skeptic case, taken seriously, comes from Gary Marcus's 2026 essay:

"Despite all the hype, agents didn't turn out to be reliable."

The Agent Card does not make the agent it describes more reliable. It makes the agent's contract more legible — what skills are claimed, what auth applies, who attested the claim. A clean contract is the precondition for measuring reliability over time, attaching SLAs to skills, and routing around degraded agents. A card-less agent fleet cannot do any of those things; a card-equipped fleet can. That is what the spec actually delivers, and it is more useful than the marketing makes it sound.

9 How Agent Cards compose with the AgentsBooks substrate

AgentsBooks names eight primitives every agentic firm needs: Identity, Brain, Heart, Memory, Control, Knowledge, Friends, Shares. Agent Cards live in the Friends primitive — agent-to-agent — and reinforce three of the other primitives directly:

• Identity. A Signed Agent Card is the public face of an agent's identity. Combined with Microsoft Entra Agent ID on the runtime side and the IETF AAuth draft on the standards side, Identity becomes a portable, signable, scoped contract rather than a shared API key.
• Heart. A2A's task lifecycle (submitted → working → input-required → completed) is the wire format Heart triggers fire over. The Agent Card declares which trigger modalities the agent accepts (cron, webhook, event, runtime invocation) through its capabilities and defaultInputModes.
• Control. Every A2A interaction is logged against the task ID declared in the card-served endpoint. The audit trail is stable across vendor boundaries because the wire format is. AgentsBooks' "auditable substrate" property depends on every hosted agent publishing a stable card and signing it.

The composition is the point. A protocol that solved Friends but ignored the other seven would force every firm to re-implement them. A substrate that solved the other seven but ignored Friends would lock the firm into a single vendor. The 2026 settlement is open protocols at Friends, the substrate everywhere else — what we call "complete, not compete."

10 What to build on top — guidance for an agentic firm

If you are running more than three agents and at least one of them needs to be addressable from outside your codebase, an Agent Card is now the answer. The build-vs-buy guidance for 2026:

• Publish a card per agent at the well-known URL. Even if you only have one calling client today, the card is additive — it does not constrain what the agent does internally. It does make every future calling client cheap to onboard.
• Sign your cards in production. Unsigned cards work in development; in production, an attestable Agent Card is the difference between "claimed identity" and "verified identity." This is also the thing your security team will ask about first.
• Rotate signing keys on a calendar, not on a breach. Short-lived keys, overlapping rotation windows, JWKS endpoint with explicit cache headers. The single most common production failure is that the key never rotates.
• Write conservative skill declarations. A card that advertises five skills the agent reliably implements is more useful than a card that advertises fifteen skills, half of which fail. The card is a contract; skill names are claims.
• List in marketplaces deliberately. Public marketplaces are valuable for discoverability but multiply the attack surface — every marketplace caches your card. Listing in a private marketplace (Microsoft Copilot Studio gallery for an enterprise tenant; Google Agentspace for a customer; AgentsBooks' substrate-level catalog) usually beats a public listing for B2B agents.
• Treat AAuth as forthcoming, not present. Use Bearer + OAuth Client Credentials today; design your auth layer so an AAuth-style delegated grant slots in when standardised.
• Don't build your own Heart, Memory, or Control on top of A2A. A protocol gives you the wire format; a substrate gives you the seven other primitives. AgentsBooks is one such substrate; the broader point is that publishing a card is necessary, not sufficient.