Well-known URI

A well-known URI is a URI whose path starts with /.well-known/, a prefix that RFC 8615 reserves so clients can find site-wide metadata at a predictable location before they make any other request.

How it works. RFC 8615 (May 2019, Standards Track) replaced RFC 5785 and reserves the prefix for the http and https schemes. Each name under the prefix is recorded in IANA’s Well-Known URIs registry with a status of permanent or provisional. Familiar entries include security.txt (RFC 9116) and openid-configuration (OpenID Connect Discovery). RFC 8615 requires applications that mint a new well-known URI to register it.

In A2A. The A2A specification registers the suffix agent-card.json. A client that knows an agent’s domain fetches https://{domain}/.well-known/agent-card.json and gets the Agent Card: skills, supported interfaces, capabilities and authentication requirements. IANA lists agent-card.json as a permanent registration, with the Linux Foundation as change controller. Specification versions up to 0.2.x used /.well-known/agent.json. Version 0.3.0 moved to agent-card.json.

Servers should send Cache-Control with a max-age and an ETag derived from the card’s version or a content hash. Clients should revalidate with a conditional request:

GET /.well-known/agent-card.json HTTP/1.1
Host: agent.example.com
If-None-Match: "1.2.0"

Limits. The well-known path works only when the client already knows the domain. The specification also lists curated registries and direct configuration as discovery routes. The public card should not contain credentials or internal details. An agent can expose more to authenticated clients through the extended Agent Card. HTTPS proves which domain served the card, and a card signature proves which key signed it. Neither one tells the client whether the organization behind the agent is trustworthy.

Neighbouring terms. The Agent Card is the document served at this path, and a client agent is the party that fetches it.