Agent Registry

代理注册表

一个与供应商无关、与代理框架无关的AI代理、技能和MCP服务器注册表。

将元数据与OCI注册表一起存储。接受来自外部工具的评估信号。强制执行促销生命周期。适用于任何代理框架。不存储二进制文件或计算信任分数。

Architecture

快速开始

go build -o agentctl ./cmd/agentctl
./agentctl server start
open http://localhost:8080

演示


全程解说演练（2分钟）

演示

幻灯片介绍问题、架构和工作流程：

查看演示文稿

网页用户界面

服务器在根URL处嵌入了一个目录UI。按种类浏览工件，按状态过滤，跨所有种类搜索，并点击查看身份、OCI引用、评估记录、升级历史和已解决的依赖关系。

Catalog view

Detail panel — eval records, promotion history, dependencies

运作原理

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 inspect ...
                          --oci ghcr.io/acme/agent:1.0      agentctl deps ...
                          (draft — private, mutable)        agentctl get ... --format a2a

                 or  ──>  agentctl init --path .            # import from a running agent
                          (LLM generates AgentCard)         agentctl import --from-a2a \
                                                              https://agent/.well-known/agent-card.json
                     ──>  agentctl eval attach ...
                          (external tools submit results)   # export for deployment
                                                            agentctl get agents acme/x 1.0 \
                     ──>  agentctl promote --to evaluated     --format a2a > agent-card.json
                     ──>  agentctl promote --to approved    # serve at /.well-known/agent-card.json
                     ──>  agentctl promote --to published

基于标准的身份

每种工件类型都使用开放标准作为其原生身份格式。注册表用治理来包装它。

逐步

直接推送标准文档。 使用以下命令传递A2A代理卡、MCP服务器.json或SKILL.md --namespace 和 --oci注册表从标准文档中提取身份信息。

agentctl push agents agent-card.json \
    --namespace acme --oci ghcr.io/acme/my-agent:1.0.0

或者生成一个。 点 agentctl init 在你的项目中。LLM扫描源代码、Dockerfile、依赖项和README以生成清单。无需手动编写YAML。

agentctl config set init.provider openai
agentctl config set init.model gpt-4o-mini
agentctl init --path ./my-agent --image ghcr.io/acme/my-agent:1.0.0 -o manifest.yaml

使用Anthropic（消息API）、OpenAI（聊天完成、响应API）或任何兼容的端点（Ollama、vLLM、LiteLLM）通过 --base-url.

或者使用完整的注册表清单。 传统的YAML格式仍然有效。

agentctl push agents manifest.yaml

附加eval记录（可选）。 注册表存储来自外部工具的结果。它不进行评估。

agentctl eval attach agents acme/my-agent 1.0.0 \
    --category safety --provider garak --benchmark toxicity --score 0.96

推广。 每一步都是一个有效的过渡。内容在以下情况下变得不可变 evaluated.

agentctl promote agents acme/my-agent 1.0.0 --to evaluated
agentctl promote agents acme/my-agent 1.0.0 --to approved
agentctl promote agents acme/my-agent 1.0.0 --to published

发现、检查、部署。

agentctl search "kubernetes diagnostics"
agentctl inspect agents acme/my-agent 1.0.0
agentctl deps agents acme/my-agent 1.0.0
agentctl get agents acme/my-agent 1.0.0   # read OCI ref, then docker pull

命令行界面

agentctl config init                     Interactive LLM provider setup
agentctl config set          Set config value
agentctl config show                     Show config

agentctl init -p ./project -o out.yaml   Generate manifest from code (LLM)
agentctl push                Register artifact (draft)
agentctl push   --namespace  --oci    Push standard doc (AgentCard, server.json, SKILL.md)
agentctl get   [version] [--format a2a|server-json|skill-md]     Get artifact details
agentctl list                      List artifacts
agentctl delete     Delete draft
agentctl promote    --to 
agentctl eval attach    --category --provider --benchmark --score
agentctl eval list   
agentctl inspect        Status + evals + promotion history
agentctl deps           Dependency graph from BOM
agentctl search                   Full-text search across all kinds
agentctl import --from-a2a  --namespace --oci   Import agent from A2A AgentCard URL
agentctl server start [--port] [--db]    Start server (UI at /, API at /api/v1)

` 是 agents, skills，或 mcp-servers`.

API

全部在 /api/v1.答复包含在 { "data": ..., "_meta": {...}, "pagination": {...} }错误遵循RFC 7807。

|方法|路径|| |--------|------|-| |得到| /{kind} |列表| |职位| /{kind} |创建（草稿）| |得到| /{kind}/{ns}/{name}/versions/{ver} |获取| |删除| /{kind}/{ns}/{name}/versions/{ver} |删除（仅草稿）| |职位| /{kind}/{ns}/{name}/versions/{ver}/promote |推广| |职位| /{kind}/{ns}/{name}/versions/{ver}/evals |提交评估| |得到| /{kind}/{ns}/{name}/versions/{ver}/evals |列出评价| |得到| /{kind}/{ns}/{name}/versions/{ver}/inspect |检查| |得到| /{kind}/{ns}/{name}/versions/{ver}/dependencies |Deps| |得到| /{kind}/{ns}/{name}/versions/{ver}/export |导出标准文档| |得到| /search?q=... |搜索| |得到| /ping |健康|

部署

本地

go build -o agentctl ./cmd/agentctl
./agentctl server start --port 8080
# API at http://localhost:8080/api/v1, UI at http://localhost:8080

容器

make image                    # build image (multi-stage, distroless runtime)
make image push               # build and push to quay.io

图片是 quay.io/azaalouk/agent-registry.用覆盖 IMAGE_REPO 和 IMAGE_TAG:

make image push IMAGE_REPO=quay.io/myorg IMAGE_TAG=v0.2.0

Kubernetes

make deploy OVERLAY=k8s

这将创建一个命名空间 agent-registry 使用部署、服务和健康探测。通过端口转发访问：

kubectl -n agent-registry port-forward svc/agent-registry 8080:8080
open http://localhost:8080

开放式移位

make deploy                   # OVERLAY=openshift is the default

这将创建命名空间、部署、服务和TLS路由。获取URL：

oc -n agent-registry get route agent-registry -o jsonpath='{.spec.host}'

部署以非root身份运行，具有只读的根文件系统，传递 restricted SCC没有任何补助金。

拆除

make undeploy                 # removes all resources

生成文件目标

项目布局

cmd/agentctl/       Entry point (thin — embeds UI, calls cli package)
cmd/server/         Standalone server entry point
internal/
  cli/              Cobra commands (HTTP calls + output formatting only)
  handler/          HTTP handlers (parse request, call service, write response)
  service/          Business logic (promotion state machine, BOM resolution)
  store/            Storage interface + SQLite (swappable to Postgres)
  model/            Go types matching spec schemas
  server/           Chi router, middleware, serves embedded UI
pkg/client/         HTTP client (used by CLI, usable by any Go program)
ui/index.html       Catalog UI (embedded in binary, served at /)
schemas/            JSON Schemas (spec source of truth)
api/openapi.yaml    OpenAPI 3.1 spec
deploy/
  Dockerfile        Multi-stage build (distroless runtime)
  k8s/base/         Deployment, Service, Kustomization
  k8s/overlays/     openshift (+ Route) and k8s overlays
Makefile            build, image, push, deploy, undeploy
scripts/            Demo setup/teardown scripts
docs/               Presentation, architecture diagrams, screenshots

设计

身份标准，治理注册。 每种工件类型都使用开放标准（A2A AgentCard、MCP server.json、Agent Skills）作为其本机标识和功能格式。注册表用治理来包装这些：晋升生命周期、评估记录、BOM、来源和信任信号。标准文档回答“这是什么，我如何使用它？”注册表回答“我应该信任它吗？它依赖于什么，谁说它已经准备好了？”

元数据，而非有效载荷。 注册表对OCI工件进行索引。二进制内容保留在ghcr.io/quay.io/ECR中。

三种人工制品 共享升级生命周期、评估记录和BOM。它们在标准身份文档和BOM结构上有所不同：代理声明模型+工具+技能，技能声明工具要求，MCP服务器声明运行时依赖关系+外部服务。

撤离是外部信号。 注册表接受来自任何工具（Garak、eval hub、lm-eval harness、自定义CI）的eval记录。它不运行评估或计算信任分数。信任评分是另一个问题。

晋升是一台国家机器。 draft -> evaluated -> approved -> published -> deprecated -> archived。没有硬编码门。可以在外部添加策略层。

进出口。 直接推送标准文档，或从URL导入(/.well-known/agent-card.json).导出标准文档以进行部署，不进行治理包装。

CLI是一个瘦客户端。 所有逻辑都是服务器端的。任何入口点（CLI、curl、UI、CI管道）的行为都是相同的。

商店可以更换。 SQLite用于开发，Postgres用于生产。实施 Store 界面。

配置

~/.config/agentctl/config.yaml

AGENTCTL_SERVER       Registry URL (default http://localhost:8080)
ANTHROPIC_API_KEY     For init with Anthropic
OPENAI_API_KEY        For init with OpenAI