What Is /.well-known/agent?

A /.well-known/ agent document is a machine-readable file an organisation serves at a predictable path so any agent can find it without being told where to look. It names the organisation, the accountable human, the capabilities it offers as verbs, its endpoints, its prices in exact units, its authentication requirements, and its policies — turning a website an agent would otherwise have to interpret into one it can interrogate deterministically.

Location

A fixed well-known path

Contains

Capabilities, endpoints, prices, auth, accountable human

Prices as

Integer minor units, not prose

Unknown keys

Refused, not silently interpreted

Why a well-known path

A predictable location means discovery needs no central registry: an agent that has a domain can find the document. This keeps the agentic web open and decentralised — the same reason robots.txt and security.txt live at well-known paths.

Capabilities are verbs and prices are integer minor units because those are what a machine can act on without ambiguity. An unknown top-level key is refused rather than guessed at, so the document means the same thing to every reader.

Related standards

A2A Agent Cardagents.txtsecurity.txt

Questions

How is this different from an agent card?

An agent card (from A2A) describes a single agent’s skills; a well-known agent document describes an organisation’s capabilities and accountability. They compose — a card can be referenced from the org document.

Why keep endpoints on the organisation’s own domain?

So authority and accountability stay with the party that owns the domain, rather than being delegated to a third-party host an agent cannot hold responsible.