Skip to content

Commit f4b60fb

Browse files
ignatovbenbrandt
ignatov
authored and
benbrandt
committed
Add ACP Agent Registry RFD
- Define canonical manifest format (agent.json) for ACP agents - Specify registry structure with <id>/ folders - Add distribution section for binary targets across platforms - Include icon support for light/dark themes - Outline implementation phases and aggregation tooling
1 parent 424d05f commit f4b60fb

File tree

1 file changed

+125
-0
lines changed

1 file changed

+125
-0
lines changed

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

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
---
2+
title: "ACP Agent Registry"
3+
---
4+
5+
**Author:** [@ignatov](https://github.com/ignatov)
6+
**Champion:** [@benbrandt](https://github.com/benbrandt)
7+
8+
## Elevator pitch
9+
10+
ACP needs a single, trusted registry of agents so clients can discover integrations, understand their capabilities, and configure them automatically. This RFD proposes (1) a canonical manifest format that every agent must publish, (2) a dedicated `agentclientprotocol/registry` repo where maintainers contribute those manifests, and (3) tooling that aggregates and publishes a searchable catalog for editors and other clients.
11+
12+
## Status quo
13+
14+
There is no canonical listing of ACP-compatible agents. Information lives in scattered READMEs or proprietary feeds, which makes it hard to:
15+
16+
- Let users discover agents directly inside ACP-aware clients.
17+
- Ensure protocol-version compatibility or capability coverage.
18+
- Keep metadata consistent (auth requirements, hosting model, license, etc.).
19+
20+
Every editor builds bespoke manifests or scrapes GitHub, leading to duplication and stale data.
21+
22+
## Agent manifest format (core proposal)
23+
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` | SPDX identifier or `"proprietary"`. |
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` | _Optional._ 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:
42+
43+
```jsonc
44+
{
45+
"id": "someagent",
46+
"name": "SomeAgent",
47+
"version": "1.0.0",
48+
"schema_version": "1",
49+
"description": "Agent for code editing",
50+
"homepage": "https://github.com/example/someagent",
51+
"repository": "https://github.com/example/someagent",
52+
"authors": ["Example Team"],
53+
"license": "MIT",
54+
"capabilities": ["terminal", "fs/read", "fs/write"],
55+
"auth": [
56+
{
57+
"type": "api_key",
58+
},
59+
],
60+
"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": "",
87+
},
88+
},
89+
},
90+
}
91+
```
92+
93+
## What we propose to do about it
94+
95+
1. **Manifest spec** (above) becomes normative; we publish the JSON Schema and validator script so maintainers can lint locally.
96+
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.
100+
3. **Aggregated outputs**:
101+
- `registry.json`: deterministic list of all agents with JSONC stripped.
102+
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.
105+
106+
## Shiny future
107+
108+
- Agent maintainers make PRs to update their manifests; CI keeps data clean.
109+
- Editors/clients can bootstrap ACP support by fetching one JSON file and filtering locally.
110+
- 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.
112+
113+
## Implementation details and plan
114+
115+
**Phase 1 – Spec & repo bootstrap**
116+
117+
- Think about the auth options.
118+
- 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.
122+
123+
## Revision history
124+
125+
- 2025-01-XX: Initial draft.

0 commit comments

Comments
 (0)