Add ACP Agent Registry RFD #289
Conversation
ignatov
commented
Nov 28, 2025
ignatov
commented
- 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
- 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
| "env": { | ||
| "SOMEAGENT_MODE_KEY": "", | ||
| }, |
There was a problem hiding this comment.
Since this is a spec, should we care about knowing if the secret is required or not?
| "homepage": "https://github.com/example/someagent", | ||
| "repository": "https://github.com/example/someagent", | ||
| "authors": ["Example Team"], | ||
| "license": "MIT", |
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/
|
|
||
| ## 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): |
There was a problem hiding this comment.
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:
- authoring
- consuming in a client
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
| "homepage": "https://github.com/example/someagent", | ||
| "repository": "https://github.com/example/someagent", | ||
| "authors": ["Example Team"], | ||
| "license": "MIT", |
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/
| | `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"]`). | |
There was a problem hiding this comment.
Should this be a string? Or just a mirror of the agentCapabilities type?
| | `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 `<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). | |
There was a problem hiding this comment.
Why optional? I assume this is largely the point?
Though maybe we offer a way to discriminate between different distribution types in the future?
|
|
||
| ## 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?
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
| | `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. | |
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
There was a problem hiding this comment.
okay, let's discuss that with @benbrandt; he has much more experience here
codefromthecrypt
left a comment
codefromthecrypt
left a comment
There was a problem hiding this comment.
some comments don't feel they need to be addressed
| | `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). | |
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."
| | `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. | |
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? ;)
| "type": "api_key", | ||
| }, | ||
| ], | ||
| "distribution": { |
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?
| | `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 `<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). | |
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.
|
@ignatov looking more at the MCP registry, they seem to allow for multiple distribution methods, such as npm, github release, docker, etc We could still potentially put some cache in front if we want, but I think from an authoring perspective it could be nice to use some similar options? |
