@@ -1,11 +1,11 @@
# External Agents
-Zed supports terminal-based agents through the [Agent Client Protocol (ACP)](https://agentclientprotocol.com).
+Zed supports many external agents, including CLI-based ones, through the [Agent Client Protocol (ACP)](https://agentclientprotocol.com).
Currently, [Gemini CLI](https://github.com/google-gemini/gemini-cli) serves as the reference implementation.
-[Claude Code](https://www.anthropic.com/claude-code) and [Codex](https://developers.openai.com/codex) are also included by default, and you can [add custom ACP-compatible agents](#add-more-agents) as well.
+[Claude Code](https://www.anthropic.com/claude-code) and [Codex](https://developers.openai.com/codex) are also included by default, and you can [add more custom ACP-compatible agents](#add-more-agents) as well.
-> Note that Zed's affordance for external agents is strictly UI-based; the billing and legal/terms arrangement is directly between you and the agent provider.
+> Note that Zed's interaction with external agents is strictly UI-based; the billing, legal, and terms arrangement is directly between you and the agent provider.
> Zed does not charge for use of external agents, and our [zero-data retention agreements/privacy guarantees](./ai-improvement.md) are **_only_** applicable for Zed's hosted models.
## Gemini CLI {#gemini-cli}
@@ -51,9 +51,11 @@ By default, Zed will use this managed version of Gemini CLI even if you have it
After you have Gemini CLI running, you'll be prompted to choose your authentication method.
-Most users should click the "Log in with Google". This will cause a browser window to pop-up and auth directly with Gemini CLI. Zed does not see your OAuth or access tokens in this case.
+Most users should click the "Log in with Google".
+This will cause a browser window to pop-up and auth directly with Gemini CLI. Zed does not see your OAuth or access tokens in this case.
-You can also use the "Gemini API Key". If you select this, and have the `GEMINI_API_KEY` set, then we will use that. Otherwise Zed will prompt you for an API key which will be stored securely in your keychain, and used to start Gemini CLI from within Zed.
+You can also use the "Gemini API Key". If you select this, and have the `GEMINI_API_KEY` set, then we will use that.
+Otherwise Zed will prompt you for an API key which will be stored securely in your keychain, and used to start Gemini CLI from within Zed.
The "Vertex AI" option is for those who are using [Vertex AI](https://cloud.google.com/vertex-ai), and have already configured their environment correctly.
@@ -90,13 +92,16 @@ If you'd like to bind this to a keyboard shortcut, you can do so by editing your
### Authentication
-As of version `0.202.7` (stable) and `0.203.2` (preview), authentication to Zed's Claude Code installation is decoupled entirely from Zed's agent. That is to say, an Anthropic API key added via the [Zed Agent's settings](./llm-providers.md#anthropic) will _not_ be utilized by Claude Code for authentication and billing.
+As of version `0.202.7` (stable) and `0.203.2` (preview), authentication to Zed's Claude Code installation is decoupled entirely from Zed's agent.
+That is to say, an Anthropic API key added via the [Zed Agent's settings](./llm-providers.md#anthropic) will _not_ be utilized by Claude Code for authentication and billing.
-To ensure you're using your billing method of choice, [open a new Claude Code thread](./agent-panel.md#new-thread). Then, run `/login`, and authenticate either via API key, or via `Log in with Claude Code` to use a Claude Pro/Max subscription.
+To ensure you're using your billing method of choice, [open a new Claude Code thread](./agent-panel.md#new-thread).
+Then, run `/login`, and authenticate either via API key, or via `Log in with Claude Code` to use a Claude Pro/Max subscription.
#### Installation
-The first time you create a Claude Code thread, Zed will install [@zed-industries/claude-code-acp](https://github.com/zed-industries/claude-code-acp). This installation is only available to Zed and is kept up to date as you use the agent.
+The first time you create a Claude Code thread, Zed will install [@zed-industries/claude-code-acp](https://github.com/zed-industries/claude-code-acp).
+This installation is only available to Zed and is kept up to date as you use the agent.
Zed will always use this managed version of the Claude Code adapter, which includes a vendored version of the Claude Code CLI, even if you have it installed globally.
@@ -142,7 +147,8 @@ Under the hood, Zed runs Codex CLI and communicates to it over ACP, through [a d
### Getting Started
-As of Zed Stable v0.208 you should be able to use Codex directly from Zed. Open the agent panel with {#kb agent::ToggleFocus}, and then use the `+` button in the top right to start a new Codex thread.
+As of Zed Stable v0.208 you should be able to use Codex directly from Zed.
+Open the agent panel with {#kb agent::ToggleFocus}, and then use the `+` button in the top right to start a new Codex thread.
If you'd like to bind this to a keyboard shortcut, you can do so by editing your `keymap.json` file via the `zed: open keymap` command to include:
@@ -158,9 +164,11 @@ If you'd like to bind this to a keyboard shortcut, you can do so by editing your
### Authentication
-Authentication to Zed's Codex installation is decoupled entirely from Zed's agent. That is to say, an OpenAI API key added via the [Zed Agent's settings](./llm-providers.md#openai) will _not_ be utilized by Codex for authentication and billing.
+Authentication to Zed's Codex installation is decoupled entirely from Zed's agent.
+That is to say, an OpenAI API key added via the [Zed Agent's settings](./llm-providers.md#openai) will _not_ be utilized by Codex for authentication and billing.
-To ensure you're using your billing method of choice, [open a new Codex thread](./agent-panel.md#new-thread). The first time you will be prompted to authenticate with one of three methods:
+To ensure you're using your billing method of choice, [open a new Codex thread](./agent-panel.md#new-thread).
+The first time you will be prompted to authenticate with one of three methods:
1. Login with ChatGPT - allows you to use your existing, paid ChatGPT subscription. _Note: This method isn't currently supported in remote projects_
2. `CODEX_API_KEY` - uses an API key you have set in your environment under the variable `CODEX_API_KEY`.
@@ -172,7 +180,8 @@ If you want to use a third-party provider with Codex, you can configure that wit
#### Installation
-The first time you create a Codex thread, Zed will install [codex-acp](https://github.com/zed-industries/codex-acp). This installation is only available to Zed and is kept up to date as you use the agent.
+The first time you create a Codex thread, Zed will install [codex-acp](https://github.com/zed-industries/codex-acp).
+This installation is only available to Zed and is kept up to date as you use the agent.
Zed will always use this managed version of Codex even if you have it installed globally.
@@ -186,10 +195,42 @@ And to give it context, you can @-mention files, symbols, or fetch the web.
## Add More Agents {#add-more-agents}
+### Via 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.
+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 should 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 `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 should be deprecated in the near future to give room to the ACP Registry.
+
+[The ACP Registry](https://github.com/agentclientprotocol/registry) is an easy way for developers to distribute their ACP-compatible agents to any client that speaks the protocol.
+And for clients, it's the easiest way to get the latest version of the agent.
+
+At the moment, the registry is a curated set of agents, including only the ones that [support authentication](https://agentclientprotocol.com/rfds/auth-methods).
+
+#### Using it in Zed
+
+Use the `zed: acp registry` command to quickly go to the ACP Registry page.
+There's also a button ("Add Agent") that takes you there in the Agent Pane's configuration view.
+
+From there, you can just install agents from the registry and use them right away in Zed's Agent Panel.
+
+If you installed the same agent through both the extension and the registry, the registry version takes precedence.
+
+### Custom Agents
+
You can also add agents through your `settings.json`, by specifying certain fields under `agent_servers`, like so:
```json [settings]
@@ -209,37 +250,10 @@ This can be useful if you're in the middle of developing a new agent that speaks
It's also possible to specify a custom path, arguments, or environment for the builtin integrations by using the `claude` and `gemini` names.
-### Custom Keybinding For Extension-Based Agents
-
-To assign a custom keybinding to start a new thread for agents that were added by installing agent server extensions, add the following snippet to your `keymap.json` file:
-
-```json [keymap]
-{
- "bindings": {
- "cmd-alt-n": [ // Your custom keybinding
- "agent::NewExternalAgentThread",
- {
- "agent": {
- "custom": {
- "name": "My Agent", // The agent name as defined in the extension or in settings.json (e.g., "opencode", "Auggie CLI", etc.)
- "command": {
- "command": "my-agent", // The agent name in lowercase with no spaces
- "args": ["acp"]
- }
- }
- }
- }
- ]
- }
-},
-```
-
-> For most extensions, the `agent.custom.name` attribute matches the name of the agent that appears in the [Agent Panel](../ai/agent-panel.md) UI.
-> In some cases however, the name might need to be written differently (e.g. in lowercase).
-
## Debugging Agents
-When using external agents in Zed, you can access the debug view via with `dev: open acp logs` from the Command Palette. This lets you see the messages being sent and received between Zed and the agent.
+When using external agents in Zed, you can access the debug view via with `dev: open acp logs` from the Command Palette.
+This lets you see the messages being sent and received between Zed and the agent.
