Subagents

概要

メインの Gemini CLI セッションの中で動く特化エージェント。深いコードベース解析、ドキュメント参照、ドメイン固有の推論などを、メインエージェントのコンテキストやツールセットを汚さずに扱う。subagent は同名のツールとしてメインエージェントに公開され、呼び出されるとタスクを委譲し、完了後に結果を報告する。

仕様

特徴

• focused context: それぞれが独自のシステムプロンプトとペルソナを持つ
• specialized tools: 制限された、あるいは特化したツールセットを持てる
• 独立したコンテキストウィンドウ: 別のコンテキストループで動くため、メインの会話履歴のトークンを節約する

呼び出し方

• 自動委譲: メインエージェントは、タスクが専門に一致するとき subagent を使うよう指示されている
• @ 構文で強制: プロンプトの先頭に @<subagent 名> を書く。CLI はそのツールを即座に使うようプライマリモデルを促す system note を注入する

組み込み subagent

• codebase_investigator などの設定は settings.json の agents.overrides で上書きできる

browser_agent

既定で無効。 settings.json の agents.overrides.browser_agent.enabled を true にする。

• 前提: Chrome 144 以降（最近の stable リリースであればよい）
• 基盤の chrome-devtools-mcp サーバーは Gemini CLI にバンドルされ自動起動されるため、別途インストールは不要
• 初回起動時に同意ダイアログが出る。承認するまでブラウザセッションは始まらない。このダイアログは 1 回だけ出る

session mode（agents.browser.sessionMode）:

agents.browser の設定:

セキュリティ:

• ドメイン制限: allowedDomains を設定すると、列挙したドメイン（*. 接頭辞ならそのサブドメインも）にしか遷移できない。許可外ドメインへのアクセスは fatal error になりエージェントを即座に終了させる。許可ドメインをプロキシとして使う試み（クエリパラメータやフラグメント経由）も検出・ブロックしようとする
• ブロックされる URL スキーム: 基盤の MCP サーバーが file://、javascript:、data:text/html、chrome://extensions、chrome://settings/passwords をブロックする
• フォーム入力（fill、fill_form）は、approval mode に関わらず常に policy engine 経由でユーザー確認を要求する
• confirmSensitiveActions が true のときは upload_file と evaluate_script も確認が要る

visual agent:

• 既定ではアクセシビリティツリーの uid を使って操作する
• visualModel を設定すると analyze_screenshot ツールが使え、スクリーンショットを vision モデルに送って座標と要素の説明を得て、click_at で座標ベースの操作をする
• visual agent は API キーまたは Vertex AI の認証が必要で、「Sign in with Google」では利用できない

sandbox 内での挙動:

• macOS seatbelt（sandbox-exec）配下では、persistent と isolated は headless 有効の isolated に強制される（永続プロファイルに対する seatbelt のファイルシステム制限による権限エラーを避けるため）。sessionMode が existing のときは上書きされない
• コンテナ sandbox（Docker / Podman）ではコンテナ内に Chrome が無いため、sessionMode が "existing" でない限り browser agent は無効になる。existing のときは host.docker.internal:9222 の解決済み IP 経由でホストの Chrome に接続する。ポート 9222 はハードコードされており変更できない

custom subagent

YAML frontmatter を持つ Markdown ファイル（.md）として定義する。本文がシステムプロンプトになる。

配置場所:

1. project レベル: .gemini/agents/*.md（チームと共有）
2. user レベル: ~/.gemini/agents/*.md（個人用）

frontmatter:

ツールのワイルドカード:

• *: 利用可能なすべての組み込み・発見済みツール
• mcp_*: 接続中のすべての MCP サーバーのツール
• mcp_my-server_*: 特定の MCP サーバーのすべてのツール

隔離と再帰防止

• 独立した履歴: subagent の会話履歴はメインエージェントのコンテキストを膨らませない
• 隔離されたツール: 明示的に付与したツールにしかアクセスできない
• 再帰防止: subagent は他の subagent を呼べない。* のワイルドカードを与えても、他の agent を見ることも呼ぶこともできない

subagent ごとのポリシー

• Policy Engine の TOML で、[[rules]] ブロックに subagent プロパティを足すと、そのルールを特定の subagent に限定できる
• subagent プロパティの無いルールはすべての agent に普遍的に適用される
• subagent はポリシー照合上、仮想的なツール名として扱われるため、toolName に subagent 名を書いてアクセス自体を拒否することもできる
• 注意: 出典内で TOML ポリシーのスキーマ表記が食い違っている。 この節の出典（subagents ページ）は [[rules]]（複数形）と action = "allow" を使うが、Policy Engine のリファレンスは [[rule]]（単数）と decision = "allow" | "deny" | "ask_user" を documented schema としている（facts/gemini-cli/policy-engine.md）。下の 設定 の TOML 例は subagents ページからの逐語転記であり、どちらの綴りが実装上正しいかは出典からは判断できないため、実機で確認すること

管理

• 対話セッションでは /agents コマンドで有効化・無効化・再設定ができる（推奨）
• settings.json の agents.overrides で、特定 agent の有効・無効や run 設定（maxTurns、maxTimeMinutes）を恒久的に上書きする
• modelConfigs.overrides の match.overrideScope に subagent 名を指定すると、その subagent 向けのモデル設定を当てられる

説明文の最適化

メインエージェントは description を見て「関連する専門家か」を判断する。専門領域・使うべき場面・具体例を明示すると呼ばれやすくなる、とされている。

remote subagent と extension subagent

• Agent-to-Agent（A2A）プロトコルでリモートの subagent に委譲できる（詳細は Remote Subagents のドキュメント）
• extension は subagent をバンドルして配布できる

無効化

• subagent は既定で有効。 settings.json の experimental.enableAgents を false にすると無効になる

設定

---
name: security-auditor
description: Specialized in finding security vulnerabilities in code.
kind: local
tools:
  - read_file
  - grep_search
model: gemini-3-flash-preview
temperature: 0.2
max_turns: 10
---

You are a ruthless Security Auditor.

{
  "agents": {
    "overrides": {
      "browser_agent": { "enabled": true }
    },
    "browser": {
      "sessionMode": "existing",
      "allowedDomains": ["example.com"]
    }
  }
}

{
  "agents": {
    "overrides": {
      "security-auditor": {
        "enabled": false,
        "runConfig": { "maxTurns": 20, "maxTimeMinutes": 10 }
      }
    }
  }
}

[[rules]]
name = "Allow pr-creator to push code"
subagent = "pr-creator"
action = "allow"
toolName = "run_shell_command"
commandPrefix = "git push"

{
  "experimental": { "enableAgents": false }
}

関連

• facts/gemini-cli/configuration.md
• facts/gemini-cli/policy-engine.md
• facts/gemini-cli/mcp-server.md
• facts/gemini-cli/extensions.md
• facts/gemini-cli/model.md
• facts/gemini-cli/commands.md
• facts/gemini-cli/sandbox.md