Publish an AI Catalog at /.well-known/ai-catalog.json listing the agent capabilities your domain offers — MCP servers, A2A agents — so registries and agents can find and trust them from one fetch.
What it is #
Agentic Resource Discovery (ARD) is a draft discovery layer — not a runtime — that lets a domain advertise which agent capabilities it offers and how to verify them. It answers three questions for an agent: where the right capability lives, which one to use, and whether it is safe to connect. It builds on the AI Catalog standard, both developed under a Linux Foundation working group and published Apache 2.0.
The core is a manifest at /.well-known/ai-catalog.json
. Each entries[]
item has a URN identifier
, a displayName
, a mediaType
, and either an inline data
object or a url
pointing at the real artefact. The media types tie ARD to the rest of the agent-readiness graph:
mediaType | Points at |
|---|---|
`application/mcp-server-card+json` | An
|
`application/a2a-agent-card+json`
[A2A agent card](/spec/agent-readiness/a2a-agent-cards/)`application/ai-catalog+json`
Beyond the well-known file itself, three mechanisms point agents at it: a `<link rel="ai-catalog">`
(also emittable as an HTTP Link
header); an Agentmap:
directive in robots.txt
; and DNS service-binding records _catalog._agents.<domain>
and _search._agents.<domain>
— the same _agents
namespace as DNS-AID.
Why it matters #
One fetch, typed answer. Instead of guessing at well-known paths one by one, an agent reads a single manifest that names every capability and its media type.Domain-anchored trust. An optionaltrustManifest
(SPIFFE ID, DID, or HTTPS identity, plus attestations and an optional JWS signature) lets a client verify the publisher cryptographically. The domain in the entry’s URN must align with the trust identity.Registry-friendly. Registries crawl published catalogs and make them searchable, so a capability listed once becomes discoverable across the agentic web.
How to implement #
Publish /.well-known/ai-catalog.json
with a specVersion
, a host
block, and one entry per capability you actually run. Reference your existing MCP and A2A cards by url
rather than duplicating them. Advertise the manifest with a link rel
, the robots.txt
Agentmap:
directive, and, if you publish DNS, the _catalog._agents
record. Don’t list endpoints you don’t offer.
This site ships it: /.well-known/ai-catalog.json catalogues our MCP server and A2A agent, advertised through the
Link
header, a link rel
, and robots.txt
.## Common mistakes
- Inventing fields. The entry schema is small —
identifier
,displayName
,mediaType
, and exactly one ofurl
ordata
. - A URN publisher segment that doesn’t match the
trustManifest
identity domain — verification then fails. - Listing aspirational capabilities. The catalogue is a contract; only list what resolves.
Verification #
curl -s https://example.com/.well-known/ai-catalog.json | jq .
returns valid JSON withspecVersion
andentries
.- Each entry
url
resolves to a document of the declaredmediaType
. - The
Agentmap:
line is present inrobots.txt
and theai-catalog
Link
rel is on the homepage response.
Related topics #
Sources & further reading #
[Agentic Resource Discovery (ARD) specification](https://agenticresourcediscovery.org/)— ARD Project (Linux Foundation) -
[AI Catalog standard](https://github.com/Agent-Card/ai-catalog)— AI Catalog Working Group, Linux Foundation -
[RFC 8141 — Uniform Resource Names (URNs)](https://www.rfc-editor.org/rfc/rfc8141)— IETF -
[Announcing the Agentic Resource Discovery specification](https://developers.googleblog.com/announcing-the-agentic-resource-discovery-specification/)— Google