Add agent-servers.md (#41609)
Release Notes: - N/A --------- Co-authored-by: Danilo Leal <67129314+danilo-leal@users.noreply.github.com>
This commit is contained in:
Richard Feldman
co-authored by
Danilo Leal
Danilo Leal
parent
714481073d
commit
622d626a29
@@ -80,6 +80,7 @@
|
||||
- [Theme Extensions](./extensions/themes.md)
|
||||
- [Icon Theme Extensions](./extensions/icon-themes.md)
|
||||
- [Slash Command Extensions](./extensions/slash-commands.md)
|
||||
- [Agent Server Extensions](./extensions/agent-servers.md)
|
||||
- [MCP Server Extensions](./extensions/mcp-extensions.md)
|
||||
|
||||
# Language Support
|
||||
|
||||
@@ -9,4 +9,5 @@ Zed lets you add new functionality using user-defined extensions.
|
||||
- [Developing Themes](./extensions/themes.md)
|
||||
- [Developing Icon Themes](./extensions/icon-themes.md)
|
||||
- [Developing Slash Commands](./extensions/slash-commands.md)
|
||||
- [Developing Agent Servers](./extensions/agent-servers.md)
|
||||
- [Developing MCP Servers](./extensions/mcp-extensions.md)
|
||||
|
||||
@@ -0,0 +1,156 @@
|
||||
# Agent Server Extensions
|
||||
|
||||
Agent Servers are programs that provide AI agent implementations through the [Agent Client Protocol (ACP)](https://agentclientprotocol.com). Agent Server Extensions let you package up an Agent Server so that users can install the extension and have your agent easily available to use in Zed.
|
||||
|
||||
You can see the current Agent Server Extensions either by opening the Extensions tab in Zed (execute the `zed: extensions` command) and changing the filter from `All` to `Agent Servers`, or by visiting [https://zed.dev/extensions?filter=agent-servers](https://zed.dev/extensions?filter=agent-servers).
|
||||
|
||||
## Defining Agent Server Extensions
|
||||
|
||||
An extension can register one or more agent servers in the `extension.toml` like so:
|
||||
|
||||
```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)
|
||||
|
||||
### Optional Fields
|
||||
|
||||
You can also optionally specify:
|
||||
|
||||
- `sha256`: SHA-256 hash string of the archive's bytes. Zed will check this after the archive is downloaded and give an error if it doesn't match, so doing this improves security.
|
||||
- `env`: Environment variables to set in the agent's spawned process.
|
||||
- `icon`: Path to an SVG icon (relative to extension root) for display in menus.
|
||||
|
||||
### 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..."
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
It's good for security to include SHA-256 hashes of your archives in `extension.toml`. Here's how to generate it:
|
||||
|
||||
### 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
|
||||
|
||||
In case your agent server has a logo, we highly recommend adding it as an SVG icon.
|
||||
For optimal display, follow these guidelines:
|
||||
|
||||
- Make sure you resize your SVG to fit a 16x16 bounding box, with a padding of around one or two pixels
|
||||
- Ensure you have a clean SVG code by processing it through [SVGOMG](https://jakearchibald.github.io/svgomg/)
|
||||
- Avoid including icons with gradients as they will often make the SVG more complicated and possibly not render perfectly
|
||||
|
||||
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.)
|
||||
|
||||
This is all you need to distribute an agent server through Zed's extension system!
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user