Well-known protocol discovery for AI agents
Well-known protocol files give AI agents stable public locations for capabilities, API metadata, authorization boundaries, agent cards, commerce discovery, and other machine-readable site contracts.
Document the well-known index
A /.well-known/ index or linked discovery page helps agents understand which machine-readable files are intentionally published. It is especially useful when a site supports several protocols or separates public and authenticated capabilities.
Expose API metadata when relevant
API-oriented sites should make OpenAPI, Swagger, API catalogs, and developer docs discoverable from public pages or fixed paths. Agent Web Check only scores these strongly when shallow evidence indicates a first-party API or developer surface.
Advertise auth boundaries
OAuth authorization-server and protected-resource metadata help agents discover where authenticated API workflows begin. Publish them when authenticated APIs exist, but avoid implying protected workflows are available if the public product does not support them.
Use agent cards intentionally
A2A agent cards and Agent Skills manifests should describe real supported tasks, inputs, outputs, and safety boundaries. They are not SEO tags; they are contracts that agents may rely on when choosing an action path.
Handle commerce and booking carefully
Commerce or booking protocol discovery should only be published when those workflows actually exist. Keep pricing, checkout, booking, refund, and policy pages visible so agents can explain the action before any transaction step.
Do not publish every fashionable well-known file just to pass a checklist. Protocol discovery should match real product capabilities and public evidence.
- Should every site publish every well-known file?
- No. Well-known files should describe real public or authenticated capabilities. Publishing empty or misleading protocol files can create worse agent behavior than publishing none.
- What if a capability requires login?
- The public discovery file should clearly separate public reading from authenticated actions, describe authorization boundaries, and avoid implying that protected workflows are open.
- How should agents find multiple protocol files?
- A /.well-known/ index, homepage discovery links, docs links, and /llms.txt references can all help agents understand which protocols are intentionally supported.