diff --git a/docs/ai_catalog_spec.md b/docs/ai_catalog_spec.md deleted file mode 100644 index d02c451..0000000 --- a/docs/ai_catalog_spec.md +++ /dev/null @@ -1,60 +0,0 @@ -# AI Catalog Standard - -**The foundation for federated agentic resource discovery** - -ARD is built directly on top of the **[ai-catalog](https://github.com/Agent-Card/ai-catalog)** specification. The `ai-catalog` standard establishes the base artifact-agnostic data model, progressive trust layer, and verification rules that enable dynamic runtime agentic resource discovery. - ---- - -## Standard manifest location - -A host advertises its agentic resources by publishing a well-known static JSON manifest at: - -```http -https:///.well-known/ai-catalog.json -``` - -This allows secure, decentralized, and cacheable ingestion by crawlers and discovery services worldwide. - ---- - -## Core envelope schema - -A baseline `ai-catalog.json` manifest includes the following root elements: - -* **`specVersion`**: The version of the catalog format (e.g., `"1.0"`). -* **`host`**: Information about the entity operating the catalog (display name, DID/domain identifier). -* **`entries`**: An array of individual agentic resource card definitions. -* **`collections`**: Links to sub-catalogs or related departmental feeds. - -### Example baseline entry - -```json -{ - "specVersion": "1.0", - "host": { - "displayName": "Acme Systems", - "identifier": "acme.com" - }, - "entries": [ - { - "identifier": "urn:ai:acme.com:tool:ocr", - "displayName": "OCR Text Extractor", - "type": "application/mcp-server+json", - "url": "https://tools.acme.com/ocr/mcp.json", - "description": "Extracts plain text and structured tables from scanned PDFs and PNGs." - } - ] -} -``` - ---- - -## Progressive trust & compliance - -The `ai-catalog` standard decouples complex security and compliance data from lightweight metadata, using a `trustManifest` object within each entry. This facilitates: - -1. **Workload identity**: Binding agentic resources to SPIFFE IDs, decentralized identifiers (DIDs), or standard HTTPS domains. -2. **Compliance attestations**: Standardizing links to SOC2, HIPAA, GDPR, or ISO audits. -3. **Provenance links**: Recording lineage such as derived relationships (`derivedFrom`, `publishedFrom`) to enable supply-chain tracking. -4. **Cryptographic signatures**: Verifiable detached JWS signatures computed over the trust metadata to prevent tampering. diff --git a/docs/faq.md b/docs/faq.md index 3551732..5c6cdfd 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -21,7 +21,7 @@ Traditional tool selection requires stuffing every available schema into the sys ## Do I need to register my agentic resources on a central directory? -**No.** You have absolute publishing sovereignty. You host `ai-catalog.json` on your own domain (`yourdomain.com/.well-known/ai-catalog.json`) to advertise your agentic resources. Any compliant discovery service can find and index your endpoint organically, without requiring permission. +**No.** You have absolute publishing sovereignty. You host `ard.json` on your own domain (`yourdomain.com/.well-known/ard.json`) to advertise your agentic resources. Any compliant discovery service can find and index your endpoint organically, without requiring permission. --- @@ -35,7 +35,7 @@ Traditional tool selection requires stuffing every available schema into the sys The specification's role here is narrow and deliberate: it gives a publisher a **mechanism to assert verifiable claims**, and a registry or client a **standard way to check them**. ARD itself verifies nothing and vouches for no one. An entry can carry: -- **Domain-anchored identity** — a mechanism to declare a publisher domain in the entry's URN (`urn:ai:acme.com:...`), so identity is rooted in DNS rather than a self-asserted label and can be checked by whoever consumes the entry. +- **Domain-anchored identity** — a mechanism to declare a publisher domain in the entry's URN (`urn:air:acme.com:...`), so identity is rooted in DNS rather than a self-asserted label and can be checked by whoever consumes the entry. - **Verified publishers** — a mechanism for a publisher to *demonstrate* they are who they claim: a `trustManifest.identity` (e.g. `did:web`, SPIFFE, or an Agent Name Service (ANS) identity) that a registry or client cryptographically verifies against the publisher's domain. The protocol carries the claim; the registry or client performs the verification. - **Signed metadata** — a mechanism to attach a detached JWS `signature` over the trust manifest, so a client can confirm the record was not altered in transit or by an intermediary. - **Provenance** — a mechanism to declare lineage (`derivedFrom`, `publishedFrom`) that records where a resource came from. @@ -73,8 +73,8 @@ Discovery is only as permissive as the registry you ask. Because **whoever runs ARD also makes impersonation harder than the status quo, on several concrete fronts: -- **Identity** is anchored to a publisher's domain (`urn:ai:google.com:...`), not a self-asserted label. -- **Verified publishers**: a registry MUST verify that a manifest is actually hosted on — or cryptographically bound (via `did:web`/SPIFFE) to — the domain it claims, so a manifest on `untrusted.com` cannot pose as `urn:ai:google.com:...`. +- **Identity** is anchored to a publisher's domain (`urn:air:google.com:...`), not a self-asserted label. +- **Verified publishers**: a registry MUST verify that a manifest is actually hosted on — or cryptographically bound (via `did:web`/SPIFFE) to — the domain it claims, so a manifest on `untrusted.com` cannot pose as `urn:air:google.com:...`. - **Signed metadata** lets a client confirm a record was not altered in transit, and **provenance** lets it trace where a resource came from. Compared with today's ad hoc wiring — copy-pasted endpoints with no identity or provenance — ARD raises the floor by giving every result a verifiable origin. It does not, on its own, decide what is safe; it **communicates the identity, verification, and provenance signals** that let curated registries and clients refuse what is not. diff --git a/docs/get_started.md b/docs/get_started.md index 64571b3..e1ecaf5 100644 --- a/docs/get_started.md +++ b/docs/get_started.md @@ -9,7 +9,7 @@ hide: The ARD specification is open and available now. Pick the path that fits you: - **Use it in a chatbot:** Add a [connector](connect.md), such as GitHub's Agent Finder or Hugging Face Discover, to Claude, ChatGPT, Copilot, or Gemini so your assistant can discover tools, skills, and agents for a task — and you decide what to install. -- **Publish your first catalog:** Follow the [publishing guide](how_to_publish.md) to host an `ai-catalog.json` file on your own domain and make your agentic resources discoverable in minutes. +- **Publish your first catalog:** Follow the [publishing guide](how_to_publish.md) to host an `ard.json` file on your own domain and make your agentic resources discoverable in minutes. - **Build a client:** Use the [client guide](how_to_build_a_client.md) to discover and invoke agentic resources at runtime, instead of hardcoding them into your agent. - **Read the specification:** Dig into the [ARD specification](spec.md) — the full data model, search and federation semantics, and the trust model. - **Get involved & give feedback:** ARD is developed in the open. Browse the code and reference implementations on [GitHub](https://github.com/ards-project), and share feedback, questions, bug reports, or proposed changes through the [ARD-spec issue tracker](https://github.com/ards-project/ard-spec). diff --git a/docs/glossary.md b/docs/glossary.md index f1d43b0..cd03dd8 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -12,12 +12,16 @@ A *product*: one discovery service built on ARD — [github.com/agentfinder](htt ### AI Catalog -The base, artifact-agnostic manifest standard ARD builds on. A publisher hosts an `ai-catalog.json` file describing its agentic resources. See the [AI Catalog Standard](ai_catalog_spec.md). +A separate manifest standard that predates ARD and shares much of its vocabulary. ARD defines its own [ARD entry](#ard-entry) and its own manifest at `ard.json`; the two are independent specifications. ### AI client An orchestrator, agent, or harness — a chatbot, IDE assistant, or automation — that discovers agentic resources through ARD and invokes the ones it selects over their native mechanisms. Also just *client*. +### ARD entry + +The unit ARD is defined over: the description of a single agentic resource in a form that can be found by search. Every ARD entry is a well-formed catalog entry, but not every catalog entry is an ARD entry — an entry without [representative queries](#representative-queries) cannot be found by search. + ### ARD (Agentic Resource Discovery) The open protocol defined by this specification: how agentic resources describe themselves, how clients ask for them, and how discovery services answer — all *before* invocation. @@ -26,9 +30,9 @@ The open protocol defined by this specification: how agentic resources describe A verifiable claim attached to a catalog entry's `trustManifest` (e.g. SOC2, HIPAA, GDPR) that a registry or client can fetch and check. -### Capability manifest +### ARD manifest -Another name for the `ai-catalog.json` file a publisher hosts to advertise its agentic resources. +The document a publisher hosts at `https:///.well-known/ard.json` to advertise its agentic resources: a JSON document with an `entries` array of ARD entries. ### Catalog entry @@ -52,7 +56,7 @@ The IANA media type in a catalog entry's `type` field, identifying what an artif ### Publisher -Whoever hosts an `ai-catalog.json` describing one or more agentic resources, typically at `https:///.well-known/ai-catalog.json`. +Whoever hosts an `ard.json` describing one or more agentic resources, typically at `https:///.well-known/ard.json`. ### Referral @@ -76,8 +80,8 @@ Optional verifiable identity and trust metadata on a catalog entry (`trustManife ### URN identifier -A catalog entry's domain-anchored logical identifier, `urn:ai:::`, where `` is a verifiable domain. It roots identity in DNS and stays stable as infrastructure changes. +A catalog entry's domain-anchored logical identifier, `urn:air:::`, where `` is a verifiable domain. It roots identity in DNS and stays stable as infrastructure changes. ### Well-known URI -The conventional manifest location, `https:///.well-known/ai-catalog.json`, where discovery services look for a publisher's catalog. +The conventional manifest location, `https:///.well-known/ard.json`, where discovery services look for a publisher's entries. diff --git a/docs/how_ard_works.md b/docs/how_ard_works.md index 7eed187..170b26f 100644 --- a/docs/how_ard_works.md +++ b/docs/how_ard_works.md @@ -4,7 +4,7 @@ ARD in five steps — from describing a resource to using it from a chatbot. ## 1. Describe each resource -Agentic resources come in many forms — tools, Skills, MCP servers, APIs, workflows, and agents. The **[AI Catalog](ai_catalog_spec.md)** standard gives you one extensible way to describe any of them: what it does, who provides it, where it lives, and how a client reaches it. +Agentic resources come in many forms — tools, Skills, MCP servers, APIs, workflows, and agents. The **[ARD entry](glossary.md#ard-entry)** gives you one extensible way to describe any of them: what it does, who provides it, where it lives, and how a client reaches it. ## 2. Discovery is the hard part diff --git a/docs/how_to_build_a_client.md b/docs/how_to_build_a_client.md index a2e08b8..9c7a13e 100644 --- a/docs/how_to_build_a_client.md +++ b/docs/how_to_build_a_client.md @@ -64,7 +64,7 @@ need — plus optional referrals: { "results": [ { - "identifier": "urn:ai:acme.com:travel:concierge", + "identifier": "urn:air:acme.com:travel:concierge", "displayName": "Travel Concierge", "type": "application/mcp-server+json", "url": "https://api.acme.com/mcp/travel.json", @@ -74,7 +74,7 @@ need — plus optional referrals: ], "referrals": [ { - "identifier": "urn:ai:example.org:registry", + "identifier": "urn:air:example.org:registry", "type": "application/ai-registry", "url": "https://finder.example.org/search" } @@ -91,7 +91,7 @@ rating — do that independently (Step 4). Before connecting to or invoking a discovered resource, verify the publisher: 1. **Extract the domain** — parse the FQDN authority from the URN identifier - (`urn:ai:acme.com:travel:…` ➜ `acme.com`). + (`urn:air:acme.com:travel:…` ➜ `acme.com`). 2. **Verify identity** — fetch the manifest and confirm the `trustManifest.identity` (e.g. a SPIFFE ID or `did:web`) is bound to that domain. diff --git a/docs/how_to_publish.md b/docs/how_to_publish.md index d55022d..f9a46ac 100644 --- a/docs/how_to_publish.md +++ b/docs/how_to_publish.md @@ -6,17 +6,12 @@ This guide is about publishing on the public internet so that public discovery s --- -## Step 1: Create the manifest (`ai-catalog.json`) +## Step 1: Create the manifest (`ard.json`) -Create a static `ai-catalog.json` manifest listing your agentic resources. Below is a copy-pasteable template: +Create a static `ard.json` manifest listing your agentic resources. Below is a copy-pasteable template: ```json { - "specVersion": "1.0", - "host": { - "displayName": "Acme Dev Tools", - "identifier": "did:web:acme.com" - }, "entries": [ { "identifier": "urn:air:acme.com:server:weather", @@ -43,7 +38,7 @@ Create a static `ai-catalog.json` manifest listing your agentic resources. Below Upload the manifest to your domain: ```text -https:///.well-known/ai-catalog.json +https:///.well-known/ard.json ``` Ensure your web server serves it with: @@ -60,7 +55,7 @@ If you cannot host at the standard `.well-known` path, publish a DNS `TXT` recor | Name / Host | Type | Value | | :--- | :--- | :--- | -| `_catalog._agents.yourdomain.com` | `TXT` | `"url=https://custom-bucket.s3.amazonaws.com/ai-catalog.json"` | +| `_catalog._agents.yourdomain.com` | `TXT` | `"url=https://custom-bucket.s3.amazonaws.com/ard.json"` | For dynamic discovery services (`POST /search`), publish an `SRV` record: diff --git a/docs/index.md b/docs/index.md index e955226..5efd2be 100644 --- a/docs/index.md +++ b/docs/index.md @@ -12,7 +12,7 @@ ARD sits entirely before invocation. It helps the client find the right resource ## What is an agentic resource? -An agentic resource is any external capability an AI client can call on to do a task — an agent, MCP server, Skill, Canvas, Plugin, API, or workflow — anything that can be represented as an [AI Catalog entry](ai_catalog_spec.md). +An agentic resource is any external capability an AI client can call on to do a task — an agent, MCP server, Skill, Canvas, Plugin, API, or workflow — anything that can be described as an [ARD entry](glossary.md#ard-entry). ## What ARD is not diff --git a/docs/interoperability.md b/docs/interoperability.md index 9fb89d4..64da8e6 100644 --- a/docs/interoperability.md +++ b/docs/interoperability.md @@ -11,7 +11,7 @@ ARD is designed as a **superset** of existing agent and tool discovery approache The ecosystem already has many **curated collections of agentic resources**: registries for MCP servers and A2A agents, plugin directories like [Open Plugins](https://open-plugins.com/), and platform tool catalogs from some partners. Each is a **centralized directory** — resources are submitted to it, it owns the canonical list, and clients query that one list. They're useful, but each is an island, with its own onboarding, governance, and reach. -ARD inverts the relationship. Instead of publishing *into* each collection, a publisher describes a resource once on its own domain (`yourdomain.com/.well-known/ai-catalog.json`), and any discovery service can index it organically — no central gatekeeper, no per-collection re-registration. Discovery becomes a property of the open web, the way search engines crawl sites, rather than a list owned by one operator. +ARD inverts the relationship. Instead of publishing *into* each collection, a publisher describes a resource once on its own domain (`yourdomain.com/.well-known/ard.json`), and any discovery service can index it organically — no central gatekeeper, no per-collection re-registration. Discovery becomes a property of the open web, the way search engines crawl sites, rather than a list owned by one operator. These collections don't disappear in this model — they become **ARD discovery services**. A registry, plugin directory, or tool catalog can index ARD entries from across the web, apply its own curation and trust policy, and expose the result; clients choose which to query, and they compose. So "ARD vs. a registry" is the wrong axis: ARD is the specification that lets *many* curated collections — public, vendor, and internal — index the same published resource without anyone having to choose just one. @@ -44,4 +44,4 @@ In short: built-in tool search selects among known tools; ARD is the layer that ## What about the ACP Agent Registry -The list of ACP agents in [ACP's Agent Registry](https://agentclientprotocol.com/get-started/registry) is already structurally close to the AI Catalog specification. ACP registries can export their directory manifests as standard `ai-catalog.json` feeds, enabling instant web-scale discovery for editor-context agents — without those agents having to be re-registered anywhere. +The list of ACP agents in [ACP's Agent Registry](https://agentclientprotocol.com/get-started/registry) is already structurally close to an ARD manifest. ACP registries can export their directory manifests as standard `ard.json` feeds, enabling instant web-scale discovery for editor-context agents — without those agents having to be re-registered anywhere. diff --git a/docs/ref_implementations.md b/docs/ref_implementations.md index 37f5514..d66f381 100644 --- a/docs/ref_implementations.md +++ b/docs/ref_implementations.md @@ -47,13 +47,13 @@ Call search directly at `POST https://agentfinder.github.com/api/v1/search`. The ## Cisco AI Catalog The [AGNTCY Agent Directory](https://dir.agntcy.org) reference implementation of ARD is deployed by the Cisco [AI Catalog](https://ai-catalog.outshift.io). -The catalog can be pulled from [`ai-catalog.outshift.io/.well-known/ai-catalog.json`](https://ai-catalog.outshift.io/.well-known/ai-catalog.json). +The catalog can be pulled from [`ai-catalog.outshift.io/.well-known/ard.json`](https://ai-catalog.outshift.io/.well-known/ard.json). It supports secure verification through trust manifests, so clients can validate publisher identity and resource integrity before use. ### 1. Pull the catalog manifest ```bash -curl -sS https://ai-catalog.outshift.io/.well-known/ai-catalog.json | jq '.specVersion, .host.displayName' +curl -sS https://ai-catalog.outshift.io/.well-known/ard.json | jq '.entries | length' ``` ### 2. Discover A2A cards @@ -74,7 +74,7 @@ curl -sS 'https://ai-catalog.outshift.io/v1/agents?filter=type%3Dapplication%2Fm The [Ora Directory](https://ora.directory) is an ARD discovery service over products and services that agents use on behalf of users, run by [Ora](https://ora.ai). Ora scans each product for agent-readiness — static checks against its docs, llms.txt, registries, and public APIs, plus live agent runs that attempt to use it end to end — and serves the results over the ARD protocol, alongside the MCP servers, Skills, and OpenAPI specs detected on each product, plus payable x402/MPP HTTP endpoints with per-call pricing, indexed from the public Bazaar registry. Every product entry carries its agent-readiness scorecard as a signed trust attestation, so a client can weigh not only whether a resource matches the task, but whether it has been observed to work for agents. -Ora's publisher manifest at [`ora.ai/.well-known/ai-catalog.json`](https://ora.ai/.well-known/ai-catalog.json) describes Ora's own resources and advertises the registry: its `application/ai-registry+json` entry points at `https://ora.ai/api/ard`, which serves a self-describing descriptor listing the endpoints. The index itself is queried through those endpoints. +Ora's publisher manifest at [`ora.ai/.well-known/ard.json`](https://ora.ai/.well-known/ard.json) describes Ora's own resources and advertises the registry: its `application/ai-registry+json` entry points at `https://ora.ai/api/ard`, which serves a self-describing descriptor listing the endpoints. The index itself is queried through those endpoints. ### Search and browse diff --git a/mkdocs.yml b/mkdocs.yml index eff26b5..ee7e6a1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -84,6 +84,8 @@ plugins: why.md: how_ard_works.md # 'Connect Copilot' was split into separate GitHub / Microsoft pages. connect/copilot.md: connect/github-copilot.md + # 'AI Catalog Standard' removed: ARD defines its own entry and manifest. + ai_catalog_spec.md: interoperability.md # Navigation nav: @@ -109,7 +111,6 @@ nav: - Reference Implementations: ref_implementations.md - Specifications: - ARD Specification: spec.md - - AI Catalog Standard: ai_catalog_spec.md - Give feedback: '/faq/#how-can-i-give-feedback' # Copyright