Agent Registry (AREG)

Introduction 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) defines how to express a portable agent definition that any conforming runtime can execute. The Agent Capability and Profile Model (ACPM) 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.

Requirements Language 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 when, and only when, they appear in all capitals, as shown here.

Scope 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 ); capability, trust, cost, and service-level description of the agent or registry server (that is defined by ACPM ); transport security configuration; billing and rate limiting above and beyond what this specification mandates.

Terminology

Registry entry: A JSON instance conforming to the AREG registry entry schema. Describes one published version of one agent.
Registry: A server that stores registry entries and exposes them via the AREG REST API defined in .
Publisher: The party that submits a registry entry to a registry.
Consumer: Software that queries a registry to discover, resolve, or verify agents.
Agent ID: The stable UUID identifying one logical agent across all of its published versions. Carried in both the AAIF document and the registry entry.
Registry ID: A UUID assigned by the registry to uniquely identify one specific (agent_id, agent_version) entry. Stable for the lifetime of that entry.
Yanked: An entry that has been retracted by its publisher. The entry remains in the registry with yanked set to true but MUST NOT be used for new deployments.
Canonical JSON: The deterministic byte representation produced by applying RFC 8785 (JSON Canonicalization Scheme) to a JSON value.
Conformance level: One of the four cumulative levels in that a registry implementation claims.

Design Principles

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.

Registry Entry Format

Object Model A registry entry is a flat JSON object. The following diagram shows its top-level structure (informative):

Field Definitions

Root Fields

sc_standard: REQUIRED. The literal string "SC-013". Identifies this document as an AREG registry entry.
sc_version: REQUIRED. The AREG schema version in Semantic Versioning format. Current value: "0.1.0".
registry_id: REQUIRED. A UUID (RFC 9562 ) assigned by the registry at publish time. MUST NOT change after assignment.
agent_id: REQUIRED. The agent_id UUID from the AAIF document at aaif_url. MUST match the agent_id field in that document.
agent_version: REQUIRED. The version of the agent definition in Semantic Versioning format. MUST match the version field in the AAIF document at aaif_url.
published_at: REQUIRED. ISO 8601 UTC date-time of first publication. Set by the registry on POST. Publishers MUST NOT supply this field.
updated_at: OPTIONAL. ISO 8601 UTC date-time of the most recent metadata update. Set by the registry on PATCH.

Publisher Object

publisher.name: REQUIRED. Human-readable publisher name.
publisher.url: REQUIRED. Publisher's canonical URI.
publisher.public_key_url: REQUIRED when signature is non-null. URI resolving to a JWK Set (RFC 7517 ) with Content-Type application/json, or a PEM file with Content-Type text/plain, containing the public key(s) used to produce the signature value.
publisher.contact: OPTIONAL. Contact email or URI for abuse and security reports.

Resolution Fields

aaif_url: REQUIRED. A resolvable URI at which the full AAIF agent definition document can be fetched. MUST return a document whose agent_id and agent_version match the entry.
signature: OPTIONAL. Compact JWS serialization (RFC 7515 ) of a detached signature over the canonical JSON (RFC 8785 ) of the AAIF document at aaif_url. Null for unsigned entries. See .

Discovery Metadata

tags: OPTIONAL. Array of free-form topic strings. Lowercase hyphenated strings are RECOMMENDED. Used as an OR-filter in list queries.
conformance_level: OPTIONAL. The highest AAIF conformance level the agent claims, copied from the AAIF document. Allowed values: Core, Tooled, Portable, Multi-agent, Observable, Enterprise, Stateful.
required_capabilities: OPTIONAL. Copy of required_capabilities from the AAIF document. Allows capability-based filtering without fetching the full definition.
acpm_profile_url: OPTIONAL. URI of an ACPM (SC-014) capability profile that further describes what this agent offers. Null if none published.

Lifecycle Fields

yanked: OPTIONAL. If true, this version has been retracted. Consumers MUST NOT use yanked entries for new deployments. Default: false.
yank_reason: OPTIONAL. Human-readable reason for yanking. REQUIRED when yanked is true.
license: OPTIONAL. SPDX license identifier for the agent definition document itself.

REST API

Conventions 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 ). 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: All registry endpoints MUST be served over HTTPS (TLS 1.2 or higher). Plain HTTP MUST NOT be used.

GET /v1/entries Returns a paginated list of registry entries. Yanked entries are excluded unless include_yanked=true is supplied. Query parameters:

tag (repeatable): Include entries carrying any of the supplied tags (OR logic).
capability (repeatable): Include only entries whose required_capabilities array contains all supplied values (AND logic).
conformance_level: Exact match against the conformance_level field.
publisher_url: Exact match against publisher.url.
include_yanked: If true, include yanked entries. Default: false.
page: 1-based page number. Default: 1.
per_page: Results per page. Default: 20. Maximum: 100.

Response 200:

GET /v1/entries/{registry_id} Returns a single registry entry identified by registry_id. Response 200: the registry entry object. Response 404: entry not found.

GET /v1/resolve/{agent_id} 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.

GET /v1/resolve/{agent_id}/{version} 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.

POST /v1/entries 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 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.

PATCH /v1/entries/{registry_id} 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.

DELETE /v1/entries/{registry_id} 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.

Signing Model 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.

Signing (Publisher) To produce a valid signature, a publisher:

Fetches the AAIF document from aaif_url.
Produces the canonical JSON representation of the document using RFC 8785 (JSON Canonicalization Scheme) .
Produces a JWS (RFC 7515 ) using detached payload mode: the canonical JSON bytes are the payload but are not included in the JWS serialization. The compact serialization form is used.
Uses the algorithm ES256 (ECDSA with P-256 and SHA-256, RFC 7518 ). RS256 (RSASSA-PKCS1 with SHA-256) SHOULD also be supported by registry implementations for interoperability.
Sets the signature field in the registry entry to the compact JWS string.
Publishes the corresponding public key at publisher.public_key_url as a JWK Set (RFC 7517 ) with Content-Type application/json, or a PEM file with Content-Type text/plain.

Verification (Consumer) To verify a signature, a consumer:

Retrieves the registry entry. If signature is null, the entry is unsigned; the consumer applies its own policy for unsigned entries.
Fetches the AAIF document from aaif_url.
Produces canonical JSON of the fetched document using RFC 8785 .
Fetches the JWK Set or PEM from publisher.public_key_url.
Verifies the compact JWS against the canonical JSON bytes using the public key.
If verification fails, treats the AAIF document as untrusted regardless of other metadata in the entry.

Normative Constraints 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.

Versioning and Yanking

Versioning 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 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.

Relationship to AAIF and ACPM AREG is designed to compose with SC-006 (AAIF) and SC-014 (ACPM) but has no hard dependency on either. SC-006 AAIF 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 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 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 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 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.

Discover: Implements GET /v1/entries, GET /v1/entries/{id}, GET /v1/resolve/{agent_id}, and GET /v1/resolve/{agent_id}/{version}. Validates entries against the registry entry schema. Returns the correct Content-Type. All endpoints accessible without authentication.
Publish: Discover, plus POST /v1/entries, PATCH /v1/entries/{id}, and DELETE /v1/entries/{id}. Enforces authentication on mutating endpoints. Assigns registry_id and published_at server-side.
Signed: Publish, plus verifies signature on POST when signature is non-null. Rejects entries whose signature does not verify against the key at publisher.public_key_url.
Full: Signed, plus supports all query parameters for GET /v1/entries (tag, capability, conformance_level, publisher_url, include_yanked, page, per_page) and returns correct pagination metadata (total, page, per_page).

Security Considerations

Unsigned Entries 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.

Publisher Impersonation 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.

URL Redirection and Document Mutation 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.

Key Revocation 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.

Yanked Entry Misuse 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.

IANA Considerations This document requests registration of the following media type.

Type name: application
Subtype name: areg+json
Required parameters: None
Optional parameters: None
Encoding considerations: Binary (UTF-8 encoded JSON)
Security considerations: See of this document.
Interoperability considerations: Instances MUST validate against the AREG registry entry schema version 0.1.0 or later.
Published specification: This document.
Applications that use this media type: AREG registry clients and servers.
Additional information: File extension: .areg.json. Magic number: none.
Intended usage: COMMON
Restrictions on usage: None
Author: Bob van Bussel, bob@observalytics.com
Change controller: Schema Commons (schemacommons.org)