Code at the speed of thought – Zed is a high-performance, multiplayer code editor from the creators of Atom and Tree-sitter.
docs: Update agent server extension documentation (#58306)
Finn Evers3c8fc259fdd1
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.mdindex eca2ca57ae4..d673b58a65a 100644--- a/docs/src/SUMMARY.md+++ b/docs/src/SUMMARY.md@@ -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…diff --git a/docs/src/ai/external-agents.md b/docs/src/ai/external-agents.mdindex 8660cf7594f..53f5e9cee19 100644--- a/docs/src/ai/external-agents.md+++ b/docs/src/ai/external-agents.md@@ -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).diff --git a/docs/src/extensions.md b/docs/src/extensions.mdindex 9e46f4ab54e..cd57bf30c02 100644--- a/docs/src/extensions.md+++ b/docs/src/extensions.md@@ -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)diff --git a/docs/src/extensions/agent-servers.md b/docs/src/extensions/agent-servers.mdindex 23d8c888125..8c4d5af205d 100644--- a/docs/src/extensions/agent-servers.md+++ b/docs/src/extensions/agent-servers.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).