Add ACP Agent Registry RFD #289
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 `<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). | | ||
|
Contributor
There was a problem hiding this comment. should this refer to the TOML? Thinking aloud for instructive examples.. I would like to avoid some polarizing patterns where folks in other domains start listing out a subset of contributors who recently touched something. Maybe "e.g. If GitHub, owner of the repository or if Linux Foundation, name of the most specific project." |
||
| | `license` | SPDX identifier or `"proprietary"`. | | ||
| | `capabilities` | Array of ACP method names implemented (e.g. `["terminal/new","files/read"]`). | | ||
|
Member
There was a problem hiding this comment. Should this be a string? Or just a mirror of the |
||
| | `auth` | Array of auth options for authentication. This is the trickiest part of the schema. | | ||
|
There was a problem hiding this comment. I believe that authorization should happen inside the ACP and be handled through protocol itself, as it can depend on selected model
Contributor
Author
There was a problem hiding this comment. okay, let's discuss that with @benbrandt; he has much more experience here
Contributor
There was a problem hiding this comment. I assume the value here was intentionally more like a TODO comment, as we'd not commit "trickiest part" as maybe that's too honest for a spec? ;) |
||
| | `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). | | ||
|
Member
There was a problem hiding this comment. Why optional? I assume this is largely the point?
Contributor
There was a problem hiding this comment. food for thought, but I think the distribution manifest could go in many ways.. we may not be able to assume a latest tag for things like this. I ran into this with envoy and here's an example registry where ended up needing to add a date field (though many agents update multiple times a day, envoy never) https://archive.tetratelabs.io/envoy/envoy-versions.json main concern about the download manifest part is if this digs a hole quite deep. it could be that we make a conventional manifest that is independent from the registry, then the registry assumes that packaing? just ideas. |
||
|
|
||
| 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", | ||
|
Member
There was a problem hiding this comment. SPDX allows for AND and OR already, I think this is fine as a string: https://spdx.github.io/spdx-spec/v2.3/SPDX-license-expressions/ |
||
| "capabilities": ["terminal", "fs/read", "fs/write"], | ||
| "auth": [ | ||
| { | ||
| "type": "api_key", | ||
| }, | ||
| ], | ||
| "distribution": { | ||
|
Contributor
There was a problem hiding this comment. are we expecting the cmd/args to need to vary like this? Is this meant to be used exactly? I guess this is for windows only? |
||
| "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": "", | ||
| }, | ||
|
Comment on lines
+85
to
+87
There was a problem hiding this comment. Since this is a spec, should we care about knowing if the secret is required or not? |
||
| }, | ||
| }, | ||
| } | ||
| ``` | ||
|
|
||
| ## 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. | ||
| 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. | ||
|
There was a problem hiding this comment. how do agent updates work? Agent authors upload new agent.json to repository with updated version?
Contributor
Author
There was a problem hiding this comment. yes, we have a GitHub action that builds the unified json with all agents and clients can check it once in a while |
||
| - 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. | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm curious here... if we are already doing jsonc, which will need some post-processing anyway to serve, would we be better off with something like toml or another format?
Not of a strong opinion here but it seems we have two use cases:
I can understand the argument that clients probably want to read json, but I guess I just wonder if that also necessitates that to be the authoring language, as long as we provide the tooling in the registry to convert from one to the other