Part 29 · One Agent, Five Platforms

An agent card is a CV for an agent. It tells other agents who it is, what it can do, where to reach it and how to prove who's calling. And like a CV, what you leave off matters as much as what you put on.

Part 28 had the supplier-communication agent on Azure read the invoice agent's card before asking about invoice 4471. This part writes both cards. It's based on the A2A 1.0 specification as I read it on 17 November 2026. The cards are illustrative, for the series' fictional company, and nothing here has been deployed.

An annotated agent card

What a card has to contain

The specification defines the card as a "self-describing manifest for an agent". Eight fields are required:

  • name and description: for people and for other agents.
  • version: the agent's own version, not the protocol's.
  • supportedInterfaces: a URL plus a protocol binding (JSON-RPC, gRPC or HTTP+JSON) and protocol version. The first entry is the preferred one.
  • capabilities: whether the agent supports streaming, push notifications and an extended card.
  • defaultInputModes and defaultOutputModes: media types, such as text/plain.
  • skills: what the agent is good at. Each skill needs an id, name, description and tags. Examples are optional.

The optional fields that matter most here are securitySchemes and securityRequirements, which say how a caller must authenticate, and signatures.

The invoice agent's card

The invoice agent runs on MuleSoft Agent Fabric (Part 11). Trimmed, its public card would look like this:

{ "name": "Invoice exception agent", "description": "Explains why a supplier invoice is on hold and what happens next. Read-only.", "version": "1.3.0", "supportedInterfaces": [ {"url": "https://agents.example.com/invoice/a2a/v1", "protocolBinding": "JSONRPC", "protocolVersion": "1.0"} ], "provider": {"organization": "Example Manufacturing (fictional)", "url": "https://www.example.com"}, "capabilities": {"streaming": false, "pushNotifications": true, "extendedAgentCard": false}, "securitySchemes": { "entra": {"openIdConnectSecurityScheme": { "openIdConnectUrl": "https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration"}} }, "securityRequirements": [{"schemes": {"entra": {"list": ["invoice.status.read"]}}}], "defaultInputModes": ["text/plain"], "defaultOutputModes": ["text/plain"], "skills": [{ "id": "explain-invoice-exception", "name": "Explain an invoice exception", "description": "Given an invoice number and supplier, explains the hold reason and the next step. Never changes an invoice.", "tags": ["invoice", "status", "read-only"], "examples": ["Why is invoice 4471 from supplier 2093 on hold?"] }], "signatures": [{"protected": "eyJhbGciOi...", "signature": "MEUCIQ..."}] } 

Here's why I'd make each choice:

  • One skill, worded as a limit. The description says "Never changes an invoice". A calling agent reads that text, so it should state the boundary as well as the ability.
  • Push notifications on, streaming off. Answers can wait hours for a person, as Part 28 explained, so webhooks fit better than a held-open stream.
  • One security scheme. Callers use their own Entra agent identity (Part 23), and the requirement names a read scope only.
  • A gateway URL. The interface points at Omni Gateway, not at the Mule flow or the process API behind it.

The supplier agent's card

The supplier-communication agent on Azure Foundry (Part 22) is the one the invoice agent calls back once a fix is approved. Its obvious skill would be "send a reply to the supplier". I wouldn't put that on its card.

Instead, it advertises draft-supplier-reply: given a case and the agreed outcome, it drafts an email and puts it in front of a person for approval. Sending happens only after that approval, inside the supplier agent's own process. So the card offers a draft, and the decision to send stays with a person. That keeps the rule from Part 28: no write skills on a card that another platform can call.

Skills can also carry their own securityRequirements. That lets the drafting skill ask for a narrower scope than anything else on the card.

What never goes on a card

The specification says a card "SHOULD NOT include sensitive credentials or internal implementation details". For these two agents, I'd leave off:

  • Secrets of any kind. No API keys, client secrets or tokens, not even in examples.
  • Internal URLs. No process API, SAP host or Mule flow names. Only the gateway endpoint.
  • Tool names. post_invoice_adjustment belongs to the tool contract from Part 7, not to the card. A card describes skills, not the tools behind them.
  • Write skills. As above.
  • Real data in examples. Invoice numbers and supplier ids in examples should be made up.
  • People. No approver names or email addresses. "A person approves" is enough.
  • Model and prompt details. They change often, and they help an attacker more than a caller.

Discovery and signing

The specification lists three ways to find a card: the well-known URI /.well-known/agent-card.json, a curated registry, or direct configuration. For two agents in one company, I'd use direct configuration: each side is set up with the other's card URL. Open discovery adds nothing here.

Then verify the signature. Before signing, the card is canonicalised with the JSON Canonicalization Scheme (RFC 8785), with the signatures field left out. To verify, a client fetches the public key named in the signature header, canonicalises the card the same way, and checks the signature. The specification says clients "SHOULD verify at least one signature before trusting an Agent Card". It also allows more than one signature, so keys can be rotated without downtime.

A valid signature still only proves the card wasn't changed. I'd also pin the trusted keys in a key store, so a card signed by an unknown key fails.

Versions and caching

Cards should be cached. The specification asks servers for a Cache-Control max-age and an ETag based on the card's version or a hash of its content.

So I'd treat a card change like a release:

  • Bump version whenever a skill, scope or endpoint changes.
  • Re-run the golden set from Part 10 before the new card goes live.
  • Keep the max-age short enough that a removed skill disappears within hours.

The extended card

A2A also has an extended card: a fuller version that only authenticated callers can fetch, and that can differ by caller. It could, for example, show the procurement team's agents an extra read skill. The specification says extended cards still shouldn't include internal service URLs or unmasked credentials.

For now I'd leave extendedAgentCard off on both agents. Two short public cards are easier to review than one card that changes by caller.

What I'd take from this

A good card is short. It names one or two skills, states its limits in the description, points at a gateway, asks for a narrow scope and is signed with a key you've pinned. Everything else belongs behind the gateway.

What would you require before trusting an agent card?

This series describes a reference build on a fictional company. This part is based only on the A2A 1.0 specification, as of 17 November 2026, and the documentation-only builds in Parts 11 to 25; the cards are illustrative and no hands-on build has been run yet. Views are my own.