docs: Update agent server extension documentation (#58306)
Updates the agent server extension documentation to account for the ACP server extension deprecation. Release Notes: - N/A --------- Co-authored-by: Ben Brandt <benjamin.j.brandt@gmail.com>
This commit is contained in:
Finn EversandBen Brandt authored and GitHub committed
1 parent
eba87556ee
commit
b44e0ea669
4 files changed
+5
-199
No files matched your search
@@ -187,7 +187,6 @@
|
||||
- [Theme Extensions](./extensions/themes.md)
|
||||
- [Icon Theme Extensions](./extensions/icon-themes.md)
|
||||
- [Snippets Extensions](./extensions/snippets.md)
|
||||
- [Agent Server Extensions](./extensions/agent-servers.md)
|
||||
- [MCP Server Extensions](./extensions/mcp-extensions.md)
|
||||
|
||||
# Coming From…
|
||||
|
||||
@@ -181,26 +181,8 @@ Codex supports the same workflows as Zed's first-party agent. Add context by @-m
|
||||
|
||||
## Add More Agents {#add-more-agents}
|
||||
|
||||
### Via Agent Server Extensions
|
||||
|
||||
<div class="warning">
|
||||
|
||||
Starting from `v0.221.x`, [the ACP Registry](https://agentclientprotocol.com/registry) is the preferred way to install external agents in Zed.
|
||||
Learn more about it in [the release blog post](https://zed.dev/blog/acp-registry).
|
||||
At some point in the near future, Agent Server extensions will be deprecated.
|
||||
|
||||
</div>
|
||||
|
||||
Add more external agents to Zed by installing [Agent Server extensions](../extensions/agent-servers.md).
|
||||
|
||||
See what agents are available by filtering for "Agent Servers" in the extensions page, which you can access via the command palette with {#action zed::Extensions}, or the [Zed website](https://zed.dev/extensions?filter=agent-servers).
|
||||
|
||||
### Via The ACP Registry
|
||||
|
||||
#### Overview
|
||||
|
||||
As mentioned above, the Agent Server extensions will be deprecated in the near future to give room to the ACP Registry.
|
||||
|
||||
[The ACP Registry](https://github.com/agentclientprotocol/registry) lets developers distribute ACP-compatible agents to any client that implements the protocol. Agents installed from the registry update automatically.
|
||||
|
||||
At the moment, the registry is a curated set of agents, including only the ones that [support authentication](https://agentclientprotocol.com/rfds/auth-methods).
|
||||
|
||||
@@ -10,10 +10,9 @@ Zed lets you add new functionality using user-defined extensions.
|
||||
- [Installing Extensions](./extensions/installing-extensions.md)
|
||||
- [Extension Capabilities](./extensions/capabilities.md)
|
||||
- [Developing Extensions](./extensions/developing-extensions.md)
|
||||
- [Developing Language Extensions](./extensions/languages.md)
|
||||
- [Developing Debugger Extensions](./extensions/debugger-extensions.md)
|
||||
- [Developing Themes](./extensions/themes.md)
|
||||
- [Developing Icon Themes](./extensions/icon-themes.md)
|
||||
- [Developing Snippets](./extensions/snippets.md)
|
||||
- [Developing Agent Servers](./extensions/agent-servers.md)
|
||||
- [Developing Language Extensions](./extensions/languages.md)
|
||||
- [Developing MCP Servers](./extensions/mcp-extensions.md)
|
||||
- [Developing Snippets](./extensions/snippets.md)
|
||||
- [Developing Themes](./extensions/themes.md)
|
||||
@@ -5,179 +5,5 @@ description: "Agent Server Extensions for Zed extensions."
|
||||
|
||||
# Agent Server Extensions
|
||||
|
||||
<div class="warning">
|
||||
|
||||
Note that starting from `v0.221`.x, [the ACP Registry](https://agentclientprotocol.com/registry) is the preferred way to install external agents in Zed.
|
||||
You can learn more about it in [the release blog post](https://zed.dev/blog/acp-registry)
|
||||
|
||||
At some point in the near future, Agent Server extensions will be deprecated.
|
||||
|
||||
</div>
|
||||
|
||||
Agent Servers are programs that provide AI agent implementations through the [Agent Client Protocol (ACP)](https://agentclientprotocol.com).
|
||||
Agent Server Extensions let you package an Agent Server so users can install the extension and use your agent in Zed.
|
||||
|
||||
You can see the current Agent Server extensions either by opening the Extensions tab in Zed (execute the {#action zed::Extensions} command) and changing the filter from `All` to `Agent Servers`, or by visiting [the Zed website](https://zed.dev/extensions?filter=agent-servers).
|
||||
|
||||
## Defining Agent Server Extensions
|
||||
|
||||
An extension can register one or more agent servers in the `extension.toml`:
|
||||
|
||||
```toml
|
||||
[agent_servers.my-agent]
|
||||
name = "My Agent"
|
||||
|
||||
[agent_servers.my-agent.targets.darwin-aarch64]
|
||||
archive = "https://github.com/owner/repo/releases/download/v1.0.0/agent-darwin-arm64.tar.gz"
|
||||
cmd = "./agent"
|
||||
args = ["--serve"]
|
||||
|
||||
[agent_servers.my-agent.targets.linux-x86_64]
|
||||
archive = "https://github.com/owner/repo/releases/download/v1.0.0/agent-linux-x64.tar.gz"
|
||||
cmd = "./agent"
|
||||
args = ["--serve"]
|
||||
|
||||
[agent_servers.my-agent.targets.windows-x86_64]
|
||||
archive = "https://github.com/owner/repo/releases/download/v1.0.0/agent-windows-x64.zip"
|
||||
cmd = "./agent.exe"
|
||||
args = ["--serve"]
|
||||
```
|
||||
|
||||
### Required Fields
|
||||
|
||||
- `name`: A human-readable display name for the agent server (shown in menus)
|
||||
- `targets`: Platform-specific configurations for downloading and running the agent
|
||||
|
||||
### Target Configuration
|
||||
|
||||
Each target key uses the format `{os}-{arch}` where:
|
||||
|
||||
- **os**: `darwin` (macOS), `linux`, or `windows`
|
||||
- **arch**: `aarch64` (ARM64) or `x86_64`
|
||||
|
||||
Each target must specify:
|
||||
|
||||
- `archive`: URL to download the archive from (supports `.tar.gz`, `.zip`, etc.)
|
||||
- `cmd`: Command to run the agent server (relative to the extracted archive)
|
||||
- `args`: Command-line arguments to pass to the agent server (optional)
|
||||
- `sha256`: SHA-256 hash string of the archive's bytes (optional, but recommended for security)
|
||||
- `env`: Environment variables specific to this target (optional, overrides agent-level env vars with the same name)
|
||||
|
||||
### Optional Fields
|
||||
|
||||
You can also optionally specify at the agent server level:
|
||||
|
||||
- `env`: Environment variables to set in the agent's spawned process. These apply to all targets by default.
|
||||
- `icon`: Path to an SVG icon (relative to extension root) for display in menus.
|
||||
|
||||
### Environment Variables
|
||||
|
||||
Environment variables can be configured at two levels:
|
||||
|
||||
1. **Agent-level** (`[agent_servers.my-agent.env]`): Variables that apply to all platforms
|
||||
2. **Target-level** (`[agent_servers.my-agent.targets.{platform}.env]`): Variables specific to a platform
|
||||
|
||||
When both are specified, target-level environment variables override agent-level variables with the same name. Variables defined only at the agent level are inherited by all targets.
|
||||
|
||||
### Complete Example
|
||||
|
||||
Here's a more complete example with all optional fields:
|
||||
|
||||
```toml
|
||||
[agent_servers.example-agent]
|
||||
name = "Example Agent"
|
||||
icon = "icon/agent.svg"
|
||||
|
||||
[agent_servers.example-agent.env]
|
||||
AGENT_LOG_LEVEL = "info"
|
||||
AGENT_MODE = "production"
|
||||
|
||||
[agent_servers.example-agent.targets.darwin-aarch64]
|
||||
archive = "https://github.com/example/agent/releases/download/v2.0.0/agent-darwin-arm64.tar.gz"
|
||||
cmd = "./bin/agent"
|
||||
args = ["serve", "--port", "8080"]
|
||||
sha256 = "abc123def456..."
|
||||
|
||||
[agent_servers.example-agent.targets.linux-x86_64]
|
||||
archive = "https://github.com/example/agent/releases/download/v2.0.0/agent-linux-x64.tar.gz"
|
||||
cmd = "./bin/agent"
|
||||
args = ["serve", "--port", "8080"]
|
||||
sha256 = "def456abc123..."
|
||||
|
||||
[agent_servers.example-agent.targets.linux-x86_64.env]
|
||||
AGENT_MEMORY_LIMIT = "2GB" # Linux-specific override
|
||||
```
|
||||
|
||||
## Installation Process
|
||||
|
||||
When a user installs your extension and selects the agent server:
|
||||
|
||||
1. Zed downloads the appropriate archive for the user's platform
|
||||
2. The archive is extracted to a cache directory
|
||||
3. Zed launches the agent using the specified command and arguments
|
||||
4. Environment variables are set as configured
|
||||
5. The agent server runs in the background, ready to assist the user
|
||||
|
||||
Archives are cached locally, so subsequent launches are fast.
|
||||
|
||||
## Distribution Best Practices
|
||||
|
||||
### Use GitHub Releases
|
||||
|
||||
GitHub Releases are a reliable way to distribute agent server binaries:
|
||||
|
||||
1. Build your agent for each platform (macOS ARM64, macOS x86_64, Linux x86_64, Windows x86_64)
|
||||
2. Package each build as a compressed archive (`.tar.gz` or `.zip`)
|
||||
3. Create a GitHub release and upload the archives
|
||||
4. Use the release URLs in your `extension.toml`
|
||||
|
||||
## SHA-256 Hashes
|
||||
|
||||
For better supply-chain security, include SHA-256 hashes of your archives in `extension.toml`. Here's how to generate one:
|
||||
|
||||
### macOS and Linux
|
||||
|
||||
```bash
|
||||
shasum -a 256 agent-darwin-arm64.tar.gz
|
||||
```
|
||||
|
||||
### Windows
|
||||
|
||||
```bash
|
||||
certutil -hashfile agent-windows-x64.zip SHA256
|
||||
```
|
||||
|
||||
Then add that string to your target configuration:
|
||||
|
||||
```toml
|
||||
[agent_servers.my-agent.targets.darwin-aarch64]
|
||||
archive = "https://github.com/owner/repo/releases/download/v1.0.0/agent-darwin-arm64.tar.gz"
|
||||
cmd = "./agent"
|
||||
sha256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
To test your Agent Server Extension:
|
||||
|
||||
1. [Install it as a dev extension](./developing-extensions.md#developing-an-extension-locally)
|
||||
2. Open the [Agent Panel](../ai/agent-panel.md)
|
||||
3. Select your Agent Server from the list
|
||||
4. Verify that it downloads, installs, and launches correctly
|
||||
5. Test its functionality by conversing with it and watching the [ACP logs](../ai/external-agents.md#debugging-agents)
|
||||
|
||||
## Icon Guideline
|
||||
|
||||
If your agent server has a logo, add it as an SVG icon.
|
||||
For consistent rendering, follow these guidelines:
|
||||
|
||||
- Resize your SVG to fit a 16x16 bounding box with around one or two pixels of padding
|
||||
- Keep the SVG markup clean by processing it through [SVGOMG](https://jakearchibald.github.io/svgomg/)
|
||||
- Avoid gradients, which often increase SVG complexity and can render inconsistently
|
||||
|
||||
Note that we'll automatically convert your icon to monochrome to preserve Zed's design consistency.
|
||||
(You can still use opacity in different paths of your SVG to add visual layering.)
|
||||
|
||||
## Publishing
|
||||
|
||||
Once your extension is ready, see [Publishing your extension](./developing-extensions.md#publishing-your-extension) to learn how to submit it to the Zed extension registry.
|
||||
As of Zed `v1.5.0`, ACP extensions have been deprecated in favor of [the ACP Registry](https://agentclientprotocol.com/registry).
|
||||
You can learn more about it in [the release blog post](https://zed.dev/blog/acp-registry).
|
||||
Reference in new issue
Block a user