v0.2.0

agentregistry

a vendor-neutral registry for AI agents, skills, and MCP servers

agents skills mcp-servers

$ agentctl server start

The Problem

AI agents are being built everywhere — but there's no standard way to register, discover, or trust them
Container registries store bytes — they don't know what models an agent uses, whether it's been safety-tested, or what it depends on
No supply chain visibility for AI artifacts — what's the BOM? Has it been evaluated? Who approved it?

What the Agent Registry Is

A metadata store that sits alongside OCI registries as a governance and discovery layer

Stores structured metadata about agents, skills, and MCP servers — not the binaries themselves

Accepts evaluation signals from any external tool (Garak, eval-hub, lm-eval-harness, custom CI)

Enforces a promotion lifecycle: draft → evaluated → approved → published

Built on Open Standards

Each artifact kind uses an open standard as its native identity format.

Kind	Standard	Steward	What it carries
Agent	A2A AgentCard	Google / AAIF	Name, skills, capabilities, security, signatures
MCP Server	MCP server.json	Anthropic / AAIF	Name, packages, transport, runtime
Skill	Agent Skills (SKILL.md)	Anthropic	Name, description, instructions

The registry doesn't reinvent identity schemas — it wraps these standards with governance: promotion lifecycle, eval records, BOM, provenance, trust signals

Three Artifact Kinds

Agent

Identity: A2A AgentCard
Autonomous AI system with its own runtime
BOM declares models, tools, skills, orchestration

Skill

Identity: Agent Skills (SKILL.md)
Prompt-based capability, no runtime
BOM declares tool and model requirements

MCP Server

Identity: MCP server.json
Model Context Protocol server
BOM declares runtime deps, external services

All three share:
promotion lifecycle, eval records, BOM, provenance

User Journey


You build an agent        agentctl does the rest            Others find it
──────────────────        ────────────────────              ──────────────

docker push image    ──>  agentctl push agents card.json    agentctl search "k8s"
                          --namespace acme                  agentctl get ... --format a2a
                          --oci ghcr.io/acme/x:1.0                 ↓
                          (draft — private, mutable)        serve at /.well-known/
                                                            agent-card.json
                     ──>  agentctl eval attach ...
                          (external tools submit results)   # or import from a running agent
                                                            agentctl import --from-a2a
                     ──>  agentctl promote --to evaluated     https://agent/.well-known/
                     ──>  agentctl promote --to approved       agent-card.json
                     ──>  agentctl promote --to published

Step 1: Push a Standard Document

Push an A2A AgentCard directly. The registry extracts identity from the standard doc.


# Push an A2A AgentCard
agentctl push agents agent-card.json \
    --namespace acme \
    --oci ghcr.io/acme/cluster-doctor:1.0.0


# Or generate one from source code (LLM-powered)
agentctl init --path ./my-agent \
    --image ghcr.io/acme/cluster-doctor:1.0.0 \
    -o manifest.yaml

Also works with MCP server.json and SKILL.md directories

Step 2: Push & Evaluate


# Register the artifact (lands in draft)
agentctl push agents manifest.yaml


# External tools submit eval records (optional)
agentctl eval attach agents acme/cluster-doctor 1.0.0 \
    --category safety --provider garak \
    --benchmark toxicity --score 0.96

agentctl eval attach agents acme/cluster-doctor 1.0.0 \
    --category functional --provider eval-hub \
    --benchmark accuracy --score 0.88

The registry stores eval records. It does not run evaluations or compute trust scores.

Step 3: Promote

draft → evaluated → approved → published → deprecated → archived


agentctl promote agents acme/cluster-doctor 1.0.0 --to evaluated
agentctl promote agents acme/cluster-doctor 1.0.0 --to approved
agentctl promote agents acme/cluster-doctor 1.0.0 --to published

Content becomes immutable after evaluated. What was evaluated is what gets shipped.

Step 4: Inspect


$ agentctl inspect agents acme/cluster-doctor 1.0.0

agent acme/cluster-doctor@1.0.0
  Status:    published
  Title:     Cluster Doctor
  Published: 2026-02-20T09:24:16Z

Eval Records: 3
  functional     1 record(s)
  safety         1 record(s)
  red-team       1 record(s)
  Average score: 0.92

Promotion History:
  draft → evaluated   — 3 evals pass
  evaluated → approved — Reviewed by platform team lead
  approved → published — Ready for production

Dependency Graph (from BOM)


$ agentctl deps agents acme/cluster-doctor 1.0.0

agent acme/cluster-doctor@1.0.0
  |- mcp-server acme/kubernetes-mcp@2.0.0 [resolved]
  |- mcp-server acme/prometheus-mcp@>=1.0.0 [UNRESOLVED]
  |- skill acme/k8s-troubleshooting@1.0.0 [resolved]
  |- model claude-sonnet-4@anthropic [resolved]

The BOM captures the full dependency graph:

Agents declare models, tools (MCP servers), skills, prompts, orchestration
Skills declare tool requirements (abstract, not tied to specific MCP servers)
MCP Servers declare runtime dependencies, external services

The Governance Envelope

Standard Identity Document
agent → A2A AgentCard | mcp-server → MCP server.json | skill → SKILL.md
WHO is this? WHAT can it do? HOW do I talk to it?

artifacts[]
OCI references

bom
Dependency graph

promotion
draft→published

evalRecords[]
External eval signals

provenance
SLSA, Sigstore, SBOM

trustSignals
Composite score

Standard doc = identity. Registry = governance. No field duplication.

Architecture

agentctl CLI
Thin HTTP client. init, push, list, promote, eval, inspect, search, deps

External Tools
Garak, eval-hub, lm-eval-harness, TrustyAI, custom CI

Consumers
Agent runtimes, AI IDEs, CI/CD

UI — embedded HTML catalog

REST API — Chi router, /api/v1

Service — state machine, BOM resolution

Store Interface — SQLite (PoC) / Postgres

OCI Registries — ghcr.io, quay.io (content)

Design Principles

Standards for identity, registry for governance — A2A, MCP, Agent Skills own identity; registry owns lifecycle
Metadata, not payloads — binary content stays in OCI registries
Evals are external signals — the registry stores them, doesn't compute trust
Promotion is a state machine — no hardcoded gates, policy layers add externally
Import and export — round-trip standard docs; deploy directly from registry
CLI is a thin client — all logic server-side, any entry point behaves identically

What's Next

Kagenti integration — auto-discover agents via A2A, populate registry
MLflow entity/version pattern — agent versions as AgentCards
Trust scoring as a pluggable external service (TrustyAI integration)
Configurable promotion gates (webhook-based policy engine)
Federation (peer discovery, cross-registry search, sync)
Authentication and RBAC

demo


./scripts/demo.sh

UI → http://localhost:8080
API → http://localhost:8080/api/v1