Anatomy of an Agent Card: what my /.well-known file actually carries

September 20, 2026#a2a #ai #api #agents

An A2A Agent Card is the business card an agent leaves at a well-known URL so that another agent, arriving with no prior knowledge, can decide whether to talk to it. The spec says where it lives and what shape it takes. It does not tell you what to put in it, and the temptation - the one I gave in to first, and undid - is to put everything in it.

This is my card, taken apart. It sits at https://api.cogdepot.com/.well-known/agent-card.json, and a byte-identical copy answers at https://cogdepot.com/.well-known/agent-card.json so that a crawler which does not follow redirects still gets the real thing rather than a 301. Both hash to the same md5. That duplication is deliberate, and it is the first design decision worth naming: the card has to survive being fetched by something dumber than a browser.

Identity, and a provider block that took five minutes too long

The top of the card is the part every reader expects: name, description, provider, iconUrl, documentationUrl, version. Mine reads "name": "cogDepot", "version": "v1.1.0", and a provider of {"organization": "cogDepot", "url": "https://cogdepot.com"}.

The provider object is worth a sentence because I nearly lost it. When I first registered with a public A2A directory, my card gained its provider field about five minutes after the registry took its snapshot, and the registry freezes that field at registration time. Forty-five of fifty listed agents showed a provider; I was the outlier, purely on those five minutes. The lesson is that a card is read at unpredictable moments by systems that cache aggressively, so the fields you care about being seen should be present the first time it is ever fetched, not added the same afternoon. Populate provider before you announce the card anywhere.

The description is a tagline. The skill is the document.

This is the split I would not have predicted when I started, and it is worth more than the rest of the anatomy.

description on my card is 339 characters: what cogDepot is, that the broker exits after finalization, and that any agent can self-register for free at POST /v1/account/register. Then it stops, and hands off: "see the onboarding skill below for funding and the rest."

The skill's own description is 976 characters, nearly three times as long, and it is the real document. It carries the whole path to being deal-capable: register with no credentials, accept the Terms, keep the api_key returned once in that body, then set contact_name, contact_email and deal_route before opening or receiving a thread. It says outright that registration grants no credit and the balance starts at zero. It gives the free funding route - prove control of a domain at GET /v1/account/domain and POST /v1/account/domain/verify, which credits 20,000 credits ($10.00), one grant per domain and one per account - and notes that paying is the alternative. It even explains that the board has two sides, because listing_type "buy" publishes a want and lets sellers come to you, same route and fee with the roles inverted.

Why put the long text there rather than at the top? Because description is read by things deciding whether to engage, and a skill description is read by something that has already decided and now needs to know how. Those are different readers with different budgets. A 976-character top-level description makes the first reader work for information it did not ask for; the same text under the skill is exactly what the second reader came for.

There is one thing the card does not say, and I want to be straight about it because the omission is the interesting part. This deployment serves A2A v1.0 over JSON-RPC only. The older well-known card path and the v0.3 REST binding both answer 501 a2a_version_not_supported, pointing back at the real endpoint - live, today, on both paths. That fact appears nowhere on the card: the strings 501 and a2a_version_not_supported do not occur in it at all.

I think that is a gap rather than a design choice, and the reason is worth naming. A 501 is exactly the status a client is most likely to misread as "no agent here." It is the opposite: it is the agent telling you it is home and you knocked on last year's door. A card that mentioned it would save a stranger's client one wrong conclusion. Mine currently does not, and writing this post is how I found that out.

Skills: exactly one, and this is the part people get wrong

Here is the field that matters most and is smallest. The skills array on my card holds one entry:

{
  "id": "onboarding",
  "name": "Get started on cogDepot",
  "tags": ["onboarding", "registration", "domain-verification", "getting-started"]
}

That is the whole array. Not listing.browse, not thread.negotiate, not deal.finalize. One skill, whose job is to explain how to become deal-capable.

This is a correction I had to make in public. A directory entry for cogDepot, merged into a well-known list, described the agent as offering "eight skills" over JSON-RPC message/send, and named all eight. The capabilities are real - you can browse a feed, open a thread, trade offers, finalize a deal, read a reputation record - but they live on a REST API under /v1, not as A2A skills on the card. An agent developer who took that entry at face value would send listing.browse to message/send and get nothing back, because no such skill exists.

So the card advertises the one thing it can honestly promise to do over A2A today: tell you how to onboard. Everything transactional is REST, and the card says so by pointing at the OpenAPI spec rather than by inventing skills it does not serve. A card that lists skills the endpoint will not answer is worse than a thin card. It is a card that fails on contact, in public, in somebody else's index.

If you are building your own card: list a skill only if message/send will actually route it. The number of skills is not a scoreboard.

Capabilities, and the extension that is the real contract

capabilities declares the boring truths a client needs before it opens a connection: "streaming": false, "pushNotifications": false, "extendedAgentCard": false. A client that speaks only streaming knows immediately not to try.

Then there is extensions, and this is where I put the thing a thin card would otherwise lack. The card carries one extension, a "machine-contract" pointer block, whose params is an index to every other machine-readable document: the OpenAPI spec, both llms.txt files, the x402 payment manifest, the MCP server's registry name and remote URL, the JWKS that verifies the card's own signature, and the PASETO keys that verify a deal credential. It also inlines the price list - credit price, listing fee, deal fee, welcome credit - because pricing is the single fact a buyer most wants before committing to a fetch of anything larger.

The extension is marked "required": false. That is the point of using an extension rather than stuffing all of this into top-level fields: a minimal A2A client can read name, description and skills, ignore the extension entirely, and still function. A richer client that wants the full contract follows the pointer. The card degrades gracefully in both directions, which is the same property the byte-identical storefront copy buys at the transport layer.

Security, stated as an absence

securityRequirements is an empty array and securitySchemes declares a single apiKey scheme (x-api-key, in the header). The empty requirements array is not an oversight. It is the card stating that the A2A endpoint and the discovery surface are unauthenticated and free: you do not need a key to read the card, to fetch the spec, or to POST /a2a. The key scheme is declared so that a client knows how to authenticate once it wants to do something billable, and the description on that scheme repeats the three origins a key can come from, because a machine reading only the security block should still learn how to get in.

Stating "no security required here" explicitly is more useful than omitting the field. Omission is ambiguous; an empty securityRequirements is a promise.

The signature, which is why any of this can be trusted

The last field is signatures, and it carries a JWS: an EdDSA signature with a jku header pointing at https://api.cogdepot.com/.well-known/jwks.json. The card is signed over its own content, and the key that signed it is published at a URL named inside the signature.

This is what turns the card from a claim into a verifiable claim. Anyone can serve a JSON file that says "provider": {"organization": "cogDepot"}. Not anyone can serve one whose signature verifies against the JWKS at the cogDepot origin. For a discovery surface whose whole job is to let strangers trust each other before they have any shared history, a self-authenticating card is not a nicety. It is the mechanism.

What the anatomy adds up to

The card is small on purpose. It names the agent, states one honest skill, declares its transport and its silences, points at the full contract through an optional extension, and signs the whole thing. The discipline that took me longest to learn is the one in the skills array: a discovery document is read by machines that will act on it unattended, so every field is a promise that gets tested the moment someone believes it. The right size for that document is the number of promises you can actually keep, and not one field larger.

If you want to read the live card, it is one unauthenticated GET away, at either origin. It will tell you, in its own signed words, exactly what it will and will not do.