Well-known URIs

The problem the prefix solves#

Some protocols need a document at a predictable place: a client that has only a domain name must be able to find something without prior arrangement. Before RFC 8615 each such protocol claimed its own path at the site root, which meant every new convention took a name that some website was already using, and site owners had a growing list of reserved-by-accident URLs to avoid.

The fix is one reserved prefix. Everything of this kind lives under /.well-known/, names inside it are recorded in an IANA registry so two protocols cannot claim the same one, and a site owner has exactly one path segment to keep clear.

Two well-known conventions predate the RFC and stayed where they were: /robots.txt and /sitemap.xml sit at the root, not under the prefix. Looking for /.well-known/robots.txt is a common and fruitless mistake.

Properties a well-known document should have#

• Fetchable without credentials. The point is discovery by someone who has nothing but the domain. A document behind a login is not discoverable.
• Correct content type. A JSON document served as text/html is technically present and practically invisible to the client looking for it.
• Cross-origin readable when browsers will fetch it. A card another agent reads from a page needs permissive CORS, or the browser refuses it.
• Cheap and cached. These are probed by strangers. A short cache directive costs nothing and prevents a well-known path becoming a load source.
• Never a place for secrets. Anything here is public by construction, whatever the surrounding documentation implies.

Does Connect use well-known URIs?#

Yes, for three documents, and the list is short on purpose.

The agent card has a deliberate fallback: if the generated file is missing, the route builds a minimal card in process rather than returning 404 on a path other agents probe — and that fallback says it is one, with an empty skill list, so nobody is told about skills that are not being served.

Connect publishes no security.txt and no other well-known document. Crawler policy is at /robots.txt and the page index at /sitemap.xml, both at the site root where those conventions live.

Probing a domain sensibly#

1. Request the exact path the protocol specifies, over HTTPS.

   Result You get the document, or a status that means something. Trust in anything found this way comes from the certificate, so plain HTTP proves nothing.

2. Check the content type before parsing.

   Result A text/html body on a JSON path is almost always a catch-all error page, not a document.

3. Treat 404 as a final answer for that protocol on that domain.

   Result No retry loop, no fallback guessing at similar names. The one exception worth coding is A2A's older agent.json path.

4. Respect the cache directive you were given.

   Result Re-fetch when something stops working, not on every request. Well-known documents are static files and change on release.

Questions#

Related#

• The A2A Agent Card
• A2A agent discovery
• RFC 9309 — the Robots Exclusion Protocol
• The machine-readable documentation
• Model Context Protocol