diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index eca2ca57ae..d673b58a65 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.md index 8660cf7594..53f5e9cee1 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 - -
- -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. - -
- -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.md index 9e46f4ab54..cd57bf30c0 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.md index 23d8c88812..8c4d5af205 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 -
- -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. - -
- -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).