Agent Experience

Discovery

Publish one file that tells agents what you offer.

Agentic Resource Discovery is an envelope, not an execution protocol. It tells an agent that a resource exists and where to fetch its real description.

Agentic Resource Discovery (ARD) is a way to publish, on your own domain, a machine-readable list of the agents, tools and servers you offer. An agent fetches one file, reads the entries, and follows each entry’s URL to the resource’s real description — an MCP server card, an A2A agent card, an OpenAPI document. The specification calls itself an envelope, not an execution mechanism.

Three facts to get right before you build anything:

  1. The path changed. ARD v0.91, dated 26 August 2026, specifies /.well-known/ard.json. /.well-known/ai-catalog.json is named in the spec as the predecessor path. Nearly every explainer published between June and August 2026 describes the old path.
  2. It is a proposal, not a ratified standard. The spec header reads “Status: Proposal”. There is no v1.0, and no W3C, IETF or foundation stewardship as of this writing.
  3. Adoption is negligible so far. See the adoption section below for the one public measurement we could find.

Reviewed 1 September 2026 against ARD v0.91 in github.com/ards-project/ard-spec.

What is Agentic Resource Discovery?

ARD is an open specification for resource discovery, announced on 17 June 2026 in coordinated posts from Google, Microsoft, Hugging Face, Snowflake and Cisco. The spec names three authors: Junjie Bu (Google), R.V. Guha (Microsoft) and Shaun Smith (Hugging Face). A longer list of companies — GitHub, Cisco, Databricks, GoDaddy, Nvidia, Salesforce, Snowflake, Amazon among them — appears under Acknowledgements and on the project’s logo wall, as contributors rather than co-authors.

The problem it addresses is inversion of the registry. Today, if you build an MCP server or an agent, you publish it into someone’s catalogue — a marketplace, a registry, a directory — once per catalogue. ARD’s framing, in the spec’s own words, is that a publisher “describes a resource once on its own domain”, and existing collections “become ARD discovery services” that crawl those descriptions rather than acting as the place of record.

That is the same architectural move robots.txt and sitemap.xml made for search: the site owner publishes the assertion, and consumers come and read it.

Why does the well-known path say ard.json now?

Because the project renamed and decoupled itself. The repository’s git history shows it began as “Agent Finder” and was rebranded to Agentic Resource Discovery on 11 June 2026, days before the public launch. Version 0.9 of the spec (28 May 2026) defined a manifest called ai-catalog.json; v0.91 (26 August 2026) defines an ARD entry that, per the spec’s own Appendix D, “does not derive from any catalog schema; the two evolve independently.”

The spec’s consumer rule is explicit and worth quoting, because it tells you how long the old path stays useful:

Consumer resolution (normative). A consumer resolving a domain’s entries MUST fetch /.well-known/ard.json, and MUST honour a rel="ard" link. ARD’s predecessor specified the path /.well-known/ai-catalog.json and the link relation ai-catalog; a consumer MAY additionally consult these […] a publisher on the predecessor path SHOULD move to ard.json.

So: consumers must read the new path and may read the old one. If you are starting today, publish ard.json. If you published ai-catalog.json in June, keep it and add the new path.

One trap for anyone reading older manifests: the v0.9 catalog format carried a top-level "specVersion": "1.0". That string is the catalog format version. It is not the ARD specification version, which is 0.91. Do not read it as evidence that ARD has reached 1.0.

How does ARD relate to llms.txt, AGENTS.md and MCP?

Carefully, and less than the commentary suggests.

Against MCP, A2A and OpenAPI: it wraps them. The spec’s interoperability document is direct on this — asked whether ARD replaces those protocols, it answers: “No. ARD is a discovery protocol (an envelope), not an execution mechanism. It wraps existing execution standards (like MCP, A2A, and OpenAPI) using standard and proposed IANA media types.” An ARD entry carries a type that is a media type — application/mcp-server-card+json, application/a2a-agent-card+json — and a url pointing at that document. The entry is a pointer with enough metadata to decide whether to follow it.

The spec also flags that those two media types are not yet formally registered: they are described as “de-facto community standards tracking towards formal registration”, with the caveat that “the format may change.”

Against A2A’s /.well-known/agent-card.json: it points at it, not over it. If you already publish an A2A agent card, an ARD entry references it. The two are complementary; ARD adds the inventory layer that lets a domain declare more than one resource.

Against llms.txt and AGENTS.md: the specification does not mention them. We grepped the spec and docs repositories; llms.txt appears once, incidentally, and AGENTS.md not at all. Any claim that ARD “supersedes llms.txt” is commentary, not spec text. Functionally they solve different problems: llms.txt indexes documentation for reading, AGENTS.md gives a coding agent working in a repository durable local instructions, and ARD inventories invocable resources. A site can reasonably publish all three.

ARD (ard.json) llms.txt AGENTS.md MCP server card
Object Invocable resources on a domain Documentation pages Repository conventions One tool server
Location /.well-known/ard.json Site root Repository, nearest file wins Server-defined URL
Read by ARD discovery services Retrieval agents, unevenly Coding-agent harnesses MCP clients
Says “This exists, fetch it here” “Read these docs” “Build and test like this” “Call these tools like this”

How do I publish an ARD manifest?

Step 1 — Inventory what you actually expose

List the resources on your domain that an agent could invoke or search: an MCP server, an A2A agent, a public API with an OpenAPI document, a search endpoint, a skill bundle. If the answer is “none”, ARD has little to offer you yet — publish a sitemap and an accurate documentation index first.

Step 2 — Write one entry per resource

Four members are required by the spec (§4.2), and one pair is exclusive:

Term Requirement Notes
identifier MUST URN of the form urn:air:<publisher>:<namespace>:<agent-name>. Schema pattern: ^urn:air:[a-zA-Z0-9.-]+(:[a-zA-Z0-9._-]+)+$
displayName MUST Human-readable name
type MUST An IANA media type describing the target document
url or data MUST (exactly one) Point at the description, or inline it
representativeQueries SHOULD The spec says it “SHOULD contain 2–5 examples”; failing this is a conformance warning, not an error
capabilities MAY Named capabilities
description, tags, version, updatedAt, metadata, trustManifest Optional @context and @id are also available for JSON-LD

The specification’s own example entry, verbatim from §4.4:

{
  "identifier": "urn:air:acme.com:server:weather",
  "displayName": "Weather Data Node",
  "type": "application/mcp-server-card+json",
  "url": "https://api.acme.com/mcp/weather.json",
  "capabilities": ["WeatherTool", "ForecastTool"],
  "description": "Enterprise weather MCP server for live telemetry.",
  "representativeQueries": [
    "what is the current wind speed in Chicago",
    "get the 5-day forecast for Seattle"
  ]
}

representativeQueries is the field most people skip and the one that does the most work. A discovery service matching a user’s phrasing against your entries has nothing else to match on. Write the questions a person would actually ask, not a keyword list.

Step 3 — Wrap the entries in a manifest

The manifest schema is deliberately thin. Its description in the repository reads: “The document published at /.well-known/ard.json… ARD requires only an entries array of ARD entries.” entries is the only required member, and additional top-level members are permitted and ignored.

Here is a complete worked example for a documentation and content site — a hypothetical docs.example.com that publishes an MCP server for searching its own docs, a public API, and a Markdown documentation index.

{
  "entries": [
    {
      "identifier": "urn:air:example.com:mcp:docs-search",
      "displayName": "Example Docs Search",
      "type": "application/mcp-server-card+json",
      "url": "https://docs.example.com/mcp/server-card.json",
      "description": "Full-text and semantic search across Example's product documentation, changelog and API reference.",
      "capabilities": ["SearchDocs", "GetPage", "ListSections"],
      "tags": ["documentation", "search", "mcp-server"],
      "representativeQueries": [
        "how do I rotate an Example API key",
        "what changed in the Example API in August 2026",
        "which Example plan includes audit logs"
      ],
      "version": "1.2.0",
      "updatedAt": "2026-09-01T00:00:00Z"
    },
    {
      "identifier": "urn:air:example.com:api:public",
      "displayName": "Example Public API",
      "type": "application/vnd.oai.openapi+json;version=3.1.0",
      "url": "https://api.example.com/openapi.json",
      "description": "REST API for projects, members and audit events. OAuth 2.1 with delegated scopes; write operations accept an idempotency key.",
      "tags": ["api", "openapi", "rest"],
      "representativeQueries": [
        "create a project in Example",
        "list the audit events for an Example workspace"
      ],
      "updatedAt": "2026-08-14T00:00:00Z"
    },
    {
      "identifier": "urn:air:example.com:docs:index",
      "displayName": "Example Documentation Index",
      "type": "text/markdown",
      "url": "https://docs.example.com/llms.txt",
      "description": "Curated Markdown index of Example's documentation, for agents that want to read rather than call.",
      "tags": ["documentation", "index"],
      "representativeQueries": [
        "where is the Example getting started guide",
        "show me Example's documentation table of contents"
      ],
      "updatedAt": "2026-09-01T00:00:00Z"
    }
  ]
}

That third entry is the pattern most content sites will care about: ARD does not require you to have an agent. It lets you point at whatever machine-readable representation you already have, including your documentation index. This site publishes its own manifest at agentexperience.tech/.well-known/ard.json, using both patterns: a first entry for the read-only MCP server it runs at /api/mcp, which is the invocable resource ARD was written for, and further entries pointing at the documentation index, the guides and the rubric.

Step 4 — Serve it correctly

Serve the file at https://your-domain/.well-known/ard.json with Content-Type: application/json, a 200, and permissive CORS if you want browser-based agents to read it. Serve it from the apex domain an agent would guess, not only from a subdomain.

Step 5 — Add a secondary discovery route

The spec lists several mechanisms besides the well-known path (§5.1): in-page JSON-LD markup, an Agentmap: directive in robots.txt, a <link rel="ard" href="…"> element, and DNS Service Binding records under _entries._agents.example.com and _search._agents.example.com. The link relation is the cheapest:

<link rel="ard" href="https://example.com/.well-known/ard.json">

Note that consumers must honour rel="ard", per the same normative paragraph quoted earlier, so this is a real second route rather than decoration.

Step 6 — Validate, then keep it honest

The specification repository ships a zero-dependency conformance CLI at conformance/bin/conformance-test, with modes for manifest validation, publisher resolution and registry validation. Run it in CI.

Then set a reminder to re-check the URLs in your entries every release. The failure mode for a manifest is not invalidity, it is drift: a url that 404s, a version that is two releases behind, an updatedAt from June.

Optional — the registry side

If you want to consume ARD rather than publish it, the spec defines a registry API: POST /search is required, POST /explore and GET /agents are optional, with an OpenAPI 3.1.0 description and a CDDL schema in the repository, and federation modes auto, referrals and none. One line in that section deserves quoting to anyone tempted to build a ranking on top of it: the relevance score “reflects semantic relevance only and MUST NOT be interpreted as a trust, compliance, or safety judgment.”

What is the real adoption picture?

Thin, and worth stating plainly rather than glossing.

The only systematic public probe we have found is an independent audit repository, api-evangelist/agentic-resource-discovery, whose adoption file dated 31 July 2026 records probing 43,838 domains, of which 37,751 were reachable, and finding 12 manifest responses across 9 distinct publishers, with zero fully conformant. That is six weeks after launch, against the older ai-catalog.json path. It is one measurement by one party, so treat it as an indication rather than a census — but it is the only number in public, and it is small.

Early publisher examples and reference links can drift quickly, so treat the API Evangelist audit as a dated adoption snapshot rather than as durable implementation guidance. Before citing a live publisher, fetch its current manifest and validate it against the current spec.

What this means for you. Publishing an ARD manifest today is a low-cost, low-risk bet on a specification with credible backing and almost no installed base of readers. That is a reasonable bet — the file takes an hour and it is the only standard in this space that inventories invocable resources. It is not a reasonable basis for expecting traffic, discovery, or agent usage in the near term, and we would treat any claim that it produces those outcomes as unsupported.

Should we adopt it?

A short decision guide, with no promises attached.

  • You run an MCP server, an A2A agent, or a public API. Publish ard.json. This is exactly the case the spec was written for, and the manifest is the cheapest way to make the resource findable from your own domain rather than from someone’s catalogue.
  • You run a documentation or content site with no invocable surface. Publish a sitemap, dates, and an accurate Markdown index first. Do not add an ARD manifest merely to claim a path: its scope is invocable resources, not a documentation index.
  • You already publish ai-catalog.json. Add ard.json, keep the old file for now, and make them agree.
  • You are writing about ARD. Check the version header before you cite anything. This spec changed its manifest path and decoupled its schema within ten weeks of launch.

Frequently asked questions

What is Agentic Resource Discovery? ARD is an open specification for publishing a machine-readable list of the agents, tools, servers and other resources a domain offers, at a well-known URL on that domain. Each entry says what a resource is and where to fetch its real description, rather than describing how to call it.

Is the file called ai-catalog.json or ard.json? As of ARD v0.91, dated 26 August 2026, the path is /.well-known/ard.json. The spec designates /.well-known/ai-catalog.json as the predecessor path, says publishers on it should move, and says consumers may still consult it. Guides written between June and August 2026 describe the older path.

Does ARD replace llms.txt, AGENTS.md or MCP? No. The spec describes ARD as an envelope that wraps execution standards such as MCP, A2A and OpenAPI. It does not discuss llms.txt or AGENTS.md at all, and those address different problems — a documentation index and repository instructions.

Is anyone actually reading ARD manifests yet? Adoption is very early. The one systematic public probe we found, dated 31 July 2026, reported manifests from 9 distinct publishers across 37,751 reachable domains, none fully conformant. Publish it because it is cheap and correct, not because you expect traffic from it.

Who governs the specification? The project publishes a governance page describing an oversight board and a maintainer group, and the repository names three code owners. There is no W3C, IETF or foundation stewardship as of 1 September 2026; the project’s own governance page frames a decision about a neutral host as roughly a year away. The specification is licensed Apache-2.0.

ARD is worth publishing because it is cheap and honest about what it is. It is not worth over-claiming, because almost nobody is reading it yet.

Read this guide as markdown