Agent Registry: Finding and Publishing Agents¶

NEAR AI agents can be deployed and hosted in a common registry, allowing the community to share their creations. This registry is used by the NEAR AI Developer Hub to store and serve agents.

Let's take a look at how we can navigate this registry, download agents, and contribute our own agents to the ecosystem.

Note

The agent registry is backed by an S3 bucket with metadata stored in a database.

Finding an Agent¶

There are two main ways to navigate the agent registry to discover agents:

For the rest of this guide, we will use the CLI to find and deploy agents.

Tip

Refer to the Quickstart Guide to learn how to install the CLI and login to the AI Developer Hub.

View all agents¶

To view all agents with nearai CLI, run:

nearai registry list --category agent

Example Output

┌─────────────────────────────────┬─────────────────────────┬───────┐
│ entry                           │ description             │ tags  │
├─────────────────────────────────┼─────────────────────────┼───────┤
│ zavodil.near/ai16z-docs/1.03    │ AI agent with AI16Z ... │ agent │
├─────────────────────────────────┼─────────────────────────┼───────┤
│ flatirons.near/common-tool...   │ A library of common ..  │ llama │
├─────────────────────────────────┼─────────────────────────┼───────┤
│ jayzalowitz.near/example_a...   │ Example agent           │       │
├─────────────────────────────────┼─────────────────────────┼───────┤
│ ...                             │ ...                     │ ...   │
└─────────────────────────────────┴─────────────────────────┴───────┘

Filtering Agents¶

You can further filter the agents with two flags:

--namespace : The developer that created it
--tags: Any tags that were added to the agent

For example, to find all agents created by gagdiez.near with the tag template, run:

nearai registry list  --category agent \
                      --namespace gagdiez.near \
                      --tags template \
                      --show_all

Tip

You can use the info command to get more details about a specific agent, for example:

nearai registry info gagdiez.near/hello-ai/latest

Downloading an Agent¶

Once you find an agent that you would like to download, use the download command to save it locally. Agent details are passed in the following format:

nearai registry download <account.near>/<agent_name>/<version>

The version can be a specific version number, or latest to download the most recent version.

Example:

# Download a hello world agent
nearai registry download gagdiez.near/hello-ai/latest

This command saves the agent locally in .nearai/registry under your home directory.

The example above would save to: ~/.nearai/registry/gagdiez.near/hello-ai/latest.

Tip

The --force flag allows you to overwrite the local agent with the version from the registry.

Uploading an Agent¶

If you created an agent and would like to share it with others, you can upload it to the registry. To upload an agent, you must be logged in.

The upload command requires the path to the agent folder stored locally, for example:

nearai registry upload ~/.nearai/registry/<your-account.near>/<agent_folder>

The folder must contain:

agent.py: Agent logic
metadata.json: Agent information (ex: description, tags, and model, etc.)

Example metadata.json file

metadata.json

{
"name": "hello-ai",
"version": "0.0.1",
"description": "A friendly agent",
"category": "agent",
"tags": [],
"details": {
  "agent": {
    "defaults": {
      "model": "llama-v3p1-70b-instruct",
      "model_provider": "fireworks",
      "model_temperature": 1.0,
      "model_max_tokens": 16384
    }
  }
},
"show_entry": true
}