Specialized agents that operate within your main Gemini CLI session — each with its own system prompt, toolset, and independent context window.
Subagents handle specific, complex tasks without cluttering the main agent's context or toolset. The main agent exposes each subagent as a callable tool. It delegates, the subagent runs in its own loop, then reports back with findings.
mcp_* to grant groups of tools with precision.Prefix any prompt with @subagent_name to bypass the main agent's routing and go straight to a specialist.
Three are enabled by default. The browser_agent is experimental and must be explicitly enabled via agents.overrides in settings.json.
The browser agent supports three Chrome session modes and enforces domain restrictions, blocked URL schemes, and action rate limiting.
Launches Chrome with a profile at ~/.gemini/cli-browser-profile/. Cookies, history, and settings preserved between sessions.
Temporary profile deleted after each session. Use for clean-state automation and testing scenarios.
Attaches to an already-running Chrome instance with remote debugging enabled. Required for Docker/container sandbox environments.
Set allowedDomains to restrict navigation. Disallowed domains throw fatal errors. Proxy bypass attempts via query parameters are detected and blocked.
Always blocked: file://, javascript:, data:text/html, chrome://extensions, chrome://settings/passwords.
maxActionsPerTask (default: 100) limits total tool calls per task. The browser agent terminates when the limit is reached, preventing runaway execution.
Set visualModel to enable screenshot-based interaction via analyze_screenshot. Requires API key or Vertex AI authentication. Not available with Sign in with Google.
Custom subagents are .md files with YAML frontmatter. Place in .gemini/agents/ (project, team-shared) or ~/.gemini/agents/ (user-level, personal).
| Field | Required | Description |
|---|---|---|
| name | Yes | Unique slug — lowercase, hyphens, underscores. Becomes the tool name exposed to the main agent. |
| description | Yes | Visible to main agent. Write clearly — this determines when automatic delegation triggers. |
| kind | No | local (default) or remote for A2A remote delegation. |
| tools | No | Tool access list. Wildcards: * (all), mcp_* (all MCP), mcp_server_*. Omit to inherit all parent tools. |
| mcpServers | No | Inline MCP server definitions isolated to this agent only. |
| model | No | Specific Gemini model. Defaults to inherit (main session model). |
| temperature | No | 0.0–2.0. Defaults to 1. |
| max_turns | No | Max conversation turns before the agent must return. Defaults to 30. |
| timeout_mins | No | Max execution time in minutes. Defaults to 10. |
Each subagent runs in its own isolated context loop. Subagents cannot call other subagents — even with * (all tools) granted.
Define exactly which tools an agent can access. Prevents unintended side effects and state contamination across the global tool registry. Enables fine-grained permission control per agent.
Framework-level protection: even with * granted, a subagent cannot see or invoke other subagents. Stops infinite delegation loops and runaway token usage.
Configure MCP servers in the agent's frontmatter under mcpServers. These are isolated to that agent only — not shared with the main session or other agents.
TOML [[rules]] blocks with a subagent property target specific agents. Grant or deny tool access and commands per agent without affecting the rest of your session.
Use /agents for on-the-fly changes; use agents.overrides in settings.json for persistent global overrides.
maxTurns, maxTimeMinutes, and model configuration across all sessions via settings.json.~/.gemini/policies/. Subagents are treated as virtual tool names — deny specific agents for specific sessions using the policy engine.Seven steps from idea to a working specialist agent.
.md file in .gemini/agents/ (project-level, shared with team) or ~/.gemini/agents/ (user-level, personal). The filename is your natural identifier.--- frontmatter. Required fields: name (slug — lowercase, hyphens, underscores only) and description. The main agent reads the description to decide when to delegate.tools array listing exactly which tools the agent can use. Use wildcards (*, mcp_*, mcp_server_*) for flexible grants. Omit to inherit all parent tools.model, temperature (0.0–2.0), max_turns (default 30), timeout_mins (default 10), and mcpServers for inline MCP server definitions isolated to this agent.~/.gemini/policies/ with [[rules]] blocks. Add a subagent property to target your agent by name for fine-grained allow/deny control./agents or settings.json/agents interactively for on-the-fly changes. Use agents.overrides for persistent model and run configuration. Tune the description for better automatic delegation reliability.Subagents are specialized agents operating within the main Gemini CLI session. Each has its own system prompt, persona, and toolset, running in an independent context window so they don't bloat the main conversation history.
Use the @ syntax at the start of your prompt — for example, @codebase_investigator explain the auth module. This bypasses automatic delegation and routes directly to the named subagent.
Four: codebase_investigator (code analysis), cli_help (CLI docs), generalist (all-purpose), and browser_agent (experimental, disabled by default).
Deep code analysis — understanding how systems work, tracing dependencies, reverse engineering complex modules. Use it for "How does the authentication system work?" or "Map out the AgentRegistry class dependencies."
The generalist inherits the same full tool access but runs in an isolated context loop. Multi-step tasks with large outputs don't clutter the main conversation — only the final result is returned.
Add "browser_agent": {"enabled": true} under agents.overrides in settings.json. Also requires Chrome 144+. Choose a session mode: persistent (default), isolated, or existing.
No. Recursion protection prevents this even with the * wildcard granted. This stops infinite delegation loops and runaway token usage at the framework level.
In .gemini/agents/ at the project root (shared with your team) or ~/.gemini/agents/ at user level (personal, available across all projects).
Tool isolation ensures subagents only access explicitly listed tools, preventing cross-agent state contamination and unauthorized actions. It enables fine-grained permission control per agent.
Add a tools array in the YAML frontmatter. Use wildcards like mcp_* for all MCP tools, or omit the list entirely to inherit all parent session tools.
A2A enables Gemini CLI to delegate tasks to remote subagents running on external machines or services. Declare remote agents with kind: remote in their definition file.
Set "enableAgents": false under experimental in settings.json. Individual agents can also be disabled with enabled: false under agents.overrides.
@subagent_name prefix forcing a prompt to be handled by a specific subagent, bypassing the main agent's automatic routing decision.subagent property.* (all), mcp_* (all MCP), mcp_server_* (all tools from a named MCP server)..md file with YAML frontmatter defining a custom subagent's name, description, tools, model, and system prompt. Placed in .gemini/agents/.