List on Index - AgentSystems

Publishing metadata to the agent index makes your agent discoverable in the AgentSystems platform. The index contains metadata only - your actual agent image can be public or private. Metadata submissions are automatically validated and merged.

Prerequisites

GitHub account with commit signing enabled (Setup Guide)
Agent deployed (see Quickstart)
5 minutes

Commit Signing Required: All commits in your PR must be signed with a verified GPG or SSH key. Unverified commits will be rejected by the auto-merge workflow. This requirement helps verify that commits are cryptographically signed and match the author identity.

Overview

The agent-index repository is an open-source, Git-based registry for agent metadata enabling federated discovery. Instead of a centralized API:

Developers manage their own YAML files in developers/your-github-username/
Pull requests are automatically validated and merged—no manual approval needed
Metadata is published to https://agentsystems.github.io/agent-index/
The AgentSystems UI consumes this index (and can connect to multiple indexes)
Anyone can fork the repository and run their own independent index

Disclaimer: Inclusion in the index does not constitute endorsement. The index provides metadata submitted by developers and does not verify agent quality, functionality, or security.

Step 1: Fork the Repository

Go to github.com/agentsystems/agent-index and click “Fork”. Clone your fork:

git clone https://github.com/your-github-username/agent-index.git
cd agent-index

Step 2: Create Your Developer Profile

Create your developer folder (must match your GitHub username):

mkdir -p developers/your-github-username

Copy the example profile:

cp examples/profile.yaml developers/your-github-username/profile.yaml

Edit developers/your-github-username/profile.yaml:

name: Your Name or Company
developer: your-github-username  # Must match folder name
type: individual          # individual, organization, company, or enterprise
bio: Developer of AI agents for...
website: https://example.com
support_email: hello@example.com

# Optional fields
tagline: Building the future of AI agents
location: San Francisco, CA
twitter_handle: yourhandle
linkedin_url: https://linkedin.com/in/yourprofile
expertise:
  - Natural Language Processing
  - Data Analysis
  - Multi-Agent Systems
open_to_collaboration: true

Complete Developer Profile Schema

Required:

name (string): Display name
developer (string): Developer namespace - must match folder name

Optional:

type (string): “individual”, “organization”, “company”, or “enterprise”
avatar_url (string): Profile image URL
bio (string): Short biography
tagline (string): Short tagline or slogan
company (string): Company name
location (string): Geographic location
years_experience (integer): Years in AI/ML
website (string): Your website URL
support_email (string): Support email
documentation_url (string): Docs URL
twitter_handle (string): Twitter/X handle (without @)
linkedin_url (string): LinkedIn profile
discord_username (string): Discord username
expertise (array): Areas of expertise
featured_work (array): URLs to featured projects
open_to_collaboration (boolean): Open to collaboration
sponsor_url (string): GitHub Sponsors or similar

Step 3: Add Your Agent Metadata

Create the agents folder:

mkdir -p developers/your-github-username/agents

Copy the example agent:

# Create your agent directory
mkdir -p developers/your-github-username/agents/your-agent

# Copy example files
cp examples/agents/demo-agent/agent.yaml developers/your-github-username/agents/your-agent/
cp examples/agents/demo-agent/versions.yaml developers/your-github-username/agents/your-agent/
cp examples/agents/demo-agent/0.1.0.yaml developers/your-github-username/agents/your-agent/

The directory structure will be:

developers/your-github-username/agents/your-agent/
  agent.yaml      # Agent identity (who/what it is)
  versions.yaml   # Version management (which versions)
  0.1.0.yaml     # Version specification (how it behaves)

Edit the three YAML files: agent.yaml - Set your agent identity:

developer - Must match your GitHub username
name - Must match directory name
description, container_image, tags, capabilities - See examples folder for all fields

versions.yaml - Set version management:

latest_version: "0.1.0"
listed_versions: with - "0.1.0" (use dash notation)

0.1.0.yaml - Set version-specific attributes:

version - Must match filename (“0.1.0”)
model_dependencies: with - gemma3:1b (use dash notation)
readiness_level, input_schema, facets - See examples folder for all fields

See examples/agents/demo-agent/ in the repository for complete examples of all three files with all available fields and documentation.

Complete Agent Metadata Schema

Required in agent.yaml (Agent Identity):

name (string): Agent name (lowercase, alphanumeric, hyphens)
developer (string): Your GitHub username (must match folder name)
description (string): Short description
container_image (string): Container image reference without tag (e.g., docker.io/user/agent)

Optional in agent.yaml (Agent Identity):

source_repository_url (string): Source code URL
primary_function (string): Primary function category
tags (array): Searchable tags
capabilities (array): High-level capability descriptions

Required in versions.yaml (Version Management):

latest_version (string): Latest version (must match an existing .yaml file)
listed_versions (array): Versions visible in discovery (each must match an existing .yaml file)

Required in .yaml files (Version Specification):

version (string): Semantic version (e.g., “0.1.0” or “1.0.0-beta.1”), used as container image tag
model_dependencies (array): Required AI models (at least one)

Optional in .yaml files:

readiness_level (string): “experimental”, “beta”, “production”, or “deprecated”
container_image_access (string): “public” or “private”
source_repository_access (string): “public” or “private”
required_egress (array): Required network egress URLs
required_integrations (array): Required external integrations
input_types (array): Supported input data types
output_types (array): Supported output data types
input_schema (object): Input parameter schema
facets (object): Behavioral characteristics and categorization
- context (string): Operating context (personal, professional, general)
- autonomy (string): Autonomy level (Assist, Co-pilot, Auto-pilot)
- latency (string): Latency profile (real-time, interactive, batch)
- cost_profile (string): Cost model (free, $/task,$ /month)
- modalities (array): Supported modalities (text, image, audio, video)
- domains (array): Application domains
- model_tooling (array): Model frameworks (LLM, RAG, fine-tuned, embeddings)
- industries (array): Target industries
- integrations (array): Supported integrations
release_notes (string): Markdown-formatted release notes

See the schemas for complete details:

Step 4: Validate Locally (Optional)

Validation runs automatically on your PR, but testing locally helps catch issues early.

python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install pyyaml jsonschema
python scripts/validate.py all

Should output:

✅ All validations passed!

Step 5: Submit Pull Request

Commit and push:

git add developers/your-github-username/
git commit -m "Add your-github-username profile and your-agent"
git push origin main

Go to your fork on GitHub and click “Contribute” → “Open pull request”.

What Happens Next

Your PR triggers automated workflows:

Policy Gate: Validates folder ownership (checks your GitHub username matches folder name)
YAML Validation: Checks syntax and schema compliance
Auto-Merge: If all checks pass, PR is automatically approved and merged
Build & Deploy: Index is rebuilt and published to GitHub Pages

Your agent should appear at https://agentsystems.github.io/agent-index/ shortly after the build completes.

Publishing New Versions

To publish a new version of your agent:

Create a new version file in your agent directory:

# Copy your current version as a template
cp developers/your-github-username/agents/your-agent/0.1.0.yaml \
   developers/your-github-username/agents/your-agent/0.2.0.yaml

Edit the new version file:
- Update version: "0.2.0" (must match filename)
- Modify any behavioral changes (model, facets, schema, etc.)
- Add release notes
Update versions.yaml:
- Change latest_version: "0.1.0" to latest_version: "0.2.0"
- Add "0.2.0" to listed_versions array
- Optionally remove old versions from listed_versions to hide them

latest_version: "0.2.0"

listed_versions:
  - "0.1.0"    # Keep if users might want old version
  - "0.2.0"    # New version

Commit and push:

git add developers/your-github-username/agents/your-agent/
git commit -m "Release 0.2.0 of your-agent"
git push origin main

Git diff clarity: Adding 0.2.0 shows as a clean new file in your PR, making reviews simple and clear.

Updating Agent Identity

To update your agent’s identity (description, tags, capabilities):

Edit developers/your-github-username/agents/your-agent/agent.yaml
Commit and push to your fork
Open a new pull request
Auto-merge handles the rest

Note: Identity fields affect all versions. Version-specific changes go in the .yaml files.

Security Model

The index uses fork-based ownership:

✅ Only you can modify developers/your-github-username/ (checked via fork ownership)
✅ PRs touching only your folder auto-merge
✅ PRs touching core files require maintainer approval
✅ Multiple validation layers protect the index

Troubleshooting

PR not auto-merging

Check:

All files are in developers/your-github-username/ (folder name must match your GitHub username exactly)
YAML validation passes (check the workflow logs)
You’re submitting from a fork (not a branch in the main repo)
All commits are signed and verified (see below)

YAML validation fails

Common issues:

Syntax error: Check YAML indentation (use spaces, not tabs)
Missing required field: Ensure name, developer (in profile.yaml), version, description, and model_dependencies are present
Invalid value: Check enum fields like readiness_level

Run python scripts/validate.py all locally to see detailed error messages.

Folder ownership check fails

Error: “Developer folder (your-name) does not match PR head repository owner (different-name)” Solution: Your folder name must exactly match your GitHub username. If your fork is under a different account, the folder name must match that account.

Unverified commits

Error: “PR contains unverified commits. All commits must be signed with a verified GPG or SSH key.” Solution:

Verify your git config matches your signing key:

git config user.name    # Should match your GitHub username
git config user.email   # Should match your signing key email

Set up commit signing: GitHub Docs

Configure auto-signing:

git config commit.gpgsign true   # For GPG
# or
git config gpg.format ssh        # For SSH keys
git config user.signingkey ~/.ssh/id_ed25519.pub

If commits are already pushed, you’ll need to amend and force-push (or create a new PR with signed commits)

Next Steps

Discover agents: Browse the index at agentsystems.github.io/agent-index
Deploy private agents: See Deploying Private Agents
Review schemas: Full schemas at github.com/agentsystems/agent-index/tree/main/schema

Documentation Index

​Prerequisites

​Overview

​Step 1: Fork the Repository

​Step 2: Create Your Developer Profile

​Step 3: Add Your Agent Metadata

​Step 4: Validate Locally (Optional)

​Step 5: Submit Pull Request

​What Happens Next

​Publishing New Versions

​Updating Agent Identity

​Security Model

​Troubleshooting

​PR not auto-merging

​YAML validation fails

​Folder ownership check fails

​Unverified commits

​Next Steps

Prerequisites

Overview

Step 1: Fork the Repository

Step 2: Create Your Developer Profile

Step 3: Add Your Agent Metadata

Step 4: Validate Locally (Optional)

Step 5: Submit Pull Request

What Happens Next

Publishing New Versions

Updating Agent Identity

Security Model

Troubleshooting

PR not auto-merging

YAML validation fails

Folder ownership check fails

Unverified commits

Next Steps