Skip to content

docs(rfd): Move registry RFD to preview #455

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
benbrandt wants to merge 2 commits into
base: main
Choose a base branch
from
+146 −66
Open

docs(rfd): Move registry RFD to preview #455

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d052dd6
docs(rfd): Move registry RFD to preview
benbrandt Feb 4, 2026
6a5573b
Remove mention of extensions for now
benbrandt Feb 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions docs/docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -116,14 +116,13 @@
"rfds/proxy-chains",
"rfds/mcp-over-acp",
"rfds/session-usage",
"rfds/acp-agent-registry",
"rfds/auth-methods",
"rfds/rust-sdk-v1",
"rfds/logout-method",
"rfds/session-delete"
]
},
{ "group": "Preview", "pages": [] },
{ "group": "Preview", "pages": ["rfds/acp-agent-registry"] },
{
"group": "Completed",
"pages": [
Expand Down
209 changes: 145 additions & 64 deletions docs/rfds/acp-agent-registry.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,112 +15,193 @@ There is no canonical listing of ACP-compatible agents. Information lives in sca

- Let users discover agents directly inside ACP-aware clients.
- Ensure protocol-version compatibility or capability coverage.
- Keep metadata consistent (auth requirements, hosting model, license, etc.).
- Keep metadata consistent (hosting model, license, etc.).

Every editor builds bespoke manifests or scrapes GitHub, leading to duplication and stale data.

## Agent manifest format (core proposal)

Each agent advertises itself via `agent.json` stored under `<id>/` in the registry repo. JSONC keeps things close to ACP’s JSON-centric schemas while remaining human-friendly during authoring. Fields (required unless noted):

| Field | Description |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | Lowercase slug, unique across registry (also the folder name). |
| `name` | Human-readable label. |
| `version` | Agent release version surfaced to users. |
| `schema_version` | Semver of the manifest schema. Allows future breaking changes. |
| `description` | Description of the agent's functionality and purpose. |
| `homepage` | URL for docs/marketing. |
| `repository` | Source repository URL. |
| `authors` | Array of author/organization names (mirrors `authors` in the TOML example). |
| `license` | Licence (string). |
| `capabilities` | Array of ACP method names implemented (e.g. `["terminal/new","files/read"]`). |
| `auth` | Array of auth options for authentication. This is the trickiest part of the schema. |
| `distribution` | Object mapping target platforms to download/execution info. Each target key follows `<os>-<arch>` format (e.g., `darwin-aarch64`, `linux-x86_64`, `windows-x86_64`). Each target specifies `archive` (download URL), `cmd` (executable path), optional `args` (array of command-line arguments), and optional `env` (object of environment variables). |

Example skeleton:
Each agent advertises itself via a manifest stored as `<id>/agent.json` in the registry repo.

Fields marked with **\*** are required:

| Field | Description |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` **\*** | Unique agent identifier. Lowercase letters, digits, and hyphens; must start with a letter (pattern: `^[a-z][a-z0-9-]*$`). Also the folder name in the registry repo. |
| `name` **\*** | Human-readable display name. |
| `version` **\*** | Semantic version of the agent release (e.g. `1.0.0`). |
| `description` **\*** | Brief description of the agent's functionality and purpose. |
| `distribution` **\*** | Object describing how to obtain and run the agent. Supports three distribution types: `binary` (platform-specific archives), `npx` (Node packages), and `uvx` (Python packages). At least one distribution type must be provided. See [Distribution](#distribution) for details. |
| `repository` | Source code repository URL. |
| `authors` | Array of author/organization names. |
| `license` | SPDX license identifier or `"proprietary"`. |
| `icon` | Path to icon file (relative path or absolute URL). Must be SVG format, 16×16, monochrome using `currentColor` (enables light/dark theme adaptation). See [Icon requirements](#icon-requirements). |

### Distribution

The `distribution` object supports three mutually independent strategies. An agent may provide one or more:

#### `binary`

Platform-specific archive downloads. Keyed by `<os>-<arch>` targets:

| Target | OS | Architecture |
| ----------------- | ------- | ------------ |
| `darwin-aarch64` | macOS | ARM64 |
| `darwin-x86_64` | macOS | x86-64 |
| `linux-aarch64` | Linux | ARM64 |
| `linux-x86_64` | Linux | x86-64 |
| `windows-aarch64` | Windows | ARM64 |
| `windows-x86_64` | Windows | x86-64 |

When using `binary` distribution, builds **must be provided for all three operating systems** (darwin, linux, windows). CI will reject entries that only cover a subset.

Each target is an object with:

| Field | Required | Description |
| --------- | -------- | ----------------------------------- |
| `archive` | Yes | URL to download archive |
| `cmd` | Yes | Command to execute after extraction |
| `args` | No | Array of command-line arguments |
| `env` | No | Object of environment variables |

#### `npx` / `uvx`

Package-manager-based distribution (Node via `npx`, Python via `uvx`). Each is an object with:

| Field | Required | Description |
| --------- | -------- | ----------------------------------------- |
| `package` | Yes | Package name (with optional version spec) |
| `args` | No | Array of command-line arguments |
| `env` | No | Object of environment variables |

### Icon requirements

Icons must meet the following requirements to pass CI validation:

- **SVG format** — only `.svg` files are accepted.
- **16×16 dimensions** — via `width`/`height` attributes or `viewBox`.
- **Monochrome using `currentColor`** — all `fill` and `stroke` values must use `currentColor` or `none`. Hardcoded colors (e.g. `fill="#FF5500"`, `fill="red"`) are rejected.

Using `currentColor` lets icons adapt automatically to the client's light or dark theme.

### Example: binary distribution

```jsonc
{
"id": "someagent",
"name": "SomeAgent",
"version": "1.0.0",
"schema_version": "1",
"description": "Agent for code editing",
"homepage": "https://github.com/example/someagent",
"repository": "https://github.com/example/someagent",
"authors": ["Example Team"],
"license": "MIT",
"capabilities": ["terminal", "fs/read", "fs/write"],
"auth": [
{
"type": "api_key",
},
],
"icon": "icon.svg",
"distribution": {
"darwin-aarch64": {
"archive": "https://github.com/example/someagent/releases/latest/download/someagent-darwin-arm64.zip",
"cmd": "./someagent",
"args": ["acp"],
},
"darwin-x86_64": {
"archive": "https://github.com/example/someagent/releases/latest/download/someagent-darwin-x64.zip",
"cmd": "./someagent",
"args": ["acp"],
},
"linux-aarch64": {
"archive": "https://github.com/example/someagent/releases/latest/download/someagent-linux-arm64.zip",
"cmd": "./someagent",
"args": ["acp"],
},
"linux-x86_64": {
"archive": "https://github.com/example/someagent/releases/latest/download/someagent-linux-x64.zip",
"cmd": "./someagent",
"args": ["acp"],
},
"windows-x86_64": {
"archive": "https://github.com/example/someagent/releases/latest/download/someagent-windows-x64.zip",
"cmd": "./someagent.exe",
"args": ["acp"],
"env": {
"SOMEAGENT_MODE_KEY": "",
"binary": {
"darwin-aarch64": {
"archive": "https://github.com/example/someagent/releases/latest/download/someagent-darwin-arm64.zip",
"cmd": "./someagent",
"args": ["acp"],
},
"darwin-x86_64": {
"archive": "https://github.com/example/someagent/releases/latest/download/someagent-darwin-x64.zip",
"cmd": "./someagent",
"args": ["acp"],
},
"linux-aarch64": {
"archive": "https://github.com/example/someagent/releases/latest/download/someagent-linux-arm64.zip",
"cmd": "./someagent",
"args": ["acp"],
},
"linux-x86_64": {
"archive": "https://github.com/example/someagent/releases/latest/download/someagent-linux-x64.zip",
"cmd": "./someagent",
"args": ["acp"],
},
"windows-x86_64": {
"archive": "https://github.com/example/someagent/releases/latest/download/someagent-windows-x64.zip",
"cmd": "./someagent.exe",
"args": ["acp"],
"env": {
"SOMEAGENT_MODE_KEY": "",
},
},
},
},
}
```

### Example: package distribution

```jsonc
{
"id": "pyagent",
"name": "PyAgent",
"version": "2.1.0",
"description": "A Python-based ACP agent",
"repository": "https://github.com/example/pyagent",
"license": "Apache-2.0",
"distribution": {
"uvx": {
"package": "pyagent@latest",
"args": ["--mode", "acp"],
},
},
}
```

## Registry schema

The aggregated `registry.json` file conforms to the registry schema and contains:

| Field | Description |
| --------- | --------------------------------------------------------------------------------------------------------- |
| `version` | Registry schema version (semver, e.g. `1.0.0`). |
| `agents` | Array of agent entries (each following the agent manifest schema above, sourced from `agent.json` files). |

## Authentication requirements

To be listed in the registry, an agent **must support at least one** of the following authentication methods:

- **Agent Auth** — the agent handles the OAuth flow independently (opens the user's browser, runs a local callback server, exchanges the authorization code for tokens).
- **Terminal Auth** — the agent provides an interactive terminal-based setup experience (launched with additional args/env specified in the auth method).

CI verifies this by checking that the agent returns an `authMethods` array in its `initialize` response, with at least one method. See the [ACP auth methods RFD](./auth-methods) for the full specification.

## What we propose to do about it

1. **Manifest spec** (above) becomes normative; we publish the JSON Schema and validator script so maintainers can lint locally.
2. **Registry repository** `github.com/agentclientprotocol/registry`:
- Structure: `<id>/agent.json`, optional `icon.svg` (or `icon-light.svg` and `icon-dark.svg` for theme-specific variants), optional `README.md`.
- Icons should be SVG format for scalability. If providing theme-specific icons, both light and dark variants must be included.
- CI: validate manifests, enforce slug uniqueness, check asset sizes, generate aggregate artifacts.
- Structure: `<id>/agent.json`, optional `icon.svg`, optional `README.md`.
- CI validates manifests on every PR: schema compliance, slug uniqueness, icon format (16×16 SVG, monochrome `currentColor`), URL accessibility for all distribution URLs, authentication support via ACP handshake, and binary OS coverage.
- Push to `main` triggers a build that aggregates all entries into `registry.json` and publishes versioned + `latest` GitHub releases.
3. **Aggregated outputs**:
- `registry.json`: deterministic list of all agents with JSONC stripped.
- `registry.json`: deterministic list of all agents with icons copied to `dist/<id>.svg`.
4. **Distribution & search**:
- Clients fetch `registry.json` from a pinned release or `https://agentclientprotocol.com/registry.json` or `https://registry.agentclientprotocol.com`.
- Static site offers filters for capability, protocol version, deployment, auth model, and tags.
- Clients fetch `registry.json` from `https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json`.
- Static site offers filters for deployment model, license, and distribution type.

## Shiny future

- Agent maintainers make PRs to update their manifests; CI keeps data clean.
- Automated version updates run hourly, checking npm, PyPI, and GitHub releases for new versions of registered agents and opening PRs automatically.
- Editors/clients can bootstrap ACP support by fetching one JSON file and filtering locally.
- The ACP website displays the same data for humans, ensuring consistency.
- Protocol-version mismatches are visible immediately; clients can warn or hide incompatible agents.
- Package-based distribution (`npx`, `uvx`) lowers the barrier for agents that don't need platform-specific binaries.

## Implementation details and plan

**Phase 1 – Spec & repo bootstrap**

- Think about the auth options.
- Finalize JSON Schema and documentation.
- Ask agent developers to contribute their thoughts on the spec.
- Create registry repo with CI (GitHub Actions) that runs validation on PRs.
- Seed with a few reference agents to prove the workflow.
- Create registry repo with CI (GitHub Actions) that validates on PRs and publishes on merge.
- Seed with reference agents.
- Implement automated version update workflow (hourly cron via GitHub Actions).
- Enforce authentication requirements via CI handshake verification.

## Revision history

- 2025-11-28: Initial draft.
- 2025-12-16: Minors.
- 2026-02-04: Updated to match latest schema — removed `schema_version`, `homepage`, `capabilities`, and `auth` fields; added `icon` field; restructured `distribution` into `binary`, `npx`, and `uvx` types.