Getting started

The Agent Directory (dir) allows publication, exchange and discovery of information about AI agents over a distributed peer-to-peer network. It leverages OASF to describe agents and provides a set of APIs and tools to build, store, publish and discover agents across the network by their attributes and constraints. Directory also leverages CSIT for continuous system integration and testing across different versions, environments, and features.

Features

Data Models - Defines a standard schema for data representation and exchange.
Dev Kit - Provides CLI tooling to simplify development workflows and facilitate API interactions.
Plugins - Pluggable components to extend the build process of agent data models for custom use-cases.
Announce - Allows publication of agent data models to the network.
Discover - Listen, search, and retrieve agents across the network by their attributes and constraints.
Security - Relies on well-known security principles to provide data provenance, integrity and ownership.

Prerequisites

To build the project and work with the code, you will need the following installed in your system

Make sure Docker is installed with Buildx.

Development

Use Taskfile for all related development operations such as testing, validating, deploying, and working with the project.

Clone the repository

git clone https://github.com/agntcy/dir
cd dir

Initialize the project

This step will fetch all project dependencies and prepare the environment for development.

task deps

Make changes

Make the changes to the source code and rebuild for later testing.

task build

Test changes

The local testing pipeline relies on Golang to perform unit tests, and Docker to perform E2E tests in an isolated Kubernetes environment using Kind.

task test:unit
task test:e2e

Artifacts distribution

All artifacts are tagged using the Semantic Versioning and follow the checked out source code tags. It is not advised to use artifacts with mismatching versions.

Container images

All container images are distributed via GitHub Packages.

docker pull ghcr.io/agntcy/dir-ctl:v0.2.0
docker pull ghcr.io/agntcy/dir-apiserver:v0.2.0

Helm charts

All helm charts are distributed as OCI artifacts via GitHub Packages.

helm pull oci://ghcr.io/agntcy/dir/helm-charts/dir --version v0.2.0

Binaries

All release binaries are distributed via GitHub Releases.

SDKs

Golang - github.com/agntcy/dir/api, github.com/agntcy/dir/cli, github.com/agntcy/dir/server

Deployment

Directory API services can be deployed either using the Taskfile or directly via released Helm chart.

Using Taskfile

This will start the necessary components such as storage and API services.

task server:start

Using Helm chart

This will deploy Directory services into an existing Kubernetes cluster.

helm pull oci://ghcr.io/agntcy/dir/helm-charts/dir --version v0.2.0
helm upgrade --install dir oci://ghcr.io/agntcy/dir/helm-charts/dir --version v0.2.0

Usage

This document defines a basic overview of main Directory features, components, and usage scenarios.

Although the following example is shown for CLI-based usage scenario, there is an effort on exposing the same functionality via SDKs.

Requirements

Directory CLI client, distributed via GitHub Releases
Directory API server, outlined in the Deployment section.

Build

This example demonstrates the examples of a data model and how to build such models using provided tooling to prepare for publication.

Generate an example agent that matches the data model schema defined in Agent Data Model specification.

cat << EOF > model.json
{
  "name": "my-agent",
  "skills": [
    {"category_name": "Text Generation"},
    {"category_name": "Fact Extraction"}
  ]
}
EOF

Alternatively, build the same agent data model using the CLI client. The build process allows additional operations to be performed, which is useful for agent model enrichment and other custom use-cases.

# Define the build config
cat << EOF > build.config.yml
builder:
  # Base agent model path
  base-model: "model.json"

  # Disable the LLMAnalyzer plugin
  llmanalyzer: false

  # Disable the runtime plugin
  runtime: false
EOF

# Build the agent
dirctl build . > built.model.json

# Override above example
mv built.model.json model.json

Store

This example demonstrates the interaction with the local storage layer. It is used as an content-addressable object store for Directory-specific models and serves both the local and network-based operations (if enabled).

# push and store content digest
dirctl push model.json > model.digest
DIGEST=$(cat model.digest)

# pull
dirctl pull $DIGEST

# lookup
dirctl info $DIGEST

Announce

This examples demonstrates how to publish the data to allow content discovery. To avoid stale data, it is recommended to republish the data periodically as the data across the network has TTL.

Note that this operation only works for the objects already pushed to local storage layer, ie. you must first push the data before being able to perform publication.

# Publish the data to your local data store.
dirctl publish $DIGEST

# Publish the data across the network.
dirctl publish $DIGEST --network

If the data is not published to the network, it cannot be discovered by other peers. For published data, peers may try to reach out over network and request specific objects for verification and replication. Network publication may fail if you are not connected to any peers.

Discover

This examples demonstrates how to discover published data locally or across the network. This API supports both unicast- mode for routing to specific objects, and multicast mode for attribute-based matching and routing.

There are two modes of operation, a) local mode where the data is queried from the local data store, and b) network mode where the data is queried across the network.

Discovery is performed using full-set label matching, ie. the results always fully match the requested query. Note that it is not guaranteed that the data is available, valid, or up to date as results.

# Get a list of peers holding a specific agent data model
dirctl list --digest $DIGEST

# Discover the agent data models in your local data store that can fully satisfy your search query.
dirctl list "/skills/Text Generation"
dirctl list "/skills/Text Generation" "/skills/Fact Extraction"

# Discover the agent data models across the network that can fully satisfy your search query.
dirctl list "/skills/Text Generation" --network
dirctl list "/skills/Text Generation" "/skills/Fact Extraction" --network

It is also possible to get an aggregated summary about the data held in your local data store or across the network. This is used for routing decisions when traversing the network. Note that for network search, you will not query your own data, but only the data of other peers.

# Get a list of labels and basic summary details about the data you currently have in your local data store.
dirctl list info

# Get a list of labels and basic summary details about the data you across the reachable network.
dirctl list info --network