Hosted AGNTCY Agent Directory

A public hosted instance of the Agent Directory is available at https://hub.agntcy.org/. In this section we describe the main features of this instance which is provided AS IS to the community to help users familiarize themselves with the Agent Directory.

AGNTCY Agent Directory is designed to provide a robust multi-organization platform for hosting and managing Agent Directory Records, which we will refer to as simply “records” or “agent records.” AGNTCY Agent Directory acts as a centralized point for organizing and accessing agent records. This hosted service is enhanced by a gRPC API that supports efficient service communication and integration, ensuring seamless interaction between components.

AGNTCY Hub serves as a central platform for hosting and managing various agent-related services. The main purpose of the Agent Directory Service component of Hub is to provide a comprehensive solution for developers and IT admins to register, discover, and manage records in an organized manner. By offering a secure environment for authentication and user management, it ensures that organizations can confidently manage their agent directories and related services.

Core Concepts

The AGNTCY Agent Directory is organized around a few basic concepts:

• Users - A user is the basic unit of authentication and authorization in the Hub, usually corresponding to a human or service account.

• Organization - An organization provides a way to group users for sharing agents and handling administrative tasks. A user can belong to many organizations, but organizations are flat and cannot belong to one another.

• Agent Records - An Agent Record is a collection of data and metadata about a particular agentic application or service. The schema of the Record is defined in OASF and contains, for example, a collection of skills.

• Repositories - A agent repository collects agent records that describe different versions of the same agent into one location to provide an overview of its history and current status. A Record can belong to only one repo, while a user or organization may access many different repos and by extension their agent records.

The Agent Directory Service (ADS) provides storage for agent records while the frontend hosted AGNTCY Agent Directory provides access control with Users and their Organizations and management of agent records in their Repos.

Features

AGNTCY Agent Directory enables users to:

• View and search for public agent records.

• View your organization’s public and private agent records.

• Publish agent records to an agent repository.

• Access multiple separate organizations.

• Invite other users your organizations.

Using the Hub

Signing up for the hosted AGNTCY Agent Directory and Logging in

To get started with the hosted AGNTCY Agent Directory, sign up for free at the AGNCTY Agent Directory homepage. You can sign up with your GitHub account or by providing an email and password. Once your account is created, simply log in. When first logging in, you are prompted to create a name for your default organization. This organization is a personal space where all repositories belong to you.

View and Search for Agents

“The Explore page allows users to browse and search through available agent repositories.

You can refine the results using predefined filters and open search:

• Use the Search bar to search for a text string in a repository name. To clear the search bar, click the ×.

• Use the drop-down Filters list to narrow the results by Agent Skill.

• Use the drop-down Sort by list to sort the displayed items by Most Recent or Oldest.

You can change organizations by clicking the Org drop-down list and selecting another organization.

Manage Agents associated with Your Organization

The Agent Directory Page allows you to view, edit, and create agent repositories in the AGNTCY Agent Directory. Here the records are displayed in a table with customizable columns.

You can select which columns are displayed, and in which order, by clicking the Arrange Columns button (▥).

You can reload the listed items by clicking the Reload button (⟳).

You can refine the results using predefined filters and open search:

• Use the Search bar to search for a text string in an agent repository name. To clear the search, click the ×.

• Use the drop-down Filters list to narrow the results by Agent Skill.

• Use the drop-down Sort by list to sort the displayed items by Most Recent or Oldest.

Agent Actions

Clicking the three dots (⁝) at the end of any row in the Agent Directory table opens a drop-down list of actions you can perform on that agent repository.

• Click Open Details to view the agent details.

• Click Edit to edit the agent.

• Click Delete to remove the agent repo from the directory, including all of its agent records.

Agent Details

Clicking on an agent repository opens the Agent Details page with further information on the agent repository.

The General tab lists the following information from the agent record:

• A description of the agent.

• The skills associated with the agent.

• The version number and date of publishing.

• The CLI command to push a new version of the agent.

The Versions tab lists the published versions of the agent.

The Settings tab allows the owner to change the visibility of the agent.

Add an Agent Directory Record to the AGNTCY Agent Directory

Agent directory records are associated with a repository. A repository must exist first for an agent record to be added to it.

Create a new agent repository

To add an agent repository in the AGNTCY Agent Directory:

1. Click the + New Repository button.

2. Enter the repository name and description.

3. Select the visibility for your agent repository.

   • Public agent repositories appear in search results.

   • Private agent repositories are only visible in your organization.

4. Click Publish.

5. You can also publish the agent repository using the generated CLI command.

6. Click Finish.

At this point, you have an empty repository ready for agent records.

Adding an Agent Directory Record to a Repository

Adding an Agent Directory Record has these prerequisites:

1. You need to install the AGNTCY Agent Directory command line tool, dirctl.

2. You need an agent record that conforms to AGNTCY Agent Directory requirements.

3. You need to sign your agent record.

Pre-req 1: Install dirctl

Binary packages and installation of the AGNTCY Agent Directory dirctl command line tool are available in multiple forms on GitHub:

• container image

• homebrew

• binary

After installation, use the dirctl and dirctl hub commands to list the available commands.

Pre-req 2: Create a Conforming Agent Directory Record

An Agent Directory record is stored in JSON format. The record is specific to one entry in the Agent Directory. The structure of each AD record is defined by the Open Agentic Schema Framework starting at the root with an Agent object.

To be useful, an agent record should include at least the following:

• Name of the agent (the name MUST match the organization and repository name in the AGNTCY Agent Directory),

• Version of the agent (use semantic convention)

• Description (something to help any viewer understand what your agent does, what is the use case it is applicable to, expected inputs and outputs, LLM used, runtime, etc)

• Locator, per OASF locator objects

  • type(s) (source code, agent as a service, docker image, etc) matching the supported types in the OASF locator objects

  • url (corresponding address to find the agent)

• Skills - MUST follow the OASF skills schema

And it will look like this

{
  "name": "organization/my-agent",
  "version": "2.0",
  "description": "This agent takes any text input and condenses it down to 3 bullets of less than 100 characters each using any LLM.",
  "locators": \[
    {
      "url": "https://github.com/example/agent_A",
      "type": "package-source-code"
    }
  \],
  "skills": \[
    {
      "class_uid": 10201
    }
  \]
}

Pre-req 3: Signing Agent Directory Records using dirctl

You must sign the record before pushing it to the AGNTCY Agent Directory. Unsigned records are rejected by the API.

To sign an agent record in the file agent.json using the default provider sigstore, run:

dirctl sign agent.json > agent.signed.json

The signing service login page opens in your browser. Use your credentials to log in. The agent record will be augmented with a generated signature and will be output in JSON format. The new signed agent record can be pushed to the Hub.

For further details on signing, please see the Agent Directory HOWTO.

Pushing Agent Directory Records using dirctl

Once all pre-requisites are complete, you are ready to push an agent record to an agent repository that you have write access to.

Pushing and pulling agent directory records is done using thd dirctl tool.

From your terminal window:

1. Login to your AGNTCY Agent Directory account

   dirctl hub login

   The login page opens in your browser. Use your credentials to log in.

2. Verify your AGNTCY Agent Directory organizations and which one you are currently logged into:

   dirctl hub orgs

   Switch organizations as needed to the organization that you want to push your agent record to:

   dirctl hub orgs switch

3. Push your signed, conforming agent record to the desired organization/repository:

   dirctl hub push <organization/repository_name> <local filename of your signed agent json file>

4. When you’re done, logout of your hub account

   dirctl hub logout

Pulling Agent Directory Records using dirctl

You can also pull an agent directory record via dirctl using the command listed on the agent details page.

Verifying an Agent Directory Record Signature

The verification process allows validation of the agent record signature against a specific identity.

To verify that an agent record is properly signed, you can run dirctl verify agent.json.

To verify the signature against a specific identity, for example to check if an agent record originates from GitHub Agntcy users, run:

dirctl verify agent.json \ 
                 --oidc-issuer "(.*)github.com(.*)" \
                 --oidc-identity "(.*)@agntcy.com"

For further details on verification, please see the Agent Directory HOWTO.

Managing Organizations and Users

Settings

The settings page allows you to manage your organizations and users.

Organizations

Organizations represent groups of users within the Hub, each with its own repositories. Users can be member of many organizations. The organizations available to you are listed under the Organizations tab.

Clicking the three dots (⁝) at the end of any row in the table opens a drop-down list of actions you can perform on that organization.

• Click Switch to switch to the organization.

You can reload the listed items by clicking the Reload button (⟳).

Users

The users in a organization are listed under the Users tab.

You can invite other users to the organization by clicking the + Invite User button.

Note: You cannot invite other users to your personal organization created during signing up. To collaborate with others, create a new organization and invite them to it.

Clicking the three dots (⁝) at the end of any row in the table opens a drop-down list of actions you can perform on that user.

• Click Edit to edit the user’s role.

• Click Delete to delete the user.

You can reload the listed items by clicking the Reload button (⟳).

Troubleshooting pushing agents to the AGNTCY Agent Directory

Error: failed to validate access token: invalid session token You forgot to login to your AGNTCY Agent Directory account

Error: failed to push agent: could not receive response: rpc error: code = InvalidArgument desc = agent: invalid value in agent name The “agent name” attribute in the json file does not match the organization/repository in the Hub.

Error: failed to push agent: could not receive response: rpc error: code = AlreadyExists desc = agent: data model with same version already exists You are trying to upload a new agent record with the same name and version as one that exists already. Update the version number in the json file.

Details on other uses of the dirctl command to interact with the Agent Directory are available in the documentation. After installation, use the dirctl hub command to list the available commands.