| Internet-Draft | ARD Manifest and Lookup | October 2026 |
| Bu, et al. | Expires 3 May 2027 | [Page] |
This document specifies the catalog representation and lookup protocol for Agent Resource Discovery (ARD), an open architecture for publishing, discovering, and searching software agent capabilities across federated networks. ARD defines a JSON-LD capability description envelope (the ARD Entry) and catalog container (the ARD Manifest) identified by domain-anchored Uniform Resource Names (URNs), cryptographic publisher authority bindings (the Trust Manifest), and an HTTP query interface supporting structured, semantic, and federated search across registries. Initial contact for discovering catalog entry points and active agent registration are specified in companion ARD documents.¶
This note is to be removed before publishing as an RFC.¶
The latest revision of this draft can be found at https://mindpower.github.io/ietf-draft-agent-resources-discovery/draft-bu-dawn-ard-discovery.html. Status information for this document may be found at https://datatracker.ietf.org/doc/draft-bu-dawn-ard-discovery/.¶
Discussion of this document takes place on the Discovery of Agents With Names (DAWN) Proposed Working Group mailing list (mailto:dawn@ietf.org), which is archived at https://mailarchive.ietf.org/arch/browse/dawn/. Subscribe at https://www.ietf.org/mailman/listinfo/dawn/.¶
Source for this draft and an issue tracker can be found at https://github.com/mindpower/ietf-draft-agent-resources-discovery.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 3 May 2027.¶
Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
Software agents and automated orchestrators increasingly interact with external, callable capabilities — such as Model Context Protocol (MCP) servers [MCP], Agent-to-Agent (A2A) agents [A2A], web APIs, and modular skills. In this document, callable capabilities providing programmatic services to automated systems are referred to generically as "agentic resources."¶
The overall Agent Resource Discovery (ARD) architecture, deployment topologies, and design principles are described in [ARD-ARCH]. Within the ARD protocol suite, initial contact for locating a domain's manifest or registry entry point URI is specified in [ARD-INITIAL-CONTACT], and active registration of live workloads with an Agent Directory is specified in [AGENT-DIRECTORY].¶
This document specifies the Manifest Representation and Lookup Protocol for ARD:¶
The ARD Entry and Manifest Format (Section 3): Defines the JSON-LD [JSON-LD] capability description envelope (ARD Entry), the application/ard+json container format (ARD Manifest), and the domain-anchored Uniform Resource Name (URN) syntax (urn:air:<publisher>:<namespace>:<agent-name>) [RFC8141].¶
Cryptographic Trust and Authority Binding (Section 3.5): Defines the optional trustManifest envelope (sealed using RFC 8785 JCS [RFC8785] and RFC 7515 detached JWS [RFC7515]) and artifact digest binding that allow consumers and multi-domain aggregators to verify publisher authority and third-party evaluations independently of the serving origin.¶
Lookup, Search, and Federated Discovery (Section 4): Defines the HTTP REST interface (POST /search, POST /explore, and GET /agents) for structured filtering, semantic vector search, faceted exploration, and federated routing (auto, referrals, and none) across ARD Registries.¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
This document uses the architectural terminology (Agentic Resource, ARD Entry, Manifest, Registry, Publisher, Domain Owner, Consumer, Discovery Identifier, and Trust Manifest) defined in [ARD-ARCH].¶
The primary information model of ARD is the ARD Entry — the description of a single agentic resource carrying both core descriptive metadata and the discovery signals (representativeQueries and structured capabilities) required to make resources comparable and discoverable across publishers. ARD is defined over ARD entries; the container an entry travels in (a hosted manifest/catalog or a registry API response) is a transport concern.¶
An ARD entry is a JSON-LD node. The authoritative ARD base context is published at:¶
https://agenticresourcediscovery.org/context/v1¶
The base context maps core terms to Internationalized Resource Identifiers (IRIs) under the namespace https://agenticresourcediscovery.org/ns#.¶
A conforming ARD consumer or registry MUST interpret an entry by applying the ARD base context as the initial expansion context (the JSON-LD expandContext option). An entry's local @context, when present, is layered on top of the base context: it MAY introduce new namespace prefixes or override existing ones, but does not discard the base. Under this rule, core terms resolve to their standard IRIs, while namespaced extension terms resolve through the prefixes declared in the entry.¶
Including @context in an entry is OPTIONAL when served within an ARD manifest, as compliant processors automatically inject the base context. An entry SHOULD include @context when exchanged outside an ARD manifest (such as in generic JSON-LD documents or third-party feeds) where generic processors might otherwise lack the base context.¶
The following fields comprise an ARD entry:¶
A globally unique, domain-anchored URN following the syntax defined in Section 3.4 (e.g., urn:air:example.com:agent:flight-finder) that identifies a specific agentic resource instance published under the <publisher> domain's authority (rather than an abstract capability class shared across independent vendors). The JSON-LD @id MAY mirror this identifier.¶
A human-readable display name for the agentic resource.¶
The artifact media type formatted as an IANA Media Type string (e.g., application/mcp-server-card+json, application/a2a-agent-card+json).¶
The capability payload delivery mechanism. An entry MUST specify either url or data, but MUST NOT specify both (see Section 3.3).¶
A list of 2 to 5 representative natural language user prompts or queries that this capability is designed to fulfill — the primary signal from which registries build semantic vector indices. Omitting this field severely degrades search discoverability. Conformance tooling flags missing or under-populated queries as a warning rather than a hard failure to accommodate entries originating from basic catalogs.¶
Strings naming specific skills or tools exported by the resource (e.g., ["WeatherQuery", "ForecastLookup"]) or JSON-LD vocabulary terms mapped via @context that enable high-performance structured filtering without fetching the complete artifact card.¶
A detailed natural language summary of the capability, its purpose, and operational characteristics.¶
Categorical tags for indexing (e.g., ["travel", "finance", "utility"]).¶
A version identifier (e.g., SemVer 1.2.0).¶
An algorithm-prefixed cryptographic digest (<alg>:<hex>, e.g., sha256:9f86d08...) of the target artifact referenced by url (or inline data). Implementations MUST support sha256 and MAY support additional collision-resistant hash algorithms (such as sha384 or sha512).¶
An [RFC9110] or ISO 8601 UTC timestamp indicating when the record was last modified.¶
An open key-value mapping for arbitrary operational metadata (e.g., rate limits, region availability).¶
A cryptographic trust envelope containing publisher identity assertions, provenance chains, and compliance attestations (see Section 3.5).¶
An entry delivers its capability manifest through either reference (url) or value (data):¶
Reference (url - Primary Link-Based Model): A URI pointing directly to the external artifact descriptor (such as an Agent Card, OpenAPI schema, or MCP server manifest). ARD is fundamentally link-based: the registry indexes discovery metadata and returns reference links, leaving the client to fetch operational descriptors directly from the capability host. This ensures that the registry remains strictly decoupled from the runtime execution data path and avoids serving as a proxy or single point of failure. When an entry using url carries content-bound attestations in trustManifest, the entry SHOULD include digest to lock the referenced descriptor's content against post-publication modification at url.¶
Value (data - Inline Fallback): The complete artifact document embedded directly inline as a JSON object. This is provided as an optional mechanism for standalone, isolated, or air-gapped environments where an additional network resolution round-trip is impossible or undesirable.¶
An entry MUST carry exactly one of url or data, and MUST NOT include both.¶
The discovery identifier MUST be a Uniform Resource Name (URN) adhering to [RFC8141] using the formal urn:air: namespace prefix:¶
urn:air:<publisher>:<namespace>:<agent-name>¶
Where:¶
urn:air: The assigned ARD namespace identifier.¶
<publisher>: The fully qualified domain name (FQDN) of the publishing authority (e.g., example.com, cloud.google.com).¶
<namespace>: A sub-organization, project, or category identifier defined by the publisher (e.g., travel, devtools, hr).¶
<agent-name>: A unique name identifying the agentic resource instance within that publisher's namespace.¶
This domain-anchored structure guarantees global uniqueness without requiring a centralized naming committee, leverages existing DNS ownership for authority, and allows registries to parse publisher boundaries deterministically.¶
Separating the logical resource identifier (urn:air:...) from physical content delivery (url or data) serves several protocol requirements:¶
Uniform Identity Across url and Inline data: Entries delivered by value via data (such as inline skills, prompt templates, or embedded MCP configurations) do not have a separate artifact url. The urn:air identifier provides a uniform primary key regardless of delivery mode.¶
Origin Independence and Deduplication: A resource's physical hosting url may change across staging and production environments, CDN mirrors, or cloud providers without changing the logical resource. The (identifier, version) tuple enables crawlers, registries, and federated peers to deduplicate entries and correlate third-party trustManifest evaluations across catalogs, while keeping provenance links (provenance[].sourceId) stable across hosting migrations.¶
Cryptographic Publisher Binding vs. Hosting Origin: Note that the HTTP origin hosting the manifest (/.well-known/ard.json), the <publisher> domain in the URN, and the host in the entry's url field do not need to be the same domain. For example, a catalog hosted at https://example.com/.well-known/ard.json may include an entry published by abc.com (urn:air:abc.com:agent:flight-finder) whose descriptor url is hosted on a cloud provider (https://xyz.execute-api.us-east-1.amazonaws.com/agent.json), where the TLS certificate of url belongs to the cloud provider rather than abc.com. An unverified urn:air:<publisher>:... string carries no implicit trust; binding the URN to <publisher> requires verifying a trustManifest signed by a key authorized by <publisher> (e.g., did:web:<publisher>). Because a manifest or registry response can contain entries from multiple publishers, each entry carries its full urn:air:<publisher>:... URN rather than a relative suffix.¶
Separation from Runtime Workload Identity: Whereas runtime workload identifiers (such as spiffe:// or WIMSE Workload Identity Tokens) authenticate live execution instances during active registration ([AGENT-DIRECTORY]) or runtime invocation, urn:air identifies the published catalog artifact across versions and registries.¶
To satisfy enterprise compliance, supply-chain verification, and zero-trust policies, an ARD entry MAY carry a trustManifest object (or a trustManifests array when multiple parties — such as the original publisher and an independent security auditor — attach separate signed manifests to the same entry):¶
{
"identifier": "urn:air:example.com:agent:flight-finder",
"type": "application/a2a-agent-card+json",
"version": "1.2.0",
"url": "https://agents.example.com/flight-finder/agent.json",
"digest": "sha256:9f86d081884c7d659a2feaa0c55ad015...",
"trustManifest": {
"identity": "did:web:example.com",
"issuedAt": "2026-03-20T14:00:00Z",
"subject": {
"identifier": "urn:air:example.com:agent:flight-finder",
"type": "application/a2a-agent-card+json",
"version": "1.2.0",
"digest": "sha256:9f86d081884c7d659a2feaa0c55ad015..."
},
"attestations": [
{
"type": "https://slsa.dev/provenance/v1",
"uri": "https://example.com/attestations/slsa.json",
"mediaType": "application/vnd.in-toto+json",
"digest": "sha256:7f83b1657ff1fc53b92dc18148a1d65d..."
}
],
"signature": "eyJhbGciOiJFUzI1NiIsImtpZCI6ImRpZDp3ZWI6..."
}
}
¶
Each trustManifest object is a self-contained signed envelope with the following core fields and signature semantics:¶
identity (String, MUST): The cryptographic signer identifier (for example, did:web:example.com, resolved over HTTPS from https://example.com/.well-known/did.json).¶
issuedAt (String, SHOULD) and expiresAt (String, MAY): ISO 8601 timestamps indicating when the manifest was signed and, for periodic third-party evaluations, when the assertion expires.¶
subject (Object, MUST): A self-contained block containing the target entry's release coordinates (identifier, type, digest, and version when present on the entry). Including subject directly inside trustManifest allows the manifest to be canonicalized and verified as a standalone JSON object without cross-level JSON stitching.¶
attestations (Array, MAY) and provenance (Array, MAY): Hash-pinned references (uri + digest) to external supply-chain or compliance evidence (such as SLSA build provenance, SPDX SBOMs, SARIF vulnerability scans, or SOC 2 audit reports) and artifact lineage links (sourceId + sourceDigest).¶
signature (String, MUST): A JSON Web Signature (JWS) [RFC7515] computed over the JSON Canonicalization Scheme (JCS) [RFC8785] serialization of the trustManifest object with the signature member removed. The JWS Protected Header specifies the signing algorithm (alg, with ES256 Mandatory-to-Implement) and key identifier (kid).¶
Attestations in trustManifest.attestations involve two distinct integrity bindings:¶
Binding the Attestation to the Target Artifact: To prevent attestation transplantation (where an attacker copies a valid attestation from one agent into another entry's metadata), each third-party attestation statement MUST either be a direct cryptographic signature over the artifact or include a signed subject claim that identifies the resource's identifier and/or the artifact's content digest. When the artifact is referenced via url rather than inline data, the ARD entry MUST include the top-level digest field so that the referenced bytes at url are bound to the attested digest.¶
Pinning the External Attestation Document (attestations[].digest): Because external attestation documents referenced by attestations[].uri (such as PDF compliance reports, SARIF scan results, or SLSA provenance files) may be hosted on external servers or in formats that do not carry self-contained signatures, the optional digest field inside each attestations[] item records the cryptographic hash of the external attestation document itself. Sealed under trustManifest.signature, this acts as a subresource integrity pin ensuring the external file at attestations[].uri cannot be replaced or modified after the trustManifest is signed.¶
All digest strings (digest, attestations[].digest, and provenance[].sourceDigest) use the algorithm-prefixed <alg>:<hex> format (e.g., sha256:...) to support hash agility; sha256 is Mandatory-to-Implement (MTI).¶
When published as a static catalog document (at an entry point URI discovered via [ARD-INITIAL-CONTACT], such as https://{domain}/.well-known/ard.json), ARD entries are packaged in an application/ard+json document containing a top-level entries array:¶
{
"entries": [
{
"identifier": "urn:air:acme.com:tools:weather",
"displayName": "Acme Weather Service",
"type": "application/mcp-server-card+json",
"url": "https://api.acme.com/mcp/weather.json",
"capabilities": ["CurrentWeather", "Forecast"],
"representativeQueries": [
"what is the weather in Seattle",
"get tomorrow's rain forecast"
]
}
]
}
¶
A publisher is not required to enumerate its capabilities in a static manifest; it MAY instead operate a dynamic Agent Registry exposing the query interface (Section 4.2) directly, or publish a minimal manifest containing a single application/ai-registry+json entry whose url advertises the Base URI of its dynamic Agent Registry service. For web crawlers, publishers MAY also signal their manifest in HTML <head> elements using <link rel="ard" type="application/ard+json" href="...">.¶
Whether a publisher exposes a dynamic Agent Registry directly or third-party registries aggregate entries across domains, clients query Agent Registries to perform structured, semantic, and faceted discovery.¶
An Agent Registry may operate as a publisher's own dynamic discovery endpoint, as a standalone search service that ingests entries via web crawling, or as a dual-role Agent Directory that pairs lookup with an active registration service. This document specifies the Lookup and Search Interface (Section 4.2 and Section 4.3), which builds upon two companion specifications:¶
Initial Contact and Entry Point Discovery ([ARD-INITIAL-CONTACT]): Clients and registry crawlers obtain manifest or registry entry point URIs using the mechanisms defined in [ARD-INITIAL-CONTACT] — including DNS Service Binding (SVCB / HTTPS) records under _entries._agents.<domain> or _search._agents.<domain>, DNS-Based Service Discovery (_ard._tcp) over unicast DNS or Multicast DNS, the baseline well-known URI (/.well-known/ard.json), and the ard HTTP link relation.¶
Active Registration and Soft-State Lifecycle ([AGENT-DIRECTORY]): For dual-role Agent Directories that accept active registrations from live agent workloads or Commissioning Tools (CTs), the registration wire protocol, soft-state lifetime (lt) renewals, and workload identity authentication (such as IETF WIMSE [WIMSE-ARCH] Workload Identity Tokens and Workload Proof Tokens, SPIFFE IDs, or ID-JAG assertions) are specified in [AGENT-DIRECTORY] (drawing from [RFC9176]). A registry MAY verify whether the asserted workload identity or trustManifest binds to the <publisher> domain declared in the entry's URN (see Section 3.5.1) and use the outcome for verified status indicators, filtering, ranking, or admission decisions.¶
Registries populate and refresh their discovery indices through automated ingestion and crawling pipelines that:¶
Discover and fetch publisher /.well-known/ard.json manifests, HTTP ard link relations, HTML <link rel="ard"> tags, and DNS-advertised entry points over TLS 1.3 (per [ARD-INITIAL-CONTACT]).¶
Ingest validated manifests and entries from software repositories, package registries, and federated peer registries.¶
As in [ARD-INITIAL-CONTACT] and the CoRE Resource Directory architecture (Section 7.2 of [RFC9176]), a discovery channel or registry is authoritative for its own lookup and search responses, not for the third-party agent resources it lists. Entry point URIs and entries ingested from static manifests, HTML <link rel="ard"> tags, package registries, or federated peer registries serve as discovery hints until publisher authority and artifact integrity are verified via the entry's signed trustManifest and the target resource at url (see Section 4.3.1 and Section 6.2).¶
In accordance with BCP 56 [RFC9205], compliant Agent Registries MUST expose an HTTP query interface over HTTPS conforming to [RFC9110] (supporting HTTP/1.1 and HTTP/2, and optionally HTTP/3), MAY additionally offer protocol-specific wrappers, and MAY document their endpoints using the OpenAPI Specification [OpenAPI]. A registry discovers peer registries by recognizing entries whose type is application/ai-registry+json.¶
To avoid squatting on root URI paths ([RFC8615], Section 4.3 of [RFC9205]), the endpoint paths /search, /explore, and /agents defined in this section are relative to the Registry's discovered Base URI (advertised in the url field of the registry's application/ai-registry+json entry, e.g., https://registry.example.com/ard/v1). Requests with a message body and successful responses use the application/json media type unless a specific profile media type is negotiated via Accept / Content-Type headers.¶
Search and introspection endpoints accept a unified query object comprising three optional elements: @context, text, and filter:¶
{
"query": {
"@context": {
"okf": "https://openknowledgeformat.org/ns#"
},
"text": "book a round-trip flight to Tokyo next Monday",
"filter": {
"type": ["application/a2a-agent-card+json"],
"tags": ["travel", "booking"],
"okf:regulatoryZone": ["JP", "US"],
"trustManifest.attestations.type": ["SOC2-Type2"]
}
}
}
¶
@context: Defines JSON-LD prefix mappings used for keys inside filter.¶
text: Natural language user intent used for semantic relevance matching and vector search.¶
filter: Key-value map of exact structural constraints. Keys represent term paths (resolved via @context and the base context). Values are arrays combined with OR logic; multiple keys are combined with AND logic.¶
POST /search)
The Search endpoint executes semantic ranking combined with structured filtering over the registry index.¶
{
"query": {
"text": "flight booking assistant",
"filter": {
"type": ["application/a2a-agent-card+json"]
}
},
"federation": "referrals",
"pageSize": 5,
"pageToken": "eyJwYWdlIjoxfQ=="
}
¶
Parameters:¶
query.text (String, MUST): The semantic search prompt.¶
query.filter (Object, OPTIONAL): Structured filter constraints.¶
federation (String, OPTIONAL): Federation routing mode ("auto", "referrals", or "none", default: "auto").¶
pageSize (Integer, OPTIONAL): Maximum results to return (default: 10, max: 100).¶
pageToken (String, OPTIONAL): Pagination cursor token.¶
{
"results": [
{
"identifier": "urn:air:skyways.com:agents:flight-booker",
"displayName": "Skyways Flight Booker",
"type": "application/a2a-agent-card+json",
"url": "https://api.skyways.com/agents/booking.json",
"score": 96,
"source": "https://registry.skyways.com"
}
],
"referrals": [
{
"identifier": "urn:air:globaltravel.org:registry:main",
"displayName": "Global Travel Agent Registry",
"type": "application/ai-registry+json",
"url": "https://registry.globaltravel.org/search"
}
],
"nextPageToken": "eyJwYWdlIjoyfQ=="
}
¶
The score integer parameter (0 to 100) indicates informational semantic relevance calculated by the registry.¶
POST /explore)
The Explore endpoint allows clients to introspect registry contents, aggregate distributions, and inspect available facets without returning full entry records.¶
{
"query": {
"filter": {
"type": ["application/mcp-server-card+json"]
}
},
"resultType": {
"facets": [
{ "field": "capabilities", "limit": 10 },
{ "field": "publisher", "limit": 5 }
]
}
}
¶
{
"resultType": "facets",
"facets": {
"capabilities": {
"buckets": [
{ "value": "WeatherTool", "count": 142 },
{ "value": "WebSearch", "count": 98 }
],
"otherCount": 12
}
}
}
¶
GET /agents)
A lightweight, cacheable HTTP GET endpoint for administrative browsing, catalog synchronization, and developer tooling. Supports standard query parameters: pageSize, pageToken, and a deterministic filter query string.¶
When a query fails or cannot be processed, conforming registries MUST return an appropriate HTTP status code and SHOULD return an HTTP Problem Details object (application/problem+json) conforming to [RFC9457] (per Section 4.7 of [RFC9205]), including a machine-readable error code extension member:¶
{
"type": "https://agenticresourcediscovery.org/problems/invalid-argument",
"title": "Invalid Argument",
"status": 400,
"detail": "Malformed query JSON or unsupported filter term.",
"error": "INVALID_ARGUMENT"
}
¶
| HTTP Status | Error Code | Description |
|---|---|---|
| 400 Bad Request |
INVALID_ARGUMENT
|
Malformed query JSON, missing required fields, or invalid filter syntax. |
| 401 Unauthorized |
UNAUTHENTICATED
|
Missing or invalid authentication credentials. |
| 403 Forbidden |
PERMISSION_DENIED
|
Caller lacks sufficient access permissions for the registry or resource. |
| 404 Not Found |
NOT_FOUND
|
Specified agent identifier, registry, or endpoint does not exist. |
| 429 Too Many Requests |
RATE_LIMIT_EXCEEDED
|
Request rate limit exceeded; server SHOULD include a Retry-After header field ([RFC9110]) and client SHOULD retry with backoff. |
| 500 Internal Server Error |
INTERNAL_ERROR
|
Internal server or unhandled storage failure. |
| 501 Not Implemented |
NOT_IMPLEMENTED
|
Requested feature (e.g., Explore endpoint or unsupported federation mode) is not implemented. |
Registries coordinate in a decentralized mesh using the federation parameter:¶
auto: The queried registry forwards the query to its upstream peer registries, aggregates and de-duplicates the result sets, and returns a unified response to the client.¶
referrals: The registry returns its own local matches along with a list of referrals pointing to downstream or domain-specific registries. The client decides which registries to query next.¶
none: The registry queries only its locally indexed entries.¶
Figure 1 illustrates the query flows for the auto and referrals modes (whereas none restricts search to Registry A's local index):¶
Mode 1: "auto" (Recursive) Mode 2: "referrals" (Iterative)
+----------+ +----------+ +----------+ +----------+
| Consumer |------->| Registry | | Consumer |------->| Registry |
| |<-------| A | | |<-------| A |
+----------+ Agg. +----------+ +----------+ Local +----------+
Results | ^ | ^ + Referrals
Fwd | | Peer | |
Query | | Results | +--- Follow Referral
v | | Query / Results
+----------+ | +----------+
| Peer | +------->| Peer |
| Registry | | Registry |
+----------+ +----------+
To prevent infinite loops and denial-of-service amplification across federated registries, registries MUST maintain a hopCount and reject or truncate queries exceeding a maximum hop limit (default: 3 hops).¶
Federated discovery introduces two distinct verification boundaries:¶
Non-Authoritative Downstream Registries: In both "auto" and "referrals" modes, peer registries act as non-authoritative discovery intermediaries (analogous to Section 7.2 of [RFC9176]). A TLS connection to a registry authenticates only that registry (source), not the <publisher> of the entries it returns. Consequently, neither an aggregating registry in "auto" mode nor a client following "referrals" MUST rely on transport trust in a downstream registry to establish publisher authority. Instead, consumers and verifying registries MUST validate each entry's signed trustManifest against the <publisher> domain (and any third-party verifier trustManifest against the verifier's identity); entries lacking a verified publisher trustManifest MUST be treated as unverified discovery hints. In "referrals" mode, clients can also evaluate the referred registry's identity before transmitting sensitive query text.¶
Binding Location url to the Target Origin: A valid trustManifest signature from <publisher> proves that <publisher> authorized the entry (urn:air:<publisher>:...), but if url points to a different origin (for example, urn:air:attacker.example:agent:foo specifying "url": "https://victim.example.com/service"), <publisher>'s signature alone does not prove that the target origin (victim.example.com) consented to host that resource. When the origin of url differs from https://<publisher>, consumers and verifying registries MUST verify that the artifact descriptor retrieved from url matches the entry's signed cryptographic digest and explicitly declares the matching identifier (urn:air:<publisher>:...) or publisher identity (trustManifest.identity) before invoking the resource.¶
When a consumer specifies "federation": "referrals", the registry returns its direct capability matches in results alongside an array of referrals pointing to downstream or specialized registries matching the query scope:¶
Request:¶
{
"query": {
"text": "find corporate travel booking agents"
},
"federation": "referrals"
}
¶
Response:¶
{
"results": [
{
"identifier": "urn:air:example.com:agent:internal-travel",
"displayName": "Internal Corporate Travel Assistant",
"type": "application/a2a-agent-card+json",
"url": "https://corp.example.com/agents/travel.json",
"score": 92,
"source": "https://registry.corp.example.com"
}
],
"referrals": [
{
"identifier": "urn:air:travelmesh.org:registry:global",
"displayName": "Global Travel Agent Registry",
"type": "application/ai-registry+json",
"url": "https://finder.travelmesh.org/search"
},
{
"identifier": "urn:air:partnernet.com:registry:alliances",
"displayName": "Airline Alliances Registry",
"type": "application/ai-registry+json",
"url": "https://registry.partnernet.com/search"
}
]
}
¶
The normative grammar of the ARD manifest, entry, and REST payloads is defined in Concise Data Definition Language (CDDL) [RFC8610]:¶
start = ard-manifest
; --- The Manifest ---
ard-manifest = {
entries: [* ard-entry],
* tstr => any
}
; --- The ARD Entry ---
ard-entry = {
ard-entry-required,
ard-entry-descriptive,
* tstr => any
}
ard-entry-required = (
; URN: urn:air:{publisher}:{namespace}:{agent-name}
identifier: tstr,
displayName: tstr,
type: tstr, ; IANA Media Type
content-delivery ; value-or-reference
)
ard-entry-descriptive = (
? "@context" => any,
? "@id" => tstr,
? description: tstr,
? tags: [+ tstr],
? capabilities: [+ tstr],
? representativeQueries: [* tstr],
? version: tstr,
? digest: tstr,
? updatedAt: tstr,
? metadata: {* tstr => any},
? trustManifest: trust-manifest,
? trustManifests: [+ trust-manifest]
)
content-delivery = (
url: tstr //
data: {* tstr => any}
)
; --- Trust Envelope ---
trust-manifest = {
identity: tstr,
? issuedAt: tstr,
? expiresAt: tstr,
? subject: trust-subject,
? identityType: tstr,
? trustSchema: trust-schema,
? attestations: [* attestation],
? provenance: [* provenance-link],
? signature: tstr,
* tstr => any
}
trust-subject = {
identifier: tstr,
type: tstr,
? version: tstr,
? digest: tstr,
? url: tstr,
* tstr => any
}
trust-schema = {
? identifier: tstr,
? version: tstr,
? governanceUri: tstr,
? verificationMethods: [* tstr],
* tstr => any
}
attestation = {
type: tstr,
uri: tstr,
? mediaType: tstr,
? digest: tstr,
* tstr => any
}
provenance-link = {
relation: tstr,
sourceId: tstr,
? sourceDigest: tstr,
* tstr => any
}
; --- Search API Payloads ---
query-model = {
? text: tstr,
? "@context" => any,
? filter: {* tstr => ([+ tstr] / tstr)}
}
search-request = {
query: query-model,
? federation: "auto" / "referrals" / "none",
? pageSize: uint,
? pageToken: tstr
}
search-response = {
results: [* search-result-item],
? referrals: [* registry-referral],
? nextPageToken: tstr
}
search-result-item = {
identifier: tstr,
? displayName: tstr,
? type: tstr,
? url: tstr,
? digest: tstr,
? trustManifest: trust-manifest,
score: 0..100,
source: tstr,
* tstr => any
}
registry-referral = {
identifier: tstr,
displayName: tstr,
type: "application/ai-registry+json",
url: tstr
}
; Helper types
any = any-cbor / any-json
any-cbor = bool / int / float / tstr / bstr /
[* any-cbor] / {* any-cbor => any-cbor}
any-json = bool / int / float / tstr / null /
[* any-json] / {* tstr => any-json}
null = nil
¶
Discovery protocols for autonomous systems operate in adversarial environments where malicious capability advertisements could misdirect automated actions, trigger unauthorized tool invocations, or exfiltrate private conversation contexts.¶
The ARD security architecture considers the following primary threat vectors:¶
Namespace Squatting and Impersonation: An attacker advertises an agent under a reputable organization's domain name (e.g., asserting urn:air:google.com:... without holding administrative control over google.com).¶
Relevance Score Poisoning (SEO Injection): An attacker injects deceptive, highly generic, or adversarial terms into representativeQueries or description to artificially inflate the agent's ranking in response to high-value user prompts (such as financial or credential-handling queries).¶
Attestation Transplantation: An attacker extracts a cryptographically valid compliance attestation (e.g., SOC2 or security audit) from a legitimate agent and embeds it into a malicious entry's metadata.¶
Federation Amplification and Query Loops: A hostile registry initiates recursive queries across federated peers designed to trigger exponential request explosion or denial-of-service loops.¶
Prompt and Intent Snooping: Eavesdroppers or untrusted intermediary registries harvest sensitive user query prompts (query.text) to extract proprietary enterprise context, personal data, or system prompts.¶
The score returned by POST /search represents solely mathematical text/semantic similarity between query.text and the indexed capability. Orchestrators and clients:¶
MUST NOT interpret score as an indicator of safety, quality, or authenticity.¶
MUST NOT execute privileged operations or expose sensitive credentials to an agent solely based on high search scores.¶
MUST evaluate security policies, verified trust manifests, and sandbox restrictions independently of the discovery ranking.¶
To prevent attestation transplantation and post-publication content substitution:¶
Artifact Subject Binding: Signed attestations referenced in trustManifest.attestations (such as SLSA [SLSA] or in-toto statements) MUST either directly sign the target artifact or bind to the resource's identifier and/or the artifact's algorithm-prefixed digest (<alg>:<hex>, with sha256 Mandatory-to-Implement). When an entry delivers its artifact by reference (url), consumers MUST compute the digest of the retrieved artifact and verify that it matches the entry's digest and the attestation subject before honoring any audit or provenance claims.¶
External Attestation Pinning: When an entry in trustManifest.attestations includes digest, consumers fetching the external attestation document from attestations[].uri MUST verify that the fetched document's digest matches attestations[].digest sealed by trustManifest.signature.¶
All ARD communications — including static manifest retrieval, DNS over HTTPS (DoH), registration endpoints, and search API queries — MUST use Transport Layer Security (TLS) 1.3 [RFC8446] or later in accordance with BCP 195 [RFC9325]. Implementations MUST use ephemeral key exchange providing forward secrecy and enforce strict certificate validation. Cleartext HTTP (plaintext) MUST NOT be permitted for any public discovery endpoint.¶
To prevent distributed denial-of-service amplification:¶
Registries implementing "auto" federation MUST decrement a Hop-Count header (maximum initial value: 3). Queries reaching Hop-Count: 0 MUST NOT be forwarded.¶
Registries MUST implement referral loop detection by tracking visited registry URIs in a query trail header.¶
Public registries SHOULD implement rate-limiting per client IP and authenticated identity.¶
When dynamic registration interfaces are exposed, registries SHOULD integrate with standard workload identity protocols such as WIMSE [WIMSE-ARCH]. Registration tokens MUST be short-lived, audience-restricted, and cryptographically verified against trusted identity providers.¶
Natural language queries submitted to POST /search inherently reflect the user's immediate intent, tasks, and potentially confidential context.¶
Query Eavesdropping: Queries transmitted over open networks can reveal user activities. Mandatory TLS 1.3 protects query confidentiality in transit.¶
Registry Logging and Profile Building: Third-party public registries could aggregate queries across time to build behavioral profiles of individuals or corporate entities. Conforming public registries SHOULD adopt strict data minimization, zero-retention, and query anonymization policies.¶
Client-Side Intent Filtering: Client orchestrators SHOULD sanitize query.text before transmission to external registries, stripping proprietary source code, credentials, personally identifiable information (PII), and session identifiers.¶
The ard.json Well-Known URI, ard Link Relation, and ard Service Name registrations are requested in the companion initial contact specification [ARD-INITIAL-CONTACT]. This document requests the Media Type and URN Sub-Namespace registrations below.¶
IANA is requested to register the following media types in the "Media Types" registry:¶
The authors would like to thank Eric Rescorla, Jari Arkko, Mirja Kühlewind, Warren Kumari, Wes Hardaker, Luca Muscariello, Darrel Miller, and Jonathan Hefner for their valuable architectural reviews, security feedback, and interoperability discussions.¶