As AI systems evolve from isolated models into interconnected networks of specialized agents, several challenges emerge: How do agents find each other? How does an AI application discover which agents can perform specific actions driven by the current context or task requirements? How do developers publish their agents so others can find and use them?

Traditional service discovery systems weren’t designed for the agentic AI ecosystem. They lack semantic understanding of agent capabilities, don’t support capability-based discovery, and can’t handle the rich metadata that describes what agents can do. Developer platforms often resort to centralized marketplaces or proprietary directories, fragmenting the ecosystem and limiting agent reusability.

The Problem: Agent Discovery at Scale

Modern AI applications increasingly rely on specialized agents working together:

  • Multi-agent Workflows where different agents handle specific tasks (data processing, analysis, synthesis)
  • Agent Marketplaces where developers publish agents for others to discover and use
  • Dynamic Agent Coordination where systems discover and invoke agents based on current requirements
  • Federated AI Services spanning organizations, platforms, and deployment environments

These scenarios require sophisticated discovery capabilities:

  • Capability-based Search to find agents by what they can do, not just by name or identifier
  • Semantic Discovery to match agent capabilities to requirements using hierarchical taxonomies
  • Verifiable Metadata to trust that agent descriptions are authentic and haven’t been tampered with
  • Distributed Architecture to enable discovery across organizational boundaries without centralized control
  • Protocol Integrations to support various agent protocols (A2A, MCP) while maintaining semantic consistency
  • Developer Experience to make it simple to publish and discover agents programmatically

Existing solutions fall short. DNS-based service discovery provides naming but lacks semantic understanding. Cloud-native service meshes focus on network routing, not capability matching. Container registries store artifacts but don’t organize by functional attributes. Centralized marketplaces work within single platforms but don’t enable cross-platform discovery.

DIR (Directory) was built to solve exactly these challenges, providing a distributed, capability-aware directory service purpose-built for the agentic AI ecosystem. Agents announce their capabilities through structured metadata, while consumers discover them through rich capability-based queries. Whether you’re building a multi-agent AI system, an agent marketplace, or a platform that coordinates specialized AI services, DIR provides the discovery infrastructure you need.

What is DIR?

DIR (Directory) is a distributed directory service that enables agents to announce their capabilities and allows others to discover them through capability-based queries. Built on proven distributed systems principles, DIR uses content-addressing for global uniqueness, hierarchical taxonomies for semantic organization, and distributed hash tables (DHT) for scalable discovery across decentralized networks.

At its core, DIR combines:

  • Capability-based Discovery - Agents publish structured metadata describing their functional characteristics
  • Hierarchical Taxonomies - Capabilities are organized through semantic taxonomies for efficient matching
  • Content-addressed Naming - Cryptographic hashes (CIDs) ensure global uniqueness and data integrity
  • Distributed Architecture - DHT-based routing enables scalable discovery without centralized control
  • Verifiable Claims - Cryptographic signing provides data integrity and provenance tracking
  • OCI Integration - Standard OCI distribution protocol for interoperable storage and retrieval
  • Multi-Protocol Support - Native integration with A2A, MCP, and custom agent protocols

This approach enables developers to publish agents once and make them discoverable across the entire ecosystem, while consumers can find the right agents for their needs through requirement- and capability-based queries rather than simple name lookups.

Capability-Based Discovery

DIR leverages the Open Agentic Schema Framework (OASF) to provide standardized, capability-based agent discovery. OASF defines a structured schema for describing AI agents through:

  • Skills Taxonomy - Hierarchical organization of agent capabilities, from high-level categories like “natural language processing” down to specific skills like “sentiment analysis” or “named entity recognition”.
  • Domain Classification - Agents can be categorized by application domains such as “healthcare”, “finance”, or “manufacturing”, enabling domain-specific discovery.
  • Modular Extensions - OASF records support modular extensions for protocol-specific metadata (A2A cards, MCP server configurations, GitHub Copilot integrations), allowing agents to work seamlessly across different agent frameworks.

DIR indexes records by their skills and domains, enabling natural capability-based queries like:

  • “Find agents with image analysis capabilities”
  • “Discover agents that can perform sentiment analysis”
  • “Show me all agents in the healthcare domain with natural language processing skills”

This semantic approach to discovery is far more powerful than simple name-based lookups, enabling developers to find the right agents based on what they need them to do.

Content-Addressed Naming

DIR uses Content Identifiers (CIDs) for naming directory records. CIDs provide a self-describing, content-addressed naming scheme that ensures:

  • Global Uniqueness - CIDs are cryptographic hashes of the record content, making them globally unique without requiring a central authority to assign identifiers.
  • Immutability - Any change to a record produces a different CID, providing a natural versioning mechanism and tamper detection.
  • Self-Verification - Anyone can verify that the content matches its CID by recomputing the hash, enabling trustless verification.

In addition to CID-based addressing, DIR supports verifiable domain-based names that enable human-readable references while maintaining cryptographic verification. For example, example.org/my-agent can be mapped to a CID while preserving the trust model through DNS-based verification.

This dual naming approach provides both the usability of human-readable names and the security guarantees of content-addressed identifiers.

Distributed DHT-Based Routing

DIR uses libp2p Kad-DHT for both server and content discovery, providing a proven, scalable foundation for distributed routing. This architecture enables:

  • Decentralization - No single point of failure or central authority
  • Fault Tolerance - The DHT can handle node churn and network partitions gracefully
  • Scalability - DHT-based routing scales to thousands of nodes and millions of records
  • Resilience - Multiple nodes can host the same records, providing redundancy
  • Efficient Lookup - Logarithmic search complexity for fast discovery even at scale

DIR implements a two-phase discovery process powered by distributed hash tables (DHT):

1. Capability-to-Record Mapping

When an agent publishes its capabilities, DIR performs the following steps:

  • Extract taxonomy data from the OASF record
  • Announces the record’s CID associated with those taxonomies to the DHT
  • Updates routing tables that map taxonomies to record identifiers

2. Record-to-Server Mapping

DIR tracks which directory nodes store which records:

  • When a node stores a record, it announces its availability to the DHT
  • The DHT maintains mappings from CIDs to server addresses
  • Query resolution identifies optimal data sources

Discovery queries execute this two-phase process:

flowchart LR
    subgraph Query["Discovery Query"]
        Q["Query: agents with NLP skills"]
    end
    
    subgraph Phase1["Phase 1: Capability → CIDs"]
        DHT1[("DHT<br/>Capability Index")]
        CIDS["Matching CIDs:<br/>• bafkrei...abc<br/>• bafkrei...def<br/>• bafkrei...ghi"]
    end
    
    subgraph Phase2["Phase 2: CIDs → Servers"]
        DHT2[("DHT<br/>Provider Index")]
        MAPPING["Server → CID Mapping"]
    end
    
    subgraph Result["Result: Server → CIDs"]
        R1["dir-node-1.example.org<br/>  └─ bafkrei...abc<br/>  └─ bafkrei...def"]
        R2["dir-node-2.example.org<br/>  └─ bafkrei...ghi"]
    end
    
    Q -->|"skill: NLP"| DHT1
    DHT1 -->|"resolve taxonomy"| CIDS
    CIDS -->|"lookup providers"| DHT2
    DHT2 -->|"find hosting nodes"| MAPPING
    MAPPING --> R1
    MAPPING --> R2
    
    style Query fill:transparent,stroke:#6b9fc8,stroke-width:2px
    style Phase1 fill:transparent,stroke:#d4a054,stroke-width:2px
    style Phase2 fill:transparent,stroke:#5ba67a,stroke-width:2px
    style Result fill:transparent,stroke:#9a7bb0,stroke-width:2px
    style Q fill:#6b9fc8,stroke:#4a7a9c,stroke-width:2px
    style DHT1 fill:#d4a054,stroke:#b08540,stroke-width:2px
    style CIDS fill:#d4a054,stroke:#b08540,stroke-width:2px
    style DHT2 fill:#5ba67a,stroke:#478a60,stroke-width:2px
    style MAPPING fill:#5ba67a,stroke:#478a60,stroke-width:2px
    style R1 fill:#9a7bb0,stroke:#7a5f8c,stroke-width:2px
    style R2 fill:#9a7bb0,stroke:#7a5f8c,stroke-width:2px

The final result is a mapping of servers to their hosted CIDs, enabling the client to download records from optimal sources.

Security and Trust

In distributed agentic systems, trust is paramount. DIR provides a comprehensive security model that combines content integrity and workload identity to enable secure agent discovery across organizational boundaries.

Content Integrity and Provenance

All records are identified by their CID, enabling anyone to verify that content hasn’t been tampered with by recomputing the hash. Records can be signed using OIDC flows or private keys, proving authorship and enabling trust decisions based on publisher reputation.

DIR supports local trust chain verification, allowing organizations to:

  • Establish their own trust anchors
  • Define verification policies for external records
  • Validate complete provenance chains from publisher to record
  • Make informed decisions about agent selection based on trust policies specific to their use case
# Verify a record's signature and trust chain
dirctl verify bafkreiabcd1234567890

# Output includes verification status, signer identity, and trust chain details

This multi-layered security approach combines content-addressed integrity with cryptographic signing and trust chain verification, enabling secure discovery in a decentralized ecosystem without relying on centralized authority.

Zero-Trust Security

DIR leverages SPIFFE (Secure Production Identity Framework For Everyone) and its runtime implementation SPIRE to provide zero-trust security for workload identity and communication. This enables:

  • Workload Identity - Every DIR component receives a cryptographically verifiable identity in the form of a SPIFFE ID like spiffe://dir.example/ns/production/sa/my-agent. This identity is used for authentication and authorization across the system and network.
  • Mutual TLS (mTLS) - SPIRE issues SVIDs enabling automatic mTLS between all DIR components. Communication is encrypted and both parties are authenticated without manual certificate management.
  • Cross-Organization Federation - Organizations can federate their SPIRE deployments by exchanging trust bundles to form networks. This enables secure, authenticated communication between DIR nodes in different organizations without custom integration.
  • Policy-Based Access Control - SPIFFE IDs enable fine-grained authorization policies. Organizations can define which workloads can push records, which can query, and which external trust domains are authorized for federation and for which operations.

OCI-Based Distributed Storage

DIR differs from block storage systems like IPFS in its approach to distributed object storage, leveraging the OCI (Open Container Initiative) distribution specification for content storage and retrieval.

Content Retrieval

  • DIR directly stores complete records rather than splitting them into blocks
  • Records are retrieved as complete units using standard OCI protocols
  • No complex block reassembly or multi-source optimization needed

Distribution Layer

  • Records are stored and transferred using OCI artifacts
  • Any OCI distribution-compliant server can participate in the DIR network
  • Servers retrieve records from each other using well-established OCI protocols
  • Existing OCI infrastructure (registries, caching layers, CDNs) can be leveraged

Integration Support

While DIR uses zot as its reference OCI store, the system works with any server that implements the OCI distribution specification. This means you can use existing container registries like Docker Registry, Harbor, or cloud-provider managed registries as DIR storage backends.

This OCI-based approach provides:

  • Interoperability - Leverage existing OCI tooling and infrastructure
  • Simplicity - Standard HTTP-based protocol without custom networking requirements
  • Efficiency - Single-request record retrieval without block coordination overhead
  • Enterprise Integration - Use existing OCI registries and security policies

Runtime Discovery Integration

DIR includes a runtime discovery service that automatically discovers and indexes agent workloads running in a specific environment, bridging the gap between deployed agents and directory records. The runtime discovery system provides real-time visibility into active agents, enabling dynamic discovery and coordination in orchestrated environments like Kubernetes or Docker, but also local environments such as developer machines or edge devices.

Workloads can be discovered through annotations that indicate they should be indexed by DIR. For example, in Kubernetes, a pod can be annotated to enable discovery:

apiVersion: v1
kind: Pod
metadata:
  name: translation-agent
  annotations:
    org.agntcy/discover: "true" # Enable discovery for this workload
    org.agntcy/agent-type: "a2a" # Indicate the protocol or framework used
    org.agntcy/agent-record: "my-agent/v1.0.0" # Indicate reference to a DIR record

The DIR runtime discovery is an optional component of the DIR stack that makes workloads queryable alongside statically published records. This enables hybrid discovery where some agents are published ahead of time while others are discovered dynamically as they’re deployed. The same discovery and security models apply to both, providing a unified experience for developers and users.

Real-World Use Cases

Building Agent Marketplaces

DIR provides the foundation for building agent marketplaces where developers can publish agents and users can discover them:

Publisher Workflow:

  1. Developer creates an agent with specific capabilities
  2. Generates an OASF record describing skills, domains, and deployment details
  3. Signs the record with their identity for authenticity
  4. Publishes to DIR which announces the CID and metadata to the DHT

Consumer Workflow:

  1. User queries DIR for agents with specific capabilities
  2. DIR returns matching records with CIDs
  3. User reviews metadata, verifies signatures, and checks trust chains
  4. User pulls the complete record and retrieves deployment artifacts (Docker images, API endpoints)
  5. User deploys or invokes the agent

This decentralized marketplace model enables anyone to publish and discover agents without requiring approval from a central authority or platform lock-in.

Multi-Agent System Coordination

In complex multi-agent systems, agents need to discover collaborators dynamically:

from agntcy.dir_sdk.client import Config, Client
from agntcy.dir_sdk.models import search_v1

# Select either local/cache or remote DIR node based on context
client = Client(Config(server_address="dir.example.org:8888"))

# Agent needs image analysis capability
# Use network or local discovery based on context
results = client.search_records(search_v1.ListRequest(
  queries=[search_v1.RecordQuery(
    type=search_v1.RECORD_QUERY_TYPE_SKILL_NAME,
    value="images_computer_vision/object_detection",
  )]
  limit=5,
))

# Select the best candidate based on metadata
for item in results:
    # Verify signature, check version, evaluate endpoints
    if meets_requirements(item.record):
        endpoint = item.record.data['locators'][0]['url']
        # Invoke the discovered agent
        invoke_agent(endpoint, task_data)
        break

This pattern enables dynamic capability discovery where agents find and coordinate with each other based on current requirements rather than hardcoded integrations.

Federated Agent Networks

Organizations can run their own DIR nodes while participating in a federated discovery network:

  • Internal Directory Node - Organization runs a DIR node behind their firewall, containing proprietary agents not shared externally.
  • Federation - The internal node connects to external DIR nodes via DHT, enabling discovery of public agents while keeping internal agents private.
  • Policy Enforcement - Organizations define trust policies determining which external agents can be discovered and used, based on publisher identity, signatures, and verification chains.

This federated model enables both private agent catalogs and participation in the broader ecosystem, with fine-grained control over what’s shared and discovered.

Protocol-Agnostic Discovery

DIR’s OASF-based approach provides a unified discovery layer across different agent protocols:

  • A2A Agents - Agents implementing the Agent-to-Agent protocol can be described in OASF records with A2A-specific metadata in modules.
  • MCP Servers - Model Context Protocol servers can be imported to OASF format, indexed by capabilities, and discovered through DIR.
  • Custom Protocols - Organizations developing custom agent protocols can define public or private OASF modules for their specific metadata while leveraging DIR’s discovery infrastructure.

Example: A user searching for “text completion” might discover agents using A2A, MCP, or custom protocols - all through a single capability-based query. The OASF record clearly indicates which protocol each agent uses, enabling proper invocation.

Getting Started

Installation

DIR provides a comprehensive suite of tools that make it easy to publish, discover, and work with agent records.

Tool Install Prerequisite Usage
dirctl brew tap agntcy/dir https://github.com/agntcy/dir/
brew install dirctl		 - CLI Documentation
Go SDK go get github.com/agntcy/dir/client - Go SDK Documentation
Python SDK pip install agntcy-dir dirctl (sign/verify) Python SDK Documentation
JS/TS SDK npm install agntcy-dir dirctl (sign/verify) JS/TS SDK Documentation
MCP Server dirctl mcp serve dirctl Directory MCP Server Blog Post
MCP Integration Documentation
Deployment - - Getting Started

Quick Example

Publish and discover your first agent in minutes:

  1. Deploy a DIR node locally
helm pull oci://ghcr.io/agntcy/dir/helm-charts/dir --version v1.0.0
helm upgrade --install dir oci://ghcr.io/agntcy/dir/helm-charts/dir --version v1.0.0
kubectl port-forward svc/dir-apiserver 8888:8888
  1. Download a sample agent record
curl -o sample-record.json https://raw.githubusercontent.com/agntcy/dir/refs/heads/main/e2e/shared/testdata/record_100.json
  1. Use CLI to publish and discover agents
# Push and sign the agent record to DIR
dirctl push sample-record.json --sign

# Search for agents with specific capabilities
dirctl search --skill "natural_language_processing/*"

# Pull a specific record by CID
dirctl pull baeareiabbog2umgduqhlcb64fzt6adn34kblzvru3fdzkl75hjhwt6h3da

# Verify a record's signature and trust chain
dirctl verify baeareiabbog2umgduqhlcb64fzt6adn34kblzvru3fdzkl75hjhwt6h3da
  1. Use SDK to publish and discover agents
from agntcy.dir_sdk.client import Config, Client
from agntcy.dir_sdk.models import core_v1, search_v1

# Connect to a DIR node
client = Client(Config(server_address="localhost:8888"))

# Push an agent record (requires signing credentials)
with open("sample-record.json", "r") as f:
    record = json.load(f)

cid = client.push(records=[core_v1.Record(data=record)])[0]
print(f"Published agent with CID: {cid}")

# Search for agents by capability
results = client.search_records(search_v1.ListRequest(
    queries=[search_v1.RecordQuery(
        type=search_v1.RECORD_QUERY_TYPE_SKILL_NAME,
        value="natural_language_processing/*",
    )],
    limit=10,
))

# Retrieve and inspect matching agents
for item in results:
    print(f"Found: {item.record.name} (CID: {item.cid})")
    print(f"  Skills: {item.record.data.get('skills', [])}")
    print(f"  Locator: {item.record.data['locators'][0]['url']}")

Why DIR Matters

As AI systems evolve from isolated models to interconnected networks of specialized agents, discovery infrastructure becomes critical. DIR provides a foundation that:

  • Enables Semantic Discovery - Find agents by what they can do, not just by name or endpoint.
  • Ensures Data Integrity - Content-addressed naming and cryptographic signing guarantee authenticity.
  • Scales Without Centralization - DHT-based routing eliminates single points of failure.
  • Bridges Organizational Boundaries - Federated architecture enables cross-organization discovery with fine-grained trust policies.
  • Supports Protocol Diversity - Native integration with A2A, MCP, and custom agent protocols through OASF extensions.
  • Simplifies Development - Publish once, discover everywhere with intuitive CLI and SDK tooling.

Whether you’re building a multi-agent AI system, an agent marketplace, or a platform that coordinates specialized AI services, DIR provides the discovery infrastructure you need.

The Road Ahead

DIR is actively developed as an open-source project under the Apache 2.0 License. The project has reached v1.0 with production-ready capabilities.

Current Capabilities:

  • OASF-based capability discovery with hierarchical taxonomies
  • DHT-based distributed routing for scalable discovery
  • Cryptographic signing with OIDC and private key support
  • OCI distribution protocol for interoperable storage
  • Data synchronization between Directory nodes
  • Runtime discovery for Kubernetes and Docker workloads
  • CLI, Go SDK, Python SDK, and JavaScript SDK
  • MCP server integration for AI assistants

Under Active Development:

  • Enhanced DHT performance and routing optimizations
  • Extended SPIFFE/SPIRE integration for enterprise deployments
  • Advanced trust chain verification policies
  • Additional runtime discovery targets (edge devices, serverless)
  • Deeper agentic protocol integrations
  • Cross-network federation protocols

Get Involved

Public Instance

A public DIR instance is available for testing and experimentation at prod.gateway.ads.outshift.io:443 in read-only mode. This instance is open for anyone that is part of github.com/agntcy organization, making it a great place to get hands-on experience with DIR.

### Configuration
# Set environment variables to connect to the public DIR instance
export DIRECTORY_CLIENT_SERVER_ADDRESS="prod.gateway.ads.outshift.io:443"
export DIRECTORY_CLIENT_AUTH_MODE="github"

### Interactive Authentication with GitHub OAuth
dirctl auth login 

### Non-Interactive Authentication with GitHub Token
# The token must have `user:email` and `read:org` scope for authentication to work
export DIRECTORY_CLIENT_GITHUB_TOKEN="ghp_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

### Usage
# Now you can use dirctl or the SDK to query the public DIR instance
dirctl search --skill "*"

Check the Directory Testbed Authentication Modes blog for detailed guides on integration and authentication with the public DIR instance. If you’re interested in publishing your own agents, running a full DIR node, or joining the public DIR network, check github.com/agntcy/dir-staging on how to get started.

Community

DIR is open source and welcomes contributions:

Join the community building the discovery layer for agentic AI. Try DIR in your next project, contribute to the codebase, or share your use cases.

DIR is developed by AGNTCY Contributors and released under the Apache 2.0 License.