Riff on the external agents page

Co-authored-by: Antonio Scandurra <me@as-cii.com>
Co-authored-by: Bennet Bo Fenner <bennetbo@gmx.de>

docs/src/SUMMARY.md

@@ -47,6 +47,7 @@
 - [Overview](./ai/overview.md)
 - [Agent Panel](./ai/agent-panel.md)
   - [Tools](./ai/tools.md)
+  - [External Agents](./ai/external-agents.md)
 - [Inline Assistant](./ai/inline-assistant.md)
 - [Edit Prediction](./ai/edit-prediction.md)
 - [Text Threads](./ai/text-threads.md)

docs/src/ai/agent-panel.md

@@ -1,14 +1,15 @@
 # Agent Panel
 
-The Agent Panel provides you with a surface to interact with LLMs, enabling various types of tasks, such as generating code, asking questions about your codebase, and general inquiries like emails, documentation, and more.
+The Agent Panel allows you to interact with many LLMs and coding agents that can support you in various types of tasks, such as generating code, codebase understanding, and other general inquiries like writing emails, documentation, and more.
 
 To open it, use the `agent: new thread` action in [the Command Palette](../getting-started.md#command-palette) or click the ✨ (sparkles) icon in the status bar.
 
-If you're using the Agent Panel for the first time, you need to have at least one LLM provider configured.
+If you're using the Agent Panel for the first time, you need to have at least one LLM or agent provider configured.
 You can do that by:
 
 1. [subscribing to our Pro plan](https://zed.dev/pricing), so you have access to our hosted models
-2. or by [bringing your own API keys](./llm-providers.md#use-your-own-keys) for your desired provider
+2. [bringing your own API keys](./llm-providers.md#use-your-own-keys) for your desired provider
+3. using an external agent like [Gemini CLI](./external-agents.md#gemini-cli)
 
 ## Overview {#overview}
 
@@ -17,6 +18,17 @@ If you need extra room to type, you can expand the message editor with {#kb agen
 
 You should start to see the responses stream in with indications of [which tools](./tools.md) the model is using to fulfill your prompt.
 
+> Note that, currently, not all features outlined below work for external agents, like Gemini CLI.
+> Features like _checkpoints_, _token usage display_, and _model selection_ may be supported in the future for them.
+
+### Creating New Threads
+
+The default view for the Agent Panel uses Zed's first-party agent.
+Every time that you hit {#kb agent::NewThread}, it creates a new thread using the currently selected agent.
+
+To change that, go to the plus button in the top-right of the Agent Panel and choose another option.
+You choose to create a new [Text Thread](./text-threads.md) or, if you have [external agents](/.external-agents.md) connected, you can create new threads with them.
+
 ### Editing Messages {#editing-messages}
 
 Any message that you send to the AI is editable.
@@ -30,7 +42,7 @@ The checkpoint button appears even if you interrupt the thread midway through an
 
 ### Navigating History {#navigating-history}
 
-To quickly navigate through recently opened threads, use the {#kb agent::ToggleNavigationMenu} binding, when focused on the panel's editor, or click the menu icon button at the top left of the panel to open the dropdown that shows you the six most recent threads.
+To quickly navigate through recently opened threads, use the {#kb agent::ToggleNavigationMenu} binding, when focused on the panel's editor, or click the menu icon button at the top right of the panel to open the dropdown that shows you the six most recent threads.
 
 The items in this menu function similarly to tabs, and closing them doesn’t delete the thread; instead, it simply removes them from the recent list.
 
@@ -70,16 +82,13 @@ So, if your active tab had edits made by the AI, you'll see diffs with the same
 
 Although Zed's agent is very efficient at reading through your code base to autonomously pick up relevant files, directories, and other context, manually adding context is still encouraged as a way to speed up and improve the AI's response quality.
 
-If you have a tab open while using the Agent Panel, that tab appears as a suggested context in form of a dashed button.
-You can also add other forms of context by either mentioning them with `@` or hitting the `+` icon button.
-
-You can even add previous threads as context by mentioning them with `@thread`, or by selecting the "New From Summary" option from the `+` menu to continue a longer conversation, keeping it within the context window.
+To add any file, directory, symbol, previous threads, rules files, or even web pages as context, type `@` to mention them in the editor.
 
 Pasting images as context is also supported by the Agent Panel.
 
 ### Token Usage {#token-usage}
 
-Zed surfaces how many tokens you are consuming for your currently active thread in the panel's toolbar.
+Zed surfaces how many tokens you are consuming for your currently active thread nearby the profile selector in the panel's message editor.
 Depending on how many pieces of context you add, your token consumption can grow rapidly.
 
 With that in mind, once you get close to the model's context window, a banner appears below the message editor suggesting to start a new thread with the current one summarized and added as context.
@@ -145,7 +154,7 @@ Zed's UI will inform about this via a warning icon that appears close to the mod
 
 ## Text Threads {#text-threads}
 
-["Text threads"](./text-threads.md) present your conversation with the LLM in a different format—as raw text.
+["Text Threads"](./text-threads.md) present your conversation with the LLM in a different format—as raw text.
 With text threads, you have full control over the conversation data.
 You can remove and edit responses from the LLM, swap roles, and include more context earlier in the conversation.
 

docs/src/ai/external-agents.md

@@ -0,0 +1,81 @@
+# External Agents
+
+Zed supports terminal-based agentic coding tools through the [Agent Client Protocol (ACP)](https://agentclientprotocol.com).
+
+Currently, [Gemini CLI](https://github.com/google-gemini/gemini-cli) serves as the reference implementation, and you can [add custom ACP-compatible agents](#add-custom-agents) as well.
+
+## Gemini CLI {#gemini-cli}
+
+Zed provides the ability to run [Gemini CLI](https://github.com/google-gemini/gemini-cli) directly in the [agent panel](./agent-panel.md).
+
+Under the hood we run Gemini CLI in the background, and talk to it over ACP.
+This means that you're running the real Gemini CLI, with all of the advantages of that, but you can see and interact with files in your editor.
+
+### Getting Started
+
+As of Zed Stable v0.201.5 you should be able to use Gemini CLI directly from Zed. First open the agent panel with {#kb agent::ToggleFocus}, and then use the `+` button in the top right to start a New Gemini CLI thread.
+
+If you'd like to bind this to a keyboard shortcut, you can do so by editing your keybindings file to include:
+
+```json
+[
+  {
+    "bindings": {
+      "cmd-alt-g": ["agent::NewExternalAgentThread", { "agent": "gemini" }]
+    }
+  }
+]
+```
+
+#### Installation
+
+If you don't yet have Gemini CLI installed, then Zed will install a version for you. If you do, then we will use the version of Gemini CLI on your path.
+
+You need to be running at least Gemini version `0.2.0-preview`, and if your version of Gemini is too old you will see an
+error message.
+
+The instructions to upgrade Gemini depend on how you originally installed it, but typically, running `npm install -g gemini-cli@preview` should work.
+
+#### Authentication
+
+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.
+
+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, and have already configured their environment correctly.
+
+For more information, see the [Gemini CLI docs](https://github.com/google-gemini/gemini-cli/blob/main/docs/index.md).
+
+### Usage
+
+Similar to Zed's first-party agent, you can use Gemini CLI to do anything that you need.
+
+You can @-mention files, recent conversations, symbols, or fetch the web.
+
+There are two features that don't yet work with Gemini CLI: editing past messages, which we hope to add support for soon; and resuming a conversation from history.
+
+## Add Custom Agents {#add-custom-agents}
+
+You can run any agent speaking ACP in Zed by changing your settings as follows:
+
+```json
+{
+  "agent_servers": {
+    "Custom Agent": {
+      "command": "node",
+      "args": ["~/projects/agent/index.js", "--acp"],
+      "env": {}
+    }
+  }
+}
+```
+
+This can also be useful if you're in the middle of developing a new agent that speaks the protocol and you want to debug it.
+
+## 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.
+
+[screenshot here]

docs/src/ai/overview.md

@@ -6,6 +6,8 @@ Learn how to get started using AI with Zed and all its capabilities.
 
 - [Configuration](./configuration.md): Learn how to set up different language model providers like Anthropic, OpenAI, Ollama, Google AI, and more.
 
+- [External Agents](./external-agents.md): Learn how to plug in your favorite agent into Zed.
+
 - [Subscription](./subscription.md): Learn about Zed's hosted model service and other billing-related information.
 
 - [Privacy and Security](./privacy-and-security.md): Understand how Zed handles privacy and security with AI features.