From f4b60fb4fbd16b7e3197c074a39d67001ea4004e Mon Sep 17 00:00:00 2001 From: Sergey Ignatov Date: Fri, 28 Nov 2025 18:05:39 +0100 Subject: [PATCH 1/4] Add ACP Agent Registry RFD - Define canonical manifest format (agent.json) for ACP agents - Specify registry structure with / folders - Add distribution section for binary targets across platforms - Include icon support for light/dark themes - Outline implementation phases and aggregation tooling --- docs/rfds/acp-agent-registry.mdx | 125 +++++++++++++++++++++++++++++++ 1 file changed, 125 insertions(+) create mode 100644 docs/rfds/acp-agent-registry.mdx diff --git a/docs/rfds/acp-agent-registry.mdx b/docs/rfds/acp-agent-registry.mdx new file mode 100644 index 00000000..e160688a --- /dev/null +++ b/docs/rfds/acp-agent-registry.mdx @@ -0,0 +1,125 @@ +--- +title: "ACP Agent Registry" +--- + +**Author:** [@ignatov](https://github.com/ignatov) +**Champion:** [@benbrandt](https://github.com/benbrandt) + +## Elevator pitch + +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. + +## Status quo + +There is no canonical listing of ACP-compatible agents. Information lives in scattered READMEs or proprietary feeds, which makes it hard to: + +- 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.). + +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 `/` 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` | SPDX identifier or `"proprietary"`. | +| `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` | _Optional._ Object mapping target platforms to download/execution info. Each target key follows `-` 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: + +```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", + }, + ], + "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": "", + }, + }, + }, +} +``` + +## 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: `/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. +3. **Aggregated outputs**: + - `registry.json`: deterministic list of all agents with JSONC stripped. +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. + +## Shiny future + +- Agent maintainers make PRs to update their manifests; CI keeps data clean. +- 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. + +## 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. + +## Revision history + +- 2025-01-XX: Initial draft. From 8df192a611490d5963375a2939427fd8ca3c2fa7 Mon Sep 17 00:00:00 2001 From: Sergey Ignatov Date: Tue, 16 Dec 2025 09:20:08 +0100 Subject: [PATCH 2/4] docs(rfd): minor updates to agent registry spec --- docs/rfds/acp-agent-registry.mdx | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/rfds/acp-agent-registry.mdx b/docs/rfds/acp-agent-registry.mdx index e160688a..661e81ad 100644 --- a/docs/rfds/acp-agent-registry.mdx +++ b/docs/rfds/acp-agent-registry.mdx @@ -33,10 +33,10 @@ Each agent advertises itself via `agent.json` stored under `/` in the regist | `homepage` | URL for docs/marketing. | | `repository` | Source repository URL. | | `authors` | Array of author/organization names (mirrors `authors` in the TOML example). | -| `license` | SPDX identifier or `"proprietary"`. | +| `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` | _Optional._ Object mapping target platforms to download/execution info. Each target key follows `-` 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). | +| `distribution` | Object mapping target platforms to download/execution info. Each target key follows `-` 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: @@ -122,4 +122,5 @@ Example skeleton: ## Revision history -- 2025-01-XX: Initial draft. +- 2025-11-28: Initial draft. +- 2025-12-16: Minors. From 2967aa30143eee024dbf7f42f54ec4b45cb236be Mon Sep 17 00:00:00 2001 From: Ben Brandt Date: Thu, 1 Jan 2026 21:34:16 +0100 Subject: [PATCH 3/4] format --- docs/rfds/acp-agent-registry.mdx | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/rfds/acp-agent-registry.mdx b/docs/rfds/acp-agent-registry.mdx index 661e81ad..c24c1d27 100644 --- a/docs/rfds/acp-agent-registry.mdx +++ b/docs/rfds/acp-agent-registry.mdx @@ -23,19 +23,19 @@ Every editor builds bespoke manifests or scrapes GitHub, leading to duplication Each agent advertises itself via `agent.json` stored under `/` 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. | +| 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 `-` 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: From 1dc9580df511833bb2af86a44c90b2ff6ab64a96 Mon Sep 17 00:00:00 2001 From: Ben Brandt Date: Thu, 1 Jan 2026 21:35:35 +0100 Subject: [PATCH 4/4] Update website --- docs/docs.json | 3 ++- docs/updates.mdx | 7 +++++++ 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/docs.json b/docs/docs.json index fed989d1..5e17da60 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -113,7 +113,8 @@ "rfds/session-info-update", "rfds/agent-telemetry-export", "rfds/proxy-chains", - "rfds/session-usage" + "rfds/session-usage", + "rfds/acp-agent-registry" ] }, { "group": "Preview", "pages": [] }, diff --git a/docs/updates.mdx b/docs/updates.mdx index 4e038af8..c2e28423 100644 --- a/docs/updates.mdx +++ b/docs/updates.mdx @@ -4,6 +4,13 @@ description: Updates and announcements about the Agent Client Protocol rss: true --- + +## Agent Registry RFD moves to Draft stage + +The RFD for creating an Agent Registry has been moved to Draft stage. Please review the [RFD](./rfds/acp-agent-registry) for more information on the current proposal and provide feedback as work on the implementation begins. + + + ## Session Usage RFD moves to Draft stage