From d99a17e35777a63e3079bbce82a4c06f49706df9 Mon Sep 17 00:00:00 2001 From: Danilo Leal <67129314+danilo-leal@users.noreply.github.com> Date: Wed, 27 Aug 2025 09:12:52 -0300 Subject: [PATCH] docs: Add ACP-related content (#36966) Release Notes: - N/A --------- Co-authored-by: Conrad Irwin Co-authored-by: Bennet Bo Fenner Co-authored-by: Antonio Scandurra Co-authored-by: Matt Miller --- docs/src/SUMMARY.md | 1 + docs/src/ai/agent-panel.md | 27 ++++++----- docs/src/ai/external-agents.md | 82 ++++++++++++++++++++++++++++++++++ docs/src/ai/overview.md | 2 + 4 files changed, 102 insertions(+), 10 deletions(-) create mode 100644 docs/src/ai/external-agents.md diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 251cad6234f10d73f423680bcd600500daae65b2..9d07881914d1f73a7333d3dc67ad1d3ca6731bc5 100644 --- a/docs/src/SUMMARY.md +++ b/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) diff --git a/docs/src/ai/agent-panel.md b/docs/src/ai/agent-panel.md index f944eb88b06c8be21002ff319a972ff1843de39d..13d92278a441efd165511d88550754587bf7f97e 100644 --- a/docs/src/ai/agent-panel.md +++ b/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,15 @@ 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, at the moment, not all features outlined below work for external agents, like [Gemini CLI](./external-agents.md#gemini-cli)—features like _checkpoints_, _token usage display_, and _model selection_ may be supported in the future. + +### Creating New Threads + +By default, the Agent Panel uses Zed's first-party 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 +40,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 +80,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 +152,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. diff --git a/docs/src/ai/external-agents.md b/docs/src/ai/external-agents.md new file mode 100644 index 0000000000000000000000000000000000000000..a67aa9d8894f917f1dea4ff505355a6a9d57eff6 --- /dev/null +++ b/docs/src/ai/external-agents.md @@ -0,0 +1,82 @@ +# 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 threads, symbols, or fetch the web. + +Note that some first-party agent features don't yet work with Gemini CLI: editing past messages, resuming threads from history, and checkpointing. +We hope to add these features in the near future. + +## 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. + +![The debug view for ACP logs.](https://zed.dev/img/acp/acp-logs.webp) diff --git a/docs/src/ai/overview.md b/docs/src/ai/overview.md index 6f081cb243ffcfb77b4304373df67865cc71ee10..8bd45240fdad156e11f28e5ba92289c97de92218 100644 --- a/docs/src/ai/overview.md +++ b/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.