Agent Directory Service

Conventions and Definitions 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.

Introduction Multi-Agent Systems (MAS) represent a new paradigm in distributed computing where software components leverage Large Language Models (LLMs) to perform specialized tasks and solve complex problems through collaborative intelligence. These systems combine LLMs with contextual knowledge and tool-calling capabilities, often abstracted through Model Context Protocol (MCP) servers, enabling dynamic workflows that adapt based on stored state and environmental conditions. The diversity and complexity of MAS architectures present unique challenges for discovery and composition. As the ecosystem of AI agents expands, developers need efficient mechanisms to:

Discover compatible agents with specific skills and capabilities
Evaluate performance characteristics including cost, latency, and resource requirements
Compose multi-agent workflows by linking agents with complementary capabilities
Verify claims about agent performance and reliability
Track versioning and dependencies between agent components

The Agent Directory Service (ADS) addresses these challenges by providing a distributed directory infrastructure specifically designed for the agentic AI ecosystem. Rather than attempting to formally define MAS architectures, which would constrain the creative composition patterns emerging in this rapidly evolving field—ADS focuses on providing flexible metadata storage and discovery mechanisms. A comparison among registries which can be centralized or distributed is reported here .

Core Capabilities ADS enables several key capabilities for the agentic AI ecosystem: Capability-Based Discovery: Agents publish structured metadata describing their functional abilities, costs, and performance characteristics. The system organizes this information using hierarchical skill taxonomies, enabling efficient matching of capabilities to requirements. Verifiable Claims: While agent capabilities are often subjectively evaluated, ADS provides cryptographic mechanisms for data integrity and provenance tracking. This allows users to make informed decisions about agent selection while enabling reputation systems to emerge organically. Semantic Linkage: Components can be securely linked to create various relationships like version histories for evolutionary development, collaborative partnerships where complementary skills solve complex problems, and dependency chains for composite agent workflows. Distributed Architecture: Built on proven distributed systems principles, ADS uses content-addressing for global uniqueness and implements distributed hash tables for scalable content discovery across decentralized networks.

Architectural Foundation The system leverages the Open Agentic Schema Framework (OASF) to model agent information in a structured, extensible format. OASF enables rich queries such as "What agents can solve problem A?" or "What combination of skills and costs optimizes for task B?" This schema-driven approach supports both objective metrics (token consumption, GPU requirements) and subjective evaluations (user ratings, task completion quality). Agent records are organized using modular extensions—reusable components like MCP server definitions, prompt-based agents, and evaluation metrics. This modular approach facilitates composition and reuse across different MAS architectures while maintaining flexibility for innovative use cases. The underlying storage layer integrates with OCI (Open Container Initiative) standards, enabling interoperability with existing container ecosystems and leveraging mature tooling for content distribution and verification. This document details the technical architecture of ADS, covering the record storage layer, security model, distributed data discovery mechanisms, and data distribution protocols between storage nodes.

Storage Architecture ADS implements a decentralized storage architecture built on OCI (Open Container Initiative) registries as the foundational object storage layer. This design choice enables the system to leverage mature, standardized container registry infrastructure while achieving the speed, scalability, and security requirements of a distributed agent directory.

Content-Addressed Storage The storage architecture centers on globally unique Content Identifiers (CID) that provide several critical properties for a distributed agent directory: Immutability: Content identifiers are cryptographically derived from the data they represent, ensuring that any modification results in a different identifier. This property is essential for maintaining data integrity in agent records and enabling verifiable claims about agent capabilities. Deduplication: Identical content automatically receives the same identifier across all nodes in the network, eliminating storage redundancy and reducing bandwidth requirements when the same agent components are referenced by multiple systems. Verifiability: Any node can independently verify that received content matches its identifier, providing built-in protection against data corruption or tampering during transmission. Location Independence: Content can be retrieved from any node that possesses it, as the identifier serves as a universal pointer that abstracts away physical storage locations.

OCI Integration ADS leverages OCI (Open Container Initiative) specifications for storing and distributing agent records as OCI artifacts, offering several advantages:

Standards Compliance By building on OCI specifications, ADS inherits compatibility with the extensive ecosystem of container registry tools, security scanners, and management platforms. This includes:

Authentication and authorization mechanisms already deployed in enterprise environments
Content signing and verification through tools like Notary and cosign
Vulnerability scanning capabilities that can be extended to agent security assessments
Content delivery networks optimized for OCI artifact distribution

Record Artifact Specification ADS stores agent records as Record Artifacts following the OCI Image Manifest Specification and adhering to the OCI artifacts guidance . A Record Artifact is an AGNTCY OASF Record packaged as an OCI artifact.

Manifest Structure The manifest structure MUST include the following properties:

mediaType string This REQUIRED property MUST be application/vnd.oci.image.manifest.v1+json.
artifactType string This REQUIRED property MUST be application/vnd.agntcy.dir.record.v1+json. Future versions of the Record Artifact Specification MAY define additional artifact types.
config descriptor This REQUIRED property MUST reference an empty configuration with media type application/vnd.oci.empty.v1+json, indicating that no additional configuration data is needed for Record Artifacts.
layers array of objects This REQUIRED property MUST contain one or more layer descriptors representing OASF Record components.
subject descriptor This OPTIONAL property MAY reference another Record Artifact to create linkage between records for version histories.

Layer Structure Each layer descriptor MUST include the following properties:

mediaType string This REQUIRED property specifies the layer content type. Implementations MUST support the following media types:
- application/vnd.agntcy.oasf.types.{version}.Record+json: The first layer (index 0) MUST use this media type and contains base record data. This layer MUST use the data field for inline storage (base64-encoded) since the content is small, frequently accessed, and unique to each record. Object annotations, schema_version and created_at are stored as part of layer annotations.
- application/vnd.agntcy.oasf.types.{version}.Skill+json: Contains skill definition data. Object annotations, id and name are stored as part of layer annotations.
- application/vnd.agntcy.oasf.types.{version}.Domain+json: Contains domain definition data. Object annotations, id and name are stored as part of layer annotations.
- application/vnd.agntcy.oasf.types.{version}.Locator+json: Contains locator definition data referencing the location where the agent can be accessed or deployed. Object annotations, type and url are stored as part of layer annotations and URL fields.
- application/vnd.agntcy.oasf.types.{version}.Module+json: Contains module definition data. Object annotations, id and name are stored as part of layer annotations.
Media types MUST map to application/vnd.{schema_uri}.{version}.{type}+{encoding} format, where - {schema_uri} corresponds to the OASF protobuf schema namespace - {version} corresponds to a specific OASF type version (e.g., v1alpha2) - {type} is the OASF type name (e.g. Record) - {encoding} MUST be json
urls array of strings This OPTIONAL property MAY contain URLs pointing to external resources, particularly useful for Locator layers to specify deployment targets.
annotations string-string map This OPTIONAL property contains arbitrary attributes. Implementations SHOULD use the predefined annotation keys:
- agntcy.oasf.record/schema_version: Schema version (for Record layers)
- agntcy.oasf.record/created_at: Creation timestamp (for Record layers)
- agntcy.oasf.locator/type: Locator type (for Locator layers)
- agntcy.oasf.skill/{id,name}: Skill id/name (for Skill layers)
- agntcy.oasf.domain/{id,name}: Domain id/name (for Domain layers)
- agntcy.oasf.module/{id,name}: Module id/name (for Module layers)

Example Record Artifacts ", "digest": "sha256:d5815835051dd97d800a03f641ed8162877920e734d3d705b698912602b8c763", "size": 216, "annotations": { "agntcy.oasf.record/schema_version": "0.7.0", "agntcy.oasf.record/created_at": "2026-01-06T00:00:00Z" } }, { "mediaType": "application/vnd.agntcy.oasf.types.v1alpha2.Skill+json", "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a", "size": 2, "annotations": { "agntcy.oasf.skill/id": "10201", "agntcy.oasf.skill/name": "Natural Language Processing/Sentiment Analysis" } }, { "mediaType": "application/vnd.agntcy.oasf.types.v1alpha2.Locator+json", "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a", "size": 2, "urls": [ "https://ghcr.io/agntcy/agent:latest", "ipfs://bafybeibwzif37xyzabcdefg" ], "annotations": { "agntcy.oasf.locator/type": "docker-image" } } ], "subject": { "mediaType": "application/vnd.oci.image.manifest.v1+json", "artifactType": "application/vnd.agntcy.dir.record.v1+json", "digest": "sha256:7e346bc58473bc1d8a98776fa2a89a3e2a446b27f0e8a33ad49c3d4f28b6471d", "size": 702 } } ]]>

Record Reconstruction Applications consuming Record Artifacts MUST implement the following reconstruction algorithm:

Pull Manifest: Retrieve the OCI image manifest from the registry using standard OCI Distribution API operations
Extract Base Record: Parse the first layer (index 0) with media type application/vnd.agntcy.oasf.types.{version}.Record+json and base64-decode the data field to obtain the base record JSON data
Retrieve Component Layers: For each subsequent layer (Skill, Domain, Locator, Module):
- Fetch the blob content from the registry using the layer's digest
- Verify the blob's SHA-256 digest matches the descriptor's digest field
- Parse the JSON content according to the layer's mediaType
- Merge the component data into the appropriate field of the base record
- Merge descriptor annotations into the corresponding component metadata
Validate Schema: Validate the reconstructed record against the OASF schema version specified in the agntcy.oasf.record/schema_version annotation

Application Integration

Open Agent Schema Framework (OASF) The Open Agent Schema Framework (OASF) complements Record Artifact Specification by defining the actual data models for agent-related information referenced in the OCI artifacts.

Third-Party Applications Third-party applications can build on top of the Record Artifact Specification to create tools and services for managing, distributing, and utilizing agent records. This can be accomplished by leveraging existing OCI ecosystem components such as registries, clients, and tooling, or by developing custom solutions that link to Record Artifacts.

Runtime Environments Runtime environments that deploy and manage agents can leverage Record Artifacts to obtain the necessary information for launching and managing agent instances based on the definitions contained within the artifacts. Implementations can provide management of process lifecycles, monitoring, and other capabilities based on the metadata defined in the records, or by linking records with runtime-specific artifacts.

Artifact Organization Agent records are stored as OCI artifacts with a structured organization. Records MUST be addressed by digest for immutable retrieval. Tags are mutable aliases and can be used as human-readable pointers, but implementations MUST NOT assume a tag resolves to more than one manifest at a time. The examples below show digest-pinned references: This naming scheme demonstrates that the same content identifier can belong to multiple skills, reflecting the reality that many AI agents are multi-capable. For example, the BERT-based agent (sha256:abc123...) appears under multiple skill categories: natural_language_processing/sentiment-analysis, natural_language_processing/text-classification, and natural_language_processing/emotion-detection, representing different capabilities of the same underlying agent implementation. Similarly, the YOLO vision model (sha256:jkl012...) provides both object-detection and scene-understanding capabilities under images_computer_vision. This cross-referencing approach allows agents to be discovered through any of their supported capabilities while maintaining unique addressability through content identifiers. Each skill category can have its own versioning and metadata, enabling fine-grained capability management even when multiple skills share the same underlying implementation. Each artifact contains structured metadata following OASF schemas, enabling rich queries and capability matching across all variants within a given category.

Multi-Registry Federation The architecture supports federation across multiple registry instances, enabling:

Organizational boundaries: Different organizations can maintain their own registries while participating in the global directory
Geographic distribution: Content can be replicated to registries closer to consumers, reducing latency
Specialization: Registries can focus on specific domains (e.g., medical AI agents, financial analysis tools)
Redundancy: Critical agent records can be replicated across multiple registries for availability

MAS Data Discovery ADS implements a two-level mapping system that enables efficient discovery of Multi-Agent System components through a distributed hash table architecture. This approach separates capability-based discovery from content location, providing both scalability and flexibility in agent retrieval.

Skill Taxonomy Effective agent discovery in multi-agent systems requires sophisticated organization of capabilities and skills. ADS employs a hierarchical skill taxonomy that serves as the foundation for efficient search and discovery operations across the distributed network.

The Challenge of Capability Search Traditional keyword-based search approaches face significant limitations when applied to agent discovery: Vocabulary Fragmentation: Different publishers may describe similar capabilities using varying terminology. For example, "sentiment analysis," "opinion mining," and "emotional classification" may all refer to similar agent capabilities, leading to search results that miss relevant agents due to terminology mismatches. Scale Complexity: As the number of agents in the ecosystem grows, exhaustive search across all records becomes computationally prohibitive. Without structured organization, every query potentially requires examining every agent record, leading to poor performance characteristics. Semantic Relationships: Many agent capabilities have natural hierarchical relationships that flat keyword systems cannot capture. An agent capable of "named entity recognition" is inherently relevant to searches for broader "text analysis" capabilities, but keyword matching alone cannot establish these connections.

Taxonomy-Driven Search Optimization ADS addresses these challenges through a structured hierarchical taxonomy that provides several critical optimization benefits: Search Space Partitioning: The taxonomy enables efficient partitioning of the search space. When processing a query for "computer vision" capabilities, the system can immediately focus on the relevant taxonomy branch, eliminating the need to examine agents in unrelated categories like natural language processing or mathematical reasoning. Index Structure Optimization: The hierarchical organization allows the distributed hash table to create specialized indices for different taxonomy branches. Rather than maintaining a single massive index, the DHT can distribute indexing responsibility across nodes, with each node specializing in specific capability domains. Query Semantic Expansion: The taxonomy enables intelligent query expansion where searches automatically include semantically related subcategories. A search for "text analysis" can transparently include results from "sentiment analysis," "entity extraction," and "text classification" without requiring users to explicitly enumerate all relevant subcategories. Standardized Vocabulary: By providing a canonical taxonomy, ADS reduces terminology fragmentation. Publishers are encouraged to tag their agents using standardized skill categories, improving search precision and recall across the ecosystem.

Two-Level Mapping Architecture The discovery system operates through two distinct mapping layers:

Skill Taxonomy for Search Optimization ADS employs a hierarchical skill taxonomy to optimize search performance and enable efficient capability-based discovery. Taxonomies provide several critical advantages for agent discovery systems: Search Space Reduction: Rather than performing exhaustive searches across all agent records, taxonomies allow the system to quickly narrow the search space to relevant categories. When a user queries for "natural language processing" capabilities, the system can immediately identify the subset of agents tagged with NLP skills without examining agents focused on computer vision or mathematical reasoning. Hierarchical Organization: Skills are organized in a tree-like structure *that reflects natural relationships between capabilities. For example: This hierarchy enables both specific queries ("sentiment analysis agents") and broader capability searches ("all natural language processing agents") while maintaining efficient indexing structures. Query Expansion and Refinement: Taxonomies support automatic query expansion *where searches for parent categories can include relevant child categories. A *query for "text analysis" can automatically include agents tagged with *"sentiment analysis," "named entity recognition," and "text classification" *without requiring users to know all specific subcategories. Semantic Consistency: Standardized taxonomies reduce ambiguity and improve *search precision by providing consistent terminology across the ecosystem. This *prevents fragmentation where similar capabilities are described using different *terms by different publishers. Scalable Indexing: The hierarchical structure enables efficient distributed *indexing where different DHT nodes can specialize in specific taxonomy *branches, distributing both storage load and query processing across the *network.

Additional Taxonomies While skills form the primary taxonomy for capability-based discovery, ADS supports multiple parallel taxonomies to enable rich, multi-dimensional agent classification and search.

Domain Taxonomy The domain taxonomy organizes agents by their application domains, representing the broader problem spaces or industries where agents are designed to operate: Domain classification enables users to discover agents that are specifically tuned for their operational context, even if those agents share similar underlying skills with agents from other domains.

Module Taxonomy The module taxonomy categorizes agents by the OASF modules they implement, facilitating the discovery of agents compatible with specific system architectures. Modules are organized into the OASF module categories (Core and Integration), and each module captures a structured integration surface or capability extension: The Agent Spec module aligns with the Open Agent Spec specification . Module identifiers use the OASF module name values. The acp module is deprecated in OASF; use a2a when possible.

Multi-Dimensional Search The parallel taxonomy system enables sophisticated multi-dimensional queries that combine criteria across different classification axes. All searches must include at least one skill criterion as the mandatory foundation, with domain and module taxonomies providing additional filtering dimensions:

Skill + Domain: "Find natural language processing agents specialized for healthcare applications"
Skill + Module: "Discover computer vision agents that support MCP integration"
Skill + Module + Domain: "Locate natural language processing agents with observability modules for manufacturing applications"

Skills as Search Foundation: The skills taxonomy serves as the primary index structure in the DHT, making skill-based criteria mandatory for efficient query resolution. This design ensures that:

Query Performance: All searches leverage the optimized skills-to-CID mapping as the starting point, providing consistent performance characteristics
Result Relevance: Domain and module filters are applied to skill-based result sets, ensuring functional capability remains the core selection criterion
Index Efficiency: The DHT can optimize storage and lookup patterns around the skills taxonomy while supporting supplementary filtering through domains and modules

Domain-only or module-only queries are not supported, as they would bypass the primary indexing structure and provide results that may not have the functional capabilities required by the requesting system. This skill-mandatory rule applies to the DHT capability index, which uses skills as its primary key for global, cross-host routing. It does not constrain the host-local AI Finder catalog browse surface (see ), which filters and orders entries over arbitrary fields and tags without requiring a skill criterion. The two surfaces are complementary: the DHT optimizes global capability routing, while AI Finder provides deterministic browsing of a host's catalog. This multi-taxonomic approach provides the flexibility to support diverse use cases while maintaining efficient indexing and search performance across all dimensions.

Skills-to-CID Mapping The first level maps agent capabilities and skills to their corresponding Content Identifiers (CID): This mapping enables queries such as "find all agents capable of natural language processing" to quickly resolve to a set of content identifiers without needing to search through individual agent records.

CID-to-PeerID Mapping The second level maps Content Identifiers to the Peer IDs of nodes that store the corresponding agent records: This separation allows the system to: - Optimize for capability queries without requiring knowledge of data locations

Enable dynamic content replication as peer availability changes
Support multiple storage strategies for the same content across different peers

DHT-Based Discovery Process The Distributed Hash Table stores and maintains both mapping layers across the network: ADS uses [Kad-DHT] for server and content discovery by using the libp2p implementation that constitutes the IPFS core DHT .

Skill Registration When agents are published to the network:

Capability Extraction: The system parses OASF records to extract skills, domains, and modules
DHT Updates: Skills-to-CID mappings are distributed across DHT nodes using consistent hashing
Location Registration: Peer nodes register themselves as providers for specific CIDs

Discovery Query Resolution Agent discovery follows a three-phase process:

Capability Resolution: Query "agents with skill X" resolves to a list of relevant CIDs via DHT lookup
Location Resolution: For each discovered CID, query DHT to find peer nodes storing the content
Result Aggregation: Combine capability matches with location information to produce actionable discovery results

Additional Tanomoxies

Content Distribution via OCI Protocol Once discovery identifies the relevant CIDs and their hosting peers, the actual agent records are retrieved using the OCI distribution protocol:

Peer-to-Peer Synchronization The discovered list of CIDs enables efficient content synchronization between peers:

Content Negotiation: Requesting peer queries hosting peers for available agent records
OCI Pull Operations: Standard OCI registry pull commands retrieve agent artifacts and metadata
Incremental Sync: Only missing or updated content is transferred, reducing bandwidth requirements
Verification: Content integrity is verified through cryptographic hash validation during transfer

Distribution Strategies The system supports multiple distribution patterns, each with distinct trade-offs and operational considerations: On-Demand Retrieval: Records are pulled from remote peers only when specifically requested, minimizing local storage requirements. Trade-offs: While this approach minimizes storage costs and ensures fresh content, it introduces several challenges:

Query Latency: Each request requires network round-trips to locate and retrieve content, increasing response times
Network Cost: Spurious or exploratory requests generate unnecessary network traffic and computational overhead
DoS Vulnerability: The system becomes susceptible to denial-of-service attacks where malicious actors can trigger expensive content retrieval operations by flooding the network with requests for non-existent or rarely-accessed agents
Scalability Limits: Performance degrades as the network grows due to increased query coordination overhead

Proactive Caching: Popular or frequently accessed agents are automatically replicated to improve query response times. Trade-offs: This strategy offers significant scalability benefits but requires sophisticated management:

Performance Gains: Dramatic reduction in query latency for popular content, enabling sub-second response times
Scalability: Can handle high query volumes efficiently once popular content is cached locally
Popularity Measurement: Requires implementing metrics collection and analysis to identify which agents warrant caching. This includes tracking query frequencies, download patterns, and usage statistics across the network
Storage Requirements: Needs sufficient local storage capacity to maintain cached copies of popular records
Cache Management: Must implement cache eviction policies, freshness validation, and synchronization mechanisms
Administrator Oversight: Proactive caching policies must be configured and monitored by agent directory node administrators to balance storage costs with performance benefits

Strategic Replication: Critical agents can be replicated across multiple peers to ensure high availability and reduce single points of failure. Trade-offs: This approach addresses availability concerns but introduces subjective complexity:

High Availability: Ensures critical agents remain accessible even during peer failures or network partitions
Reduced Single Points of Failure: Distributes risk across multiple storage locations
Subjective Criticality: The definition of "critical" or "useful" agents varies significantly between users, organizations, and use cases. What constitutes strategic value for financial services may be irrelevant for manufacturing applications
Administrative Burden: Requires agent directory node administrators to make strategic decisions about which agents warrant replication, considering factors like:
- Organizational priorities and business requirements
- Compliance and regulatory considerations
- Cost-benefit analysis of storage versus availability
- Community consensus on agent importance
Resource Allocation: Strategic replication consumes storage resources that could otherwise be used for proactive caching of popular content

Administrative Management: Both Proactive Caching and Strategic Replication require active management by agent directory node administrators. Administrators must:

Configure caching policies based on local network characteristics and storage capacity
Monitor popularity metrics and adjust caching strategies accordingly
Define strategic replication criteria aligned with organizational objectives
Balance resource allocation between different distribution strategies
Implement governance policies for content lifecycle management

This architecture provides a scalable foundation for MAS data discovery that can efficiently handle large networks of distributed agents while maintaining low latency for capability-based queries.

Agent Directory Record Examples The following examples illustrate the structure of OASF-compliant agent records stored in the directory: These examples demonstrate how the DHT indexing system extracts skills and domains from agent records to populate the Skills-to-CID mappings, enabling efficient capability-based discovery across the distributed network.

Security Model The OCI-based architecture provides multiple layers of security that address the unique challenges of distributed agent directories:

Cryptographic Integrity ADS leverages the OCI layer's built-in cryptographic mechanisms to ensure data integrity: Automatic Hash Computation: The OCI registry layer automatically computes SHA-256 hash digests for all stored artifacts. These content identifiers are generated transparently during the push operation, ensuring that every agent record has a cryptographically verifiable fingerprint without additional overhead. Tamper Detection: Content addressing ensures immediate tamper detection through cryptographic hash verification. Any modification to an agent record—whether malicious or accidental—results in a different hash digest, making unauthorized changes immediately detectable during retrieval operations. End-to-End Verification: Clients can independently verify that received content matches its advertised identifier, providing built-in protection against data corruption during transmission or storage without trusting intermediate network components.

Content Provenance and Digital Signatures ADS integrates with Sigstore, a security framework for OCI storage, to provide comprehensive content provenance and authenticity guarantees: Sigstore Integration: The system leverages Sigstore's security framework to provide verifiable proof of when and by whom agent records were signed. This creates an immutable audit trail that cannot be retroactively modified, enabling forensic analysis of agent deployment history. Keyless Signing: Sigstore's keyless signing approach eliminates the complexity and security risks associated with long-lived cryptographic keys:

Identity-Based Authentication: Uses OpenID Connect (OIDC) tokens from trusted identity providers (GitHub, Google, Microsoft) to authenticate publishers at signing time
Short-Lived Certificates: Issues ephemeral signing certificates valid only for minutes, reducing the window of potential key compromise
Automatic Key Rotation: Eliminates the need for manual key management, distribution, and rotation procedures
Scalable Trust: Publishers don't need to maintain or distribute public keys, making the system accessible to individual developers and large organizations alike

Transparency and Verification: All signatures are stored directly in OCI storage alongside the agent artifacts and public keys, providing:

Public Auditability: Anyone can verify the signing history of agent records stored in accessible registries
Non-Repudiation: Publishers cannot deny having signed records that are cryptographically linked to their identity
Supply Chain Security: Enables detection of compromised or unauthorized agent publications

Trust Boundaries and Isolation Organizational Isolation: Separate registries maintain security boundaries between different organizations, allowing each entity to control their own agent ecosystem while still participating in the broader federated network. Content Verification: Nodes can validate artifact integrity and signature authenticity without trusting transport layers or intermediate storage systems. This zero-trust approach ensures security even when using untrusted storage infrastructure. Reputation Systems: The cryptographic foundation enables the development of reputation systems based on verifiable evidence rather than subjective claims. Publishers with consistent signing practices and high-quality agents can build measurable trust over time.

Threat Mitigation The security model addresses several key threats to distributed agent directories: Supply Chain Attacks: Sigstore integration and transparency logs make it difficult for attackers to inject malicious agents without detection, as all publications are cryptographically signed and publicly auditable. Data Integrity Attacks: Automatic hash verification prevents tampering with agent records during storage or transmission, ensuring users receive authentic content. Identity Spoofing: OIDC-based keyless signing prevents attackers from impersonating legitimate publishers without compromising their identity provider credentials. Availability Attacks: The distributed nature of the system, combined with content replication across multiple registries, provides resilience against denial-of-service attacks targeting individual nodes.

Access Control

Registry-level permissions control who can publish and retrieve agent records
Fine-grained policies can restrict access to specific agent categories or capability types
Audit trails leverage existing registry logging capabilities to track access patterns

Trust Boundaries

Organizational isolation through separate registries maintains security boundaries
Content verification allows nodes to validate artifact integrity without trusting transport layers
Reputation systems can build on cryptographic proofs of past agent performance

Performance Optimizations The architecture incorporates several optimizations for the specific requirements of agent discovery:

Bandwidth Optimization

Incremental updates use OCI layer semantics to transmit only changed portions of agent records
Content compression reduces storage and transmission costs for large agent definitions
Selective replication based on query patterns minimizes unnecessary data transfer

Scalability Architecture The system scales horizontally through several mechanisms:

Registry sharding distributes storage load across multiple OCI registry instances
Index partitioning in the DHT allows query load to scale with the number of participating nodes
Lazy loading defers retrieval of detailed agent specifications until actually needed

This architecture provides a robust foundation for a decentralized agent directory that can scale to support the growing ecosystem of AI agents while maintaining the security and reliability requirements of production systems.

AI Catalog Interoperability ADS natively interoperates with the AI Catalog model , a typed, nestable JSON container for discovering heterogeneous AI artifacts (such as MCP servers, A2A agents, agent skills, and nested catalogs). ADS projects its content-addressed OASF records into AI Catalog documents and serves them through discovery APIs. This section specifies that projection and the surfaces through which AI Catalog consumers access ADS content. The AI Catalog specification version referenced here is 1.0; each catalog document's specVersion member MUST identify the version to which that document conforms.

Overview The two models operate at complementary layers:

OASF Records provide a deep, strongly typed agent model stored on a content-addressed substrate (OCI artifacts, see ) and routed through the distributed hash table (see ).
AI Catalog provides a thin, artifact-agnostic interoperability and discovery surface. A catalog identifies each artifact by media type and either references it (url) or embeds it (data), without requiring consumers to parse the artifact's internal schema.

ADS treats AI Catalog as a consumption surface projected from records: the OCI and DHT layers remain the storage and routing substrate, while AI Catalog documents are derived views suitable for generic, schema-agnostic clients. The AI Catalog media type is application/ai-catalog+json.

Catalog Data Model ADS-generated catalog documents MUST conform to the AI Catalog data model . An AICatalog MUST contain specVersion and entries. It MAY also contain host, extensions, signature, and additionalSignatures as defined by that specification. Producers SHOULD omit the reserved additionalSignatures member; consumers MUST accept and ignore it. ADS-specific information that is not defined by AI Catalog MUST NOT be represented using an undefined top-level member such as metadata. Each CatalogEntry MUST contain identifier, type, and exactly one of url or data. It MAY also contain displayName, description, tags, version, updatedAt, extensions, publisher, digest, and trustManifests. The type member identifies the artifact's media type, such as application/mcp-server-card+json, application/a2a-agent-card+json, or application/ai-catalog+json for a nested catalog. Member names and semantics are those defined by AI Catalog; in particular, producers MUST use type, displayName, and updatedAt, not media_type, display_name, or updated_at. The optional host member identifies the catalog operator. The optional publisher member on an entry identifies the artifact publisher. Trust contributions are represented by the entry's trustManifests array. Each TrustManifest identifies a contributor and MAY include subject, signature, trustSchema, attestations, provenance, and extensions, subject to the AI Catalog validity and verification requirements. ADS implementations MUST preserve the distinction between the catalog host, the artifact publisher, and each trust manifest contributor.

Catalog Projection and Identifiers ADS derives catalog entries from OASF records through a deterministic projection. The projection is keyed on the OASF integration modules a record carries; modules that have no AI Catalog representation are ignored. Projected entries MUST use the AI Catalog member names and MUST provide exactly one of url or data. An inline data value MUST contain the complete artifact document identified by type. A record is projectable only if it carries at least one known module. The following modules are recognized and map to the indicated entry media types:

OASF module	Catalog entry type
`integration/mcp`	`application/mcp-server-card+json`
`integration/a2a`	`application/a2a-agent-card+json`
`core/language_model/agentskills`	`application/agent-skills+md`

The projection produces one of three outcomes:

No known module: the record is not projectable and MUST NOT produce a catalog entry.
Exactly one known module: the record projects to a leaf entry whose type is the module's media type and whose data or url identifies the corresponding native artifact.
Two or more known modules: the record projects to a container entry with type application/ai-catalog+json whose data embeds a nested AICatalog containing one entry per known module. The nested catalog MUST use specVersion and entries as defined by AI Catalog.

Entry fields are derived from the record: displayName from the record name, and version, description, updatedAt, and tags from the corresponding record fields when present. Since AI Catalog recommends omitting displayName when the referenced artifact already carries its canonical name, the projection SHOULD omit it in that case unless an intentional display override is required. Entries within a container MUST be emitted in a deterministic order so that identical records yield byte-identical catalogs.

Projected Identifiers The entry identifier identifies the logical artifact and MUST remain stable across versions and retrieval-URL changes. When an OASF record contains a publisher-authorized urn:air identifier, ADS MUST preserve it exactly. Otherwise, ADS MAY preserve a stable source identifier or assign an identifier under its control. An ADS-assigned identifier MUST NOT be reassigned to another artifact. A content identifier that changes when the record changes MUST NOT be used as the logical artifact identifier. ADS MAY expose the record's content identifier in an ADS-namespaced extensions member. ADS SHOULD set digest to the digest of the exact artifact representation when it can be expressed using the AI Catalog digest format. A record content identifier alone does not establish publisher identity or trust. The urn:air identifier syntax is defined by AI Catalog; URNs are specified in .

Trust Projection ADS projects its existing record-signing model (see ) into the AI Catalog trustManifests array. A projected manifest MUST use the AI Catalog member names and satisfy its manifest validity requirements. A signed manifest MUST include a subject binding the manifest to the entry's identifier, type, digest, and, when present, version. The entry MUST include the matching digest; the digest is computed over the retrieved artifact bytes for url, or over the JCS-canonicalized JSON value for data. Consistent with , each trust manifest is a peer element of the entry; it does not wrap or modify the artifact. ADS carries signatures, public keys, and trust metadata through its OCI referrer model (see ). AI Catalog signatures use detached JWS over a JSON Canonicalization Scheme payload as specified by AI Catalog. An OCI or Sigstore signature MUST NOT be represented as a verified AI Catalog endorsement unless its signature, signer profile, and subject binding satisfy the AI Catalog verification requirements. Where ADS cannot produce a conforming manifest, it MAY retain the signature as an OCI referrer without projecting it into trustManifests.

AI Finder Service ADS exposes AI Catalog content through the AI Finder service, offered over gRPC and, via a gateway, as a REST API. The REST surface comprises:

GET /v1/agents: list catalog entries with deterministic, cacheable browsing semantics. Results are filtered and ordered server-side (database filtering and ordering, without relevance ranking) and paginated.
GET /v1/agents/{cid}: retrieve a single CatalogEntry by record CID, providing a stable detail URL for any entry discovered through listing.
GET /v1/agents/{cid}/export: render the full agent record in a requested export format. Supported formats include oasf, a2a, agent-skill, and mcp-ghcopilot; the response carries the rendered bytes with an appropriate content type.
GET /.well-known/ai-catalog.json: return an AI Catalog document at the well-known URI . The response MUST be a conforming AICatalog containing specVersion and entries; it MAY include host and other standard AI Catalog members. AI Catalog does not define a WellKnownCatalog type or a collections member.

An ADS host MAY also advertise its catalog using the ai-catalog link relation defined by , in an HTTP Link header or an HTML link element. Clients SHOULD check for this relation during website discovery and MAY fall back to the well-known URI when no relation is advertised. The export operation is the heterogeneity bridge: a single content-addressed OASF record can be materialized into the native format of several ecosystems (A2A agent cards, agent skills, MCP server descriptors) without changing its canonical storage representation.

Discovery Integration The AI Finder surface is host-local: the well-known document and the REST API describe the records held or indexed by a single host, and the AI Catalog nesting mechanism composes such documents into hierarchies. ADS complements this with global discovery: the distributed hash table (see ) routes capability queries across hosts, which base AI Catalog—relying only on the well-known URI and nested references—does not provide. The AI Catalog specification does not define queryable collections or dynamic discovery semantics. ADS MAY expose dynamic queries through its own REST or gRPC interfaces; these interfaces are separate from the AI Catalog data model. A catalog entry MAY reference a nested AI Catalog, but that document MUST itself conform to the standard catalog schema. In this arrangement ADS acts as the content-routing backbone beneath AI Catalog's decentralized, nestable composition.

Conformance and Trust Layers ADS supports the conformance levels defined by :

Level 1, Minimal Catalog: entries carrying identifier, type, and exactly one of url or data.
Level 2, Discoverable Catalog: a catalog with a host object; it MAY be served at the well-known URI.
Level 3, Trusted Catalog: trust manifests and signatures are verified, including signer authentication, subject-to-entry release binding, and artifact digest verification, before their claims are relied upon.

Because ADS addresses records by cryptographic content identifiers, consumers can detect substitution of a retrieved record by verifying its identifier. This does not, by itself, protect the catalog snapshot or authenticate the publisher. Consumers requiring snapshot integrity SHOULD verify the catalog signature according to AI Catalog or use an authenticated content-addressed mechanism. ADS deployments claiming Level 3 conformance SHOULD provide one of these mechanisms. Consumers verifying signed trust manifests MUST also verify the entry digest and the manifest's release binding.

IANA Considerations This document has no IANA actions.