Skip to content

Commit 6e7ce05

Browse files
benbrandtbenbrandt
authored
docs(rfd): Move registry RFD to preview (#455)
* docs(rfd): Move registry RFD to preview Updates the rfd to match the current implementation. * Remove mention of extensions for now
1 parent 610848f commit 6e7ce05

2 files changed

Lines changed: 146 additions & 66 deletions

File tree

‎docs/docs.json‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -116,14 +116,13 @@
116116
"rfds/proxy-chains",
117117
"rfds/mcp-over-acp",
118118
"rfds/session-usage",
119-
"rfds/acp-agent-registry",
120119
"rfds/auth-methods",
121120
"rfds/rust-sdk-v1",
122121
"rfds/logout-method",
123122
"rfds/session-delete"
124123
]
125124
},
126-
{ "group": "Preview", "pages": [] },
125+
{ "group": "Preview", "pages": ["rfds/acp-agent-registry"] },
127126
{
128127
"group": "Completed",
129128
"pages": [

‎docs/rfds/acp-agent-registry.mdx‎

Lines changed: 145 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -15,112 +15,193 @@ There is no canonical listing of ACP-compatible agents. Information lives in sca
1515

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

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

2222
## Agent manifest format (core proposal)
2323

24-
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):
25-
26-
| Field | Description |
27-
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
28-
| `id` | Lowercase slug, unique across registry (also the folder name). |
29-
| `name` | Human-readable label. |
30-
| `version` | Agent release version surfaced to users. |
31-
| `schema_version` | Semver of the manifest schema. Allows future breaking changes. |
32-
| `description` | Description of the agent's functionality and purpose. |
33-
| `homepage` | URL for docs/marketing. |
34-
| `repository` | Source repository URL. |
35-
| `authors` | Array of author/organization names (mirrors `authors` in the TOML example). |
36-
| `license` | Licence (string). |
37-
| `capabilities` | Array of ACP method names implemented (e.g. `["terminal/new","files/read"]`). |
38-
| `auth` | Array of auth options for authentication. This is the trickiest part of the schema. |
39-
| `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). |
40-
41-
Example skeleton:
24+
Each agent advertises itself via a manifest stored as `<id>/agent.json` in the registry repo.
25+
26+
Fields marked with **\*** are required:
27+
28+
| Field | Description |
29+
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
30+
| `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. |
31+
| `name` **\*** | Human-readable display name. |
32+
| `version` **\*** | Semantic version of the agent release (e.g. `1.0.0`). |
33+
| `description` **\*** | Brief description of the agent's functionality and purpose. |
34+
| `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. |
35+
| `repository` | Source code repository URL. |
36+
| `authors` | Array of author/organization names. |
37+
| `license` | SPDX license identifier or `"proprietary"`. |
38+
| `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). |
39+
40+
### Distribution
41+
42+
The `distribution` object supports three mutually independent strategies. An agent may provide one or more:
43+
44+
#### `binary`
45+
46+
Platform-specific archive downloads. Keyed by `<os>-<arch>` targets:
47+
48+
| Target | OS | Architecture |
49+
| ----------------- | ------- | ------------ |
50+
| `darwin-aarch64` | macOS | ARM64 |
51+
| `darwin-x86_64` | macOS | x86-64 |
52+
| `linux-aarch64` | Linux | ARM64 |
53+
| `linux-x86_64` | Linux | x86-64 |
54+
| `windows-aarch64` | Windows | ARM64 |
55+
| `windows-x86_64` | Windows | x86-64 |
56+
57+
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.
58+
59+
Each target is an object with:
60+
61+
| Field | Required | Description |
62+
| --------- | -------- | ----------------------------------- |
63+
| `archive` | Yes | URL to download archive |
64+
| `cmd` | Yes | Command to execute after extraction |
65+
| `args` | No | Array of command-line arguments |
66+
| `env` | No | Object of environment variables |
67+
68+
#### `npx` / `uvx`
69+
70+
Package-manager-based distribution (Node via `npx`, Python via `uvx`). Each is an object with:
71+
72+
| Field | Required | Description |
73+
| --------- | -------- | ----------------------------------------- |
74+
| `package` | Yes | Package name (with optional version spec) |
75+
| `args` | No | Array of command-line arguments |
76+
| `env` | No | Object of environment variables |
77+
78+
### Icon requirements
79+
80+
Icons must meet the following requirements to pass CI validation:
81+
82+
- **SVG format** — only `.svg` files are accepted.
83+
- **16×16 dimensions** — via `width`/`height` attributes or `viewBox`.
84+
- **Monochrome using `currentColor`** — all `fill` and `stroke` values must use `currentColor` or `none`. Hardcoded colors (e.g. `fill="#FF5500"`, `fill="red"`) are rejected.
85+
86+
Using `currentColor` lets icons adapt automatically to the client's light or dark theme.
87+
88+
### Example: binary distribution
4289

4390
```jsonc
4491
{
4592
"id": "someagent",
4693
"name": "SomeAgent",
4794
"version": "1.0.0",
48-
"schema_version": "1",
4995
"description": "Agent for code editing",
50-
"homepage": "https://github.com/example/someagent",
5196
"repository": "https://github.com/example/someagent",
5297
"authors": ["Example Team"],
5398
"license": "MIT",
54-
"capabilities": ["terminal", "fs/read", "fs/write"],
55-
"auth": [
56-
{
57-
"type": "api_key",
58-
},
59-
],
99+
"icon": "icon.svg",
60100
"distribution": {
61-
"darwin-aarch64": {
62-
"archive": "https://github.com/example/someagent/releases/latest/download/someagent-darwin-arm64.zip",
63-
"cmd": "./someagent",
64-
"args": ["acp"],
65-
},
66-
"darwin-x86_64": {
67-
"archive": "https://github.com/example/someagent/releases/latest/download/someagent-darwin-x64.zip",
68-
"cmd": "./someagent",
69-
"args": ["acp"],
70-
},
71-
"linux-aarch64": {
72-
"archive": "https://github.com/example/someagent/releases/latest/download/someagent-linux-arm64.zip",
73-
"cmd": "./someagent",
74-
"args": ["acp"],
75-
},
76-
"linux-x86_64": {
77-
"archive": "https://github.com/example/someagent/releases/latest/download/someagent-linux-x64.zip",
78-
"cmd": "./someagent",
79-
"args": ["acp"],
80-
},
81-
"windows-x86_64": {
82-
"archive": "https://github.com/example/someagent/releases/latest/download/someagent-windows-x64.zip",
83-
"cmd": "./someagent.exe",
84-
"args": ["acp"],
85-
"env": {
86-
"SOMEAGENT_MODE_KEY": "",
101+
"binary": {
102+
"darwin-aarch64": {
103+
"archive": "https://github.com/example/someagent/releases/latest/download/someagent-darwin-arm64.zip",
104+
"cmd": "./someagent",
105+
"args": ["acp"],
106+
},
107+
"darwin-x86_64": {
108+
"archive": "https://github.com/example/someagent/releases/latest/download/someagent-darwin-x64.zip",
109+
"cmd": "./someagent",
110+
"args": ["acp"],
111+
},
112+
"linux-aarch64": {
113+
"archive": "https://github.com/example/someagent/releases/latest/download/someagent-linux-arm64.zip",
114+
"cmd": "./someagent",
115+
"args": ["acp"],
116+
},
117+
"linux-x86_64": {
118+
"archive": "https://github.com/example/someagent/releases/latest/download/someagent-linux-x64.zip",
119+
"cmd": "./someagent",
120+
"args": ["acp"],
121+
},
122+
"windows-x86_64": {
123+
"archive": "https://github.com/example/someagent/releases/latest/download/someagent-windows-x64.zip",
124+
"cmd": "./someagent.exe",
125+
"args": ["acp"],
126+
"env": {
127+
"SOMEAGENT_MODE_KEY": "",
128+
},
87129
},
88130
},
89131
},
90132
}
91133
```
92134

135+
### Example: package distribution
136+
137+
```jsonc
138+
{
139+
"id": "pyagent",
140+
"name": "PyAgent",
141+
"version": "2.1.0",
142+
"description": "A Python-based ACP agent",
143+
"repository": "https://github.com/example/pyagent",
144+
"license": "Apache-2.0",
145+
"distribution": {
146+
"uvx": {
147+
"package": "pyagent@latest",
148+
"args": ["--mode", "acp"],
149+
},
150+
},
151+
}
152+
```
153+
154+
## Registry schema
155+
156+
The aggregated `registry.json` file conforms to the registry schema and contains:
157+
158+
| Field | Description |
159+
| --------- | --------------------------------------------------------------------------------------------------------- |
160+
| `version` | Registry schema version (semver, e.g. `1.0.0`). |
161+
| `agents` | Array of agent entries (each following the agent manifest schema above, sourced from `agent.json` files). |
162+
163+
## Authentication requirements
164+
165+
To be listed in the registry, an agent **must support at least one** of the following authentication methods:
166+
167+
- **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).
168+
- **Terminal Auth** — the agent provides an interactive terminal-based setup experience (launched with additional args/env specified in the auth method).
169+
170+
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.
171+
93172
## What we propose to do about it
94173

95174
1. **Manifest spec** (above) becomes normative; we publish the JSON Schema and validator script so maintainers can lint locally.
96175
2. **Registry repository** `github.com/agentclientprotocol/registry`:
97-
- Structure: `<id>/agent.json`, optional `icon.svg` (or `icon-light.svg` and `icon-dark.svg` for theme-specific variants), optional `README.md`.
98-
- Icons should be SVG format for scalability. If providing theme-specific icons, both light and dark variants must be included.
99-
- CI: validate manifests, enforce slug uniqueness, check asset sizes, generate aggregate artifacts.
176+
- Structure: `<id>/agent.json`, optional `icon.svg`, optional `README.md`.
177+
- 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.
178+
- Push to `main` triggers a build that aggregates all entries into `registry.json` and publishes versioned + `latest` GitHub releases.
100179
3. **Aggregated outputs**:
101-
- `registry.json`: deterministic list of all agents with JSONC stripped.
180+
- `registry.json`: deterministic list of all agents with icons copied to `dist/<id>.svg`.
102181
4. **Distribution & search**:
103-
- Clients fetch `registry.json` from a pinned release or `https://agentclientprotocol.com/registry.json` or `https://registry.agentclientprotocol.com`.
104-
- Static site offers filters for capability, protocol version, deployment, auth model, and tags.
182+
- Clients fetch `registry.json` from `https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json`.
183+
- Static site offers filters for deployment model, license, and distribution type.
105184

106185
## Shiny future
107186

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

113193
## Implementation details and plan
114194

115195
**Phase 1 – Spec & repo bootstrap**
116196

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

123203
## Revision history
124204

125205
- 2025-11-28: Initial draft.
126206
- 2025-12-16: Minors.
207+
- 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.

0 commit comments

Comments
 (0)