From 246a6d10c36964e748c874ddd73c60112e21ee3b Mon Sep 17 00:00:00 2001 From: Christian Gunderman Date: Tue, 27 Jan 2026 18:24:37 +0000 Subject: [PATCH] Sub-agents documentation. (#16639) Co-authored-by: Jenna Inouye --- docs/core/index.md | 2 + docs/core/subagents.md | 194 +++++++++++++++++++++++++++++++++++ docs/extensions/index.md | 9 +- docs/extensions/reference.md | 30 +++++- docs/sidebar.json | 4 + 5 files changed, 232 insertions(+), 7 deletions(-) create mode 100644 docs/core/subagents.md diff --git a/docs/core/index.md b/docs/core/index.md index e16af9af77..0cd49ad43e 100644 --- a/docs/core/index.md +++ b/docs/core/index.md @@ -7,6 +7,8 @@ requests sent from `packages/cli`. For a general overview of Gemini CLI, see the ## Navigating this section +- **[Sub-agents (experimental)](./subagents.md):** Learn how to create and use + specialized sub-agents for complex tasks. - **[Core tools API](./tools-api.md):** Information on how tools are defined, registered, and used by the core. - **[Memory Import Processor](./memport.md):** Documentation for the modular diff --git a/docs/core/subagents.md b/docs/core/subagents.md new file mode 100644 index 0000000000..8a0937eb31 --- /dev/null +++ b/docs/core/subagents.md @@ -0,0 +1,194 @@ +# Sub-agents (experimental) + +Sub-agents are specialized agents that operate within your main Gemini CLI +session. They are designed to handle specific, complex tasks—like deep codebase +analysis, documentation lookup, or domain-specific reasoning—without cluttering +the main agent's context or toolset. + +> **Note: Sub-agents are currently an experimental feature.** +> +> To use custom sub-agents, you must explicitly enable them in your +> `settings.json`: +> +> ```json +> { +> "experimental": { "enableAgents": true } +> } +> ``` +> +> **Warning:** Sub-agents currently operate in +> ["YOLO mode"](../get-started/configuration.md#command-line-arguments), meaning +> they may execute tools without individual user confirmation for each step. +> Proceed with caution when defining agents with powerful tools like +> `run_shell_command` or `write_file`. + +## What are sub-agents? + +Think of sub-agents as "specialists" that the main Gemini agent can hire for a +specific job. + +- **Focused context:** Each sub-agent has its own system prompt and persona. +- **Specialized tools:** Sub-agents can have a restricted or specialized set of + tools. +- **Independent context window:** Interactions with a sub-agent happen in a + separate context loop. The main agent only sees the final result, saving + tokens in your main conversation history. + +Sub-agents are exposed to the main agent as a tool of the same name which +delegates to the sub-agent, when called. Once the sub-agent completes its task +(or fails), it reports back to the main agent with its findings (usually as a +text summary or structured report returned by the tool). + +## Built-in sub-agents + +Gemini CLI comes with powerful built-in sub-agents. + +### Codebase Investigator + +- **Name:** `codebase_investigator` +- **Purpose:** Deep analysis of the codebase, reverse engineering, and + understanding complex dependencies. +- **When to use:** "How does the authentication system work?", "Map out the + dependencies of the `AgentRegistry` class." +- **Configuration:** Enabled by default. You can configure it in + `settings.json`. Example (forcing a specific model): + ```json + { + "experimental": { + "codebaseInvestigatorSettings": { + "enabled": true, + "maxNumTurns": 20, + "model": "gemini-2.5-pro" + } + } + } + ``` + +### CLI Help Agent + +- **Name:** `cli_help` +- **Purpose:** Expert knowledge about Gemini CLI itself, its commands, + configuration, and documentation. +- **When to use:** "How do I configure a proxy?", "What does the `/rewind` + command do?" +- **Configuration:** Enabled by default. + +## Creating custom sub-agents + +You can create your own sub-agents to automate specific workflows or enforce +specific personas. + +### Prerequisites + +To use custom sub-agents, you must enable them in your `settings.json`: + +```json +{ + "experimental": { + "enableAgents": true + } +} +``` + +### Agent definition files + +Custom agents are defined as Markdown files (`.md`) with YAML frontmatter. You +can place them in: + +1. **Project-level:** `.gemini/agents/*.md` (Shared with your team) +2. **User-level:** `~/.gemini/agents/*.md` (Personal agents) + +### File format + +The file **MUST** start with YAML frontmatter enclosed in triple-dashes `---`. +The body of the markdown file becomes the agent's **System Prompt**. + +**Example: `.gemini/agents/security-auditor.md`** + +```markdown +--- +name: security-auditor +description: Specialized in finding security vulnerabilities in code. +kind: local +tools: + - read_file + - search_file_content +model: gemini-2.5-pro +temperature: 0.2 +max_turns: 10 +--- + +You are a ruthless Security Auditor. Your job is to analyze code for potential +vulnerabilities. + +Focus on: + +1. SQL Injection +2. XSS (Cross-Site Scripting) +3. Hardcoded credentials +4. Unsafe file operations + +When you find a vulnerability, explain it clearly and suggest a fix. Do not fix +it yourself; just report it. +``` + +### Configuration schema + +| Field | Type | Required | Description | +| :------------- | :----- | :------- | :------------------------------------------------------------------------------------------------------------------------- | +| `name` | string | Yes | Unique identifier (slug) used as the tool name for the agent. Only lowercase letters, numbers, hyphens, and underscores. | +| `description` | string | Yes | Short description of what the agent does. This is visible to the main agent to help it decide when to call this sub-agent. | +| `kind` | string | No | `local` (default) or `remote`. | +| `tools` | array | No | List of tool names this agent can use. If omitted, it may have access to a default set. | +| `model` | string | No | Specific model to use (e.g., `gemini-2.5-pro`). Defaults to `inherit` (uses the main session model). | +| `temperature` | number | No | Model temperature (0.0 - 2.0). | +| `max_turns` | number | No | Maximum number of conversation turns allowed for this agent before it must return. | +| `timeout_mins` | number | No | Maximum execution time in minutes. | + +### Optimizing your sub-agent + +The main agent system prompt contains language that encourages use of an expert +sub-agent when one is available for the task at hand. It decides whether an +agent is a relevant expert based on the agent's description. You can improve the +reliability with which an agent is used by updating the description to more +clearly indicate: + +- Its area of expertise. +- When it should be used. +- Some example scenarios. + +For example: the following sub-agent description should be called fairly +consistently for Git operations. + +> Git expert agent which should be used for all local and remote git operations. +> For example: +> +> - Making commits +> - Searching for regressions with bisect +> - Interacting with source control and issues providers such as GitHub. + +If you need to further tune your sub-agent, you can do so by selecting the model +to optimize for with `/model` and then asking the model why it does not think +that your sub-agent was called with a specific prompt and the given description. + +## Remote agents (Agent2Agent) + +Gemini CLI can also delegate tasks to remote agents using the Model Context +Protocol (MCP) or compatible Agent2Agent interfaces. + +To define a remote agent, use `kind: remote` and provide the `agent_card_url`. + +```markdown +--- +name: bigquery-analyst +description: Can query BigQuery datasets and visualize results. +kind: remote +agent_card_url: https://agent.example.com/cards/bigquery-analyst +--- +``` + +## Extension sub-agents + +Extensions can bundle and distribute sub-agents. See the +[Extensions documentation](../extensions/index.md#sub-agents) for details on how +to package agents within an extension. diff --git a/docs/extensions/index.md b/docs/extensions/index.md index b44210762d..ae66ce07bf 100644 --- a/docs/extensions/index.md +++ b/docs/extensions/index.md @@ -1,9 +1,10 @@ # Gemini CLI extensions -Gemini CLI extensions package prompts, MCP servers, custom commands, hooks, and -agent skills into a familiar and user-friendly format. With extensions, you can -expand the capabilities of Gemini CLI and share those capabilities with others. -They are designed to be easily installable and shareable. +Gemini CLI extensions package prompts, MCP servers, custom commands, hooks, +sub-agents, and agent skills into a familiar and user-friendly format. With +extensions, you can expand the capabilities of Gemini CLI and share those +capabilities with others. They are designed to be easily installable and +shareable. To see examples of extensions, you can browse a gallery of [Gemini CLI extensions](https://geminicli.com/extensions/browse/). diff --git a/docs/extensions/reference.md b/docs/extensions/reference.md index 12d04e0bdd..7b5f782917 100644 --- a/docs/extensions/reference.md +++ b/docs/extensions/reference.md @@ -282,6 +282,29 @@ An extension with the following structure: Will expose a `security-audit` skill that the model can activate. +### Sub-agents + +> **Note: Sub-agents are currently an experimental feature.** + +Extensions can provide [sub-agents](../core/subagents.md) that users can +delegate tasks to. + +To bundle sub-agents with your extension, create an `agents/` directory in your +extension's root folder and add your agent definition files (`.md`) there. + +**Example** + +``` +.gemini/extensions/my-extension/ +├── gemini-extension.json +└── agents/ + ├── security-auditor.md + └── database-expert.md +``` + +Gemini CLI will automatically discover and load these agents when the extension +is installed and enabled. + ### Conflict resolution Extension commands have the lowest precedence. When a conflict occurs with user @@ -299,9 +322,10 @@ For example, if both a user and the `gcp` extension define a `deploy` command: ## Variables -Gemini CLI extensions allow variable substitution in `gemini-extension.json`. -This can be useful if e.g., you need the current directory to run an MCP server -using an argument like `"args": ["${extensionPath}${/}dist${/}server.js"]`. +Gemini CLI extensions allow variable substitution in both +`gemini-extension.json` and `hooks/hooks.json`. This can be useful if e.g., you +need the current directory to run an MCP server using an argument like +`"args": ["${extensionPath}${/}dist${/}server.js"]`. **Supported variables:** diff --git a/docs/sidebar.json b/docs/sidebar.json index b1e686f792..c1ea700c35 100644 --- a/docs/sidebar.json +++ b/docs/sidebar.json @@ -78,6 +78,10 @@ "label": "Ecosystem and extensibility", "items": [ { "label": "Agent skills (experimental)", "slug": "docs/cli/skills" }, + { + "label": "Sub-agents (experimental)", + "slug": "docs/core/subagents" + }, { "label": "Hooks (experimental)", "slug": "docs/hooks" }, { "label": "IDE integration", "slug": "docs/ide-integration" }, { "label": "MCP servers", "slug": "docs/tools/mcp-server" }