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:
{
  "experimental": { "enableAgents": true }
}
Warning: Sub-agents currently operate in “YOLO mode”, 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?

Sub-agents are “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, which saves tokens in your main conversation history.

Sub-agents are exposed to the main agent as a tool of the same name. When the main agent calls the tool, it delegates the task to the sub-agent. Once the sub-agent completes its task, it reports back to the main agent with its findings.

Built-in sub-agents

Gemini CLI comes with the following built-in sub-agents:

Codebase Investigator

Name: codebase_investigator
Purpose: Analyze the codebase, reverse engineer, and understand 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):

{
  "experimental": {
    "codebaseInvestigatorSettings": {
      "enabled": true,
      "maxNumTurns": 20,
      "model": "gemini-2.5-pro"
    }
  }
}

CLI Help Agent

Name: cli_help
Purpose: Get 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.

Generalist Agent

Name: generalist_agent
Purpose: Route tasks to the appropriate specialized sub-agent.
When to use: Implicitly used by the main agent for routing. Not directly invoked by the user.
Configuration: Enabled by default. No specific configuration options.

Creating custom sub-agents

You can create your own sub-agents to automate specific workflows or enforce specific personas. To use custom sub-agents, you must enable them in your settings.json:

{
  "experimental": {
    "enableAgents": true
  }
}

Agent definition files

Custom agents are defined as Markdown files (.md) with YAML frontmatter. You can place them in:

Project-level: .gemini/agents/*.md (Shared with your team)
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

---
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’s system prompt encourages it to use an expert sub-agent when one is available. 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 subagents (Agent2Agent) (experimental)

Gemini CLI can also delegate tasks to remote sub-agents using the Agent-to-Agent (A2A) protocol.

Note: Remote subagents are currently an experimental feature.

See the Remote Subagents documentation for detailed configuration and usage instructions.

Extension sub-agents

Extensions can bundle and distribute sub-agents. See the Extensions documentation for details on how to package agents within an extension.