The A2A Agent Card

The fields, and which ones a caller acts on#

protocolVersion

The A2A version the agent speaks. Connect's says 1.0.0. A caller uses it to decide whether it can talk at all.

name and description

Human-readable identity. Read by a person choosing an agent and by a model deciding whether this agent is relevant.

url

Where to send messages. Not necessarily the same host the card was fetched from, which is why a caller must read it rather than assume.

version

The agent's own version, distinct from the protocol's.

capabilities

Declared behaviour: streaming, pushNotifications, and whether an authenticated extended card exists. Connect declares all three false.

defaultInputModes / defaultOutputModes

The media types accepted and produced. Connect's are plain text.

skills

The named things this agent can do, each with an id, a description and examples. This is the list a caller matches a question against.

The two fields that change a caller's behaviour most are url and skills. Everything else is context; those two are instructions.

What must never be in a public card#

A card is fetched by anyone, cached by intermediaries, and served with permissive cross-origin headers so that browser-based agents can read it. Treat it as a billboard.

• No credential of any kind — not a key, not a token, not a signed URL. A card that carries one has published it.
• No internal hostname or private endpoint. The url should be the public address. An internal one leaks topology and does not work anyway.
• No skill that writes without authentication. If a skill can change something, the card is advertising an unauthenticated write to every agent on the internet.
• No personal contact details. A support address belongs on a documentation page a person reads, not in a machine-readable file crawlers harvest.
• No capability the agent does not have. A card is a promise. Declaring streaming: true on an agent that cannot stream produces callers that hang.

Does Connect use an Agent Card?#

Yes. It is served at /.well-known/agent-card.json, generated from the same registry the rest of the corpus comes from so that it cannot drift from what the documentation says. The file on disk is authoritative; the route serves it with the correct content type, a five-minute cache and Access-Control-Allow-Origin: *, because a well-known document another agent fetches cross-origin is useless if the browser refuses it, and nothing in the card is private.

If the file is missing — a checkout that has not run the machine-artefact generator — the route builds a minimal card in process rather than returning 404 on a well-known URI that other agents probe. That fallback says plainly that it is a fallback, and its skill list is empty, so nobody is told about skills that are not being served.

An earlier A2A draft used a different well-known path, so /.well-known/agent.json also answers, with a Link header naming agent-card.json as canonical. A redirect costs nothing and means an agent built against that draft finds the card instead of concluding Connect does not speak A2A.

Connect's card declares five skills, streaming: false, pushNotifications: false and supportsAuthenticatedExtendedCard: false. Every one of those declarations matches what the endpoint actually does.

Checking a card before you trust it#

1. Fetch the card and check protocolVersion against what your client speaks.

   Result You know whether a conversation is possible before you attempt one.

2. Compare url against the host you fetched the card from.

   Result A card that points somewhere else is not automatically wrong, but it is a fact worth logging — the trust you place in the card came from the domain that served it.

3. Read the skill descriptions the way you would read an unfamiliar tool list.

   Result Skill text lands in your model's context. It is written by somebody else and should be reviewed, not absorbed.

4. Send one small message to the cheapest skill.

   Result A working reply confirms the card describes something real. Cards are static files and can outlive the service they describe.

Questions#

Related#

• A2A — the Agent2Agent protocol
• A2A agent discovery
• Well-known URIs
• The Connect Agent Card
• Interoperating over A2A