| Internet-Draft | AREG | August 2026 |
| van Bussel | Expires 3 February 2027 | [Page] |
The Agent Registry (AREG) is an open, vendor-neutral specification for publishing, discovering, and resolving artificial intelligence (AI) agent definitions. An AREG registry entry is a lightweight metadata document that records where a specific version of an agent definition can be fetched, who published it, what version it is, and how consumers can verify its authenticity. AREG also defines a REST API that conforming registry servers implement to expose search, resolution, and publication endpoints to consumers and publishers.¶
AREG is the discovery and registry layer of the Schema Commons agent stack. It is designed to compose with the Autonomous Agent Interchange Format (AAIF, SC-006), which defines the content of the agent definition document that an AREG entry points to, and with the Agent Capability and Profile Model (ACPM, SC-014), which provides richer capability, trust, cost, and service-level information that a registry entry can reference. Neither AAIF nor ACPM is required for a conforming AREG implementation.¶
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 February 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.¶
A portable AI agent definition is only as useful as the infrastructure that lets others find it. Today, agents are shared by hard-coded URLs, proprietary marketplace databases, or not at all. There is no standard vocabulary for expressing that a specific version of an agent has been published, who is responsible for it, whether it has been retracted, or how to verify that the definition a consumer fetches is the same one the publisher intended to distribute.¶
This document specifies the Agent Registry (AREG): a registry entry document format and a REST API for registry servers. Together they provide a common, interoperable foundation for agent discovery across registries, orchestration platforms, and toolchains, without requiring a central registry authority.¶
AREG is the third member of the Schema Commons agent stack. The Autonomous Agent Interchange Format (AAIF) [SC-006] defines how to express a portable agent definition that any conforming runtime can execute. The Agent Capability and Profile Model (ACPM) [SC-014] defines how to describe what an agent, platform, tool, or model offers in terms of capabilities, trust, cost, and service level. AREG defines where to find a published agent and how to establish that the definition at a given URL has not been tampered with.¶
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.¶
AREG is in scope for: the registry entry document format; the REST API that registry servers implement; the signing model used to verify that a fetched agent definition has not been modified since publication; versioning semantics for entries; and yanking (soft retraction) semantics.¶
AREG is out of scope for: the content of the agent definition document at the entry's resolution URL (that is defined by AAIF [SC-006]); capability, trust, cost, and service-level description of the agent or registry server (that is defined by ACPM [SC-014]); transport security configuration; billing and rate limiting above and beyond what this specification mandates.¶
Entry, not copy. A registry entry is a pointer and metadata record. The authoritative agent definition lives at aaif_url. The registry does not re-host agent definitions.¶
Immutable versions. Once a (agent_id, agent_version) entry is published, aaif_url, signature, and published_at MUST NOT change. Corrections require a new version. This makes entries auditable and cacheable.¶
Soft deletes only. Yanking sets yanked to true but preserves the entry. Consumers can audit what was retracted and why; the record of a version's existence is never erased.¶
Signature is optional but fully specified. Not every publisher will sign. AREG defines the signing model precisely enough that a consumer can verify a signature when one is present, without requiring one.¶
Public reads, gated writes. Discovery is a public good. All GET endpoints MUST be accessible without authentication. Mutating endpoints MUST require authentication.¶
Decentralized by design. AREG defines no central registry authority. Any party can operate a conforming registry. Consumers may query multiple registries and merge results.¶
A registry entry is a flat JSON object. The following diagram shows its top-level structure (informative):¶
RegistryEntry (root)
sc_standard "SC-013" (required)
sc_version semver (required)
registry_id UUID — assigned by registry
agent_id UUID — from AAIF document (required)
agent_version semver — from AAIF document (required)
published_at date-time — set by registry on POST
updated_at date-time — set by registry on PATCH
publisher
name string (required)
url URI (required)
public_key_url URI — JWK Set or PEM endpoint
contact string — abuse/security contact
aaif_url URI (required)
signature compact JWS | null
tags[] string[]
conformance_level enum
required_capabilities[] string[]
acpm_profile_url URI | null
yanked boolean (default false)
yank_reason string | null
license string (SPDX ID)
¶
A registry server MUST expose the endpoints defined in this section under a stable base URL, referred to in this document as {server}. All paths below are relative to {server}/v1.¶
All request and response bodies are JSON (RFC 8259 [RFC8259]). Requests that include a body MUST send Content-Type: application/areg+json. Responses MUST carry Content-Type: application/areg+json.¶
All GET endpoints MUST be accessible without authentication. POST, PATCH, and DELETE endpoints MUST require authentication. The authentication mechanism (Bearer token, API key, OAuth 2.0) is registry-defined. A registry MUST document its authentication requirement.¶
All error responses use the following format:¶
{ "error": "short_code", "detail": "human-readable text" }
¶
All registry endpoints MUST be served over HTTPS (TLS 1.2 or higher). Plain HTTP MUST NOT be used.¶
Returns a paginated list of registry entries. Yanked entries are excluded unless include_yanked=true is supplied.¶
Query parameters:¶
Response 200:¶
{
"entries": [ /* array of registry entry objects */ ],
"total": 42,
"page": 1,
"per_page": 20
}
¶
Returns a single registry entry identified by registry_id.¶
Response 200: the registry entry object.¶
Response 404: entry not found.¶
Returns the latest non-yanked registry entry for the given agent_id, where "latest" is determined by Semantic Version ordering of agent_version (descending).¶
Response 200: the registry entry object.¶
Response 404: no non-yanked entry exists for this agent_id.¶
Returns the registry entry for the specific (agent_id, agent_version) pair.¶
Response 200: the registry entry object.¶
Response 404: no entry exists for this pair.¶
Response 410 Gone: the entry exists but is yanked. The response body MUST include the yank_reason.¶
Publishes a new registry entry. The publisher MUST supply all required fields except registry_id, published_at, and updated_at, which the registry assigns.¶
The registry MUST validate the submitted body against the registry entry schema [JSON-SCHEMA] before accepting it. The registry SHOULD verify that agent_id and agent_version in the body match the AAIF document at aaif_url at publish time. If they do not match, the registry MUST reject the request with 422.¶
Response 201: { "registry_id": "...", "published_at": "..." }¶
Response 400: schema validation failure.¶
Response 409: a non-yanked entry for this (agent_id, agent_version) already exists.¶
Response 422: agent_id or agent_version mismatch with the AAIF document at aaif_url.¶
Updates mutable metadata on a non-yanked entry. The following fields MAY be updated: tags, acpm_profile_url, publisher.contact. The following fields MUST NOT be changed via PATCH: agent_id, agent_version, aaif_url, signature, publisher.name, publisher.url, published_at. The registry MUST reject a PATCH that attempts to modify an immutable field with 422.¶
Response 200: the updated registry entry object.¶
Response 403: requester does not own this entry.¶
Response 404: entry not found.¶
Response 409: entry is yanked.¶
Response 422: attempt to modify an immutable field.¶
Marks an entry as yanked. The entry is not removed. The yanked flag is set to true and the yank_reason is recorded.¶
The request body MUST include: { "yank_reason": "string" }.¶
Response 200: the updated registry entry object with yanked set to true.¶
Response 403: requester does not own this entry.¶
Response 404: entry not found.¶
Response 409: entry is already yanked.¶
The signature field attests that the AAIF document at aaif_url has not been modified since the publisher signed it. A registry entry without a signature provides no cryptographic assurance of document integrity.¶
To produce a valid signature, a publisher:¶
To verify a signature, a consumer:¶
A registry MUST NOT modify aaif_url or signature after an entry is published.¶
A consumer that requires signed entries MUST reject entries where signature is null.¶
A consumer MUST NOT cache the public key indefinitely. It SHOULD re-fetch from publisher.public_key_url at an interval appropriate to its security policy.¶
A registry entry identifies exactly one (agent_id, agent_version) pair. When an agent definition is updated, a new entry MUST be published with the new agent_version value. The new entry receives a new registry_id. The previous entry remains in the registry unchanged.¶
The GET /v1/resolve/{agent_id} endpoint returns the latest non-yanked entry, where "latest" is determined by Semantic Version ordering of agent_version descending.¶
Yanking retracts a specific (agent_id, agent_version) entry. Yanking is REQUIRED when a security vulnerability is found in the agent definition, when the document at aaif_url has been changed in a way that invalidates the entry, or when the publisher otherwise withdraws the version.¶
Yanking MUST NOT be reversed by setting yanked back to false. If a version was inadvertently yanked, the publisher SHOULD re-publish it under a new agent_version with a corrective note.¶
A registry MUST preserve yanked entries. Consumers who hold a reference to a specific registry_id MUST be able to retrieve it, including its yank_reason, for audit purposes.¶
Consumers that cache registry entries locally MUST periodically re-check the live entry to detect yanking.¶
AREG is designed to compose with SC-006 (AAIF) and SC-014 (ACPM) but has no hard dependency on either.¶
SC-006 AAIF [SC-006] defines the content of the agent definition document that aaif_url resolves to. A registry entry carries agent_id and required_capabilities from the AAIF document to enable search without fetching every definition. Using AREG without AAIF is possible; a registry entry's aaif_url may point to any agent definition format the publisher chooses.¶
SC-014 ACPM [SC-014] provides a richer capability profile that acpm_profile_url optionally points to. ACPM profiles give consumers capability, trust, cost, and SLA information beyond the minimal conformance_level and required_capabilities in the registry entry. Neither AREG nor ACPM requires the other.¶
The A2A Protocol [A2A] defines Agent Cards that an agent server exposes at a well-known URL to advertise its runtime capabilities. Agent Cards are designed for runtime service discovery, while AREG registry entries are designed for catalog discovery prior to connection. The two are complementary: an AREG entry may carry the aaif_url of an AAIF document that in turn references an A2A Agent Card endpoint.¶
The Model Context Protocol roadmap [MCP-ROADMAP] describes a planned Server Cards effort for MCP server discovery via well-known URLs. An AREG registry entry for an MCP-based agent may carry an acpm_profile_url pointing to an ACPM profile that captures the server's MCP capabilities, enabling the two discovery mechanisms to coexist.¶
Conformance levels apply to software that implements an AREG registry server. Levels are cumulative: a server claiming Full satisfies every requirement of Discover through Signed. Conformance is self-certified; there is no central certifying authority.¶
A registry entry without a signature provides no cryptographic assurance that the AAIF document at aaif_url is authentic or unmodified. Consumers operating in high-trust environments MUST require signature to be non-null and successfully verified before deploying or executing an agent based on the entry. Unsigned entries are appropriate for development and low-trust contexts.¶
AREG does not define a mechanism for verifying the identity of a publisher beyond what the registry's own authentication provides. A compromised publisher account can publish malicious entries. Registries SHOULD implement rate limiting, review workflows, and abuse reporting to reduce this risk.¶
A publisher who controls the server at aaif_url can silently substitute a different document after the entry is published. The signature field mitigates this: a consumer who verifies the signature detects any change to the canonical JSON. Registries that do not require signatures SHOULD document this risk prominently.¶
AREG does not define a key revocation mechanism beyond the publisher updating the JWK Set at publisher.public_key_url. A consumer that caches public keys indefinitely is vulnerable to continued reliance on a compromised key. Consumers MUST re-fetch keys at an appropriate interval and MUST NOT trust a signature verified against a key that has been removed from the publisher's JWK Set.¶
A consumer that caches registry entries locally MUST periodically re-check the live entry to detect yanking. Using a yanked entry for a new deployment after the yanked flag is set is a misuse of the registry. Consumers SHOULD treat a 410 Gone response from GET /v1/resolve/{agent_id}/{version} as an immediate signal to halt any pending deployment of that version.¶
This document requests registration of the following media type.¶