Gemini CLI に Subagents がやってきた。機能やメリット纏め。

はじめに

Gemini CLI は皆さんご存知でしょうか。
Google が提供するターミナルで動く AI エージェントツールで、コードの生成やファイル操作、コマンド実行などを自然言語でこなしてくれる便利なツールです。最近このツールに サブエージェント機能 が追加されていたので、どんなものか・定義方法・使い方を整理してみました。

「サブエージェントって何？」「今までと何が違うの？」という方向けに、順番に書いていきます。

サブエージェントとは

ざっくり纏めると、メインのエージェントが別の専門エージェントに仕事を振れる仕組み です。

今まで Gemini CLI で一連の流れで複数の役割が必要な作業がある場合でも、1つのエージェントが全ての作業を担当していました。コード調査も、ドキュメント生成も、テスト実行も、全部ひとつの AI が順番にこなす形です。

サブエージェント対応後は、こんなイメージになります。

メインエージェント（指揮者）
├── サブエージェントA：コードレビュー担当
├── サブエージェントB：ドキュメント生成担当
└── サブエージェントC：テスト担当

メインエージェントがタスクを受け取り、「これはコードレビュー担当に頼もう」「ドキュメントはあっちに任せよう」と仕事を割り振ってくれます。メインエージェントに自動で判断させる場合は順番に呼び出す形になりますが、@エージェント名 で明示的に指定すれば複数のサブエージェントを並列起動することもできます。

サブエージェントの定義方法

サブエージェントを .gemini/ ディレクトリ配下に Markdown ファイルとして定義 します。

プロジェクト構成はこんな感じです。

your-project/
└── .gemini/
    └── agents/
        ├── code-reviewer.md   # コードレビュー専用エージェント
        ├── doc-writer.md      # ドキュメント生成専用エージェント
        └── test-runner.md     # テスト実行専用エージェント

各エージェント定義ファイルの中身はこのような形式で書きます。

---
name: code-reviewer
description: コードの品質チェックとレビューを担当するエージェント。セキュリティ・パフォーマンス・可読性の観点でフィードバックを返す。
---

あなたはコードレビューの専門家です。
提供されたコードに対して以下の観点でレビューを行ってください。

- セキュリティリスクの有無
- パフォーマンス上の懸念点
- 可読性・保守性の改善提案

レビュー結果は Markdown 形式でまとめてください。

各パーツの役割はこんな感じです。

description はメインエージェントがルーティング判断に使うフィールドです。「コードレビューを担当する」という機能説明より、「コードの品質チェックが必要なとき・セキュリティ観点でのフィードバックが欲しいときに使う」という使いどころの説明を記載します。

本文はシステムプロンプトなので、AI に対してプロンプトで依頼するのと同じ感覚で指示を記載します。そのサブエージェントでファイル出力（Markdown で、ファイルに書き出して、など）を明示しておくと後続エージェントが読み込みやすくなります。

tools：利用ツールを制限する

tools フィールドを使うと、そのサブエージェントが利用できるツールを絞り込めます。
書き込みをさせたくない、不要な権限を与えない方法として活用できます。

---
name: code-reviewer
description: コードレビューを担当するエージェント。
tools:
  - read_file
  - grep_search
---

mcpServers：MCP サーバーをエージェント単位で設定する

フロントマターの mcpServers フィールドを使うと、そのエージェントでのみしか使わないような専用の MCP サーバーをインラインで定義できます。

---
name: aws-docs-researcher
description: AWSの公式ドキュメントを参照して設定値の意味やベストプラクティスを調査するエージェント。
mcpServers:
  aws-documentation:
    command: uvx
    args: ["awslabs.aws-documentation-mcp-server@latest"]
---

プロジェクト全体で使う MCP サーバーは settings.json に登録しておけばすべてのエージェントから参照できます。なお、特定のエージェントだけが使うものはフロントマターの mcpServers に起動設定ごと書くと、「この MCP はこのエージェントしか使わない」ということが可能になります。

その他のオプション

フロントマターには他にも以下のような項目を設定できます。こちらは慣れてきて何らか調整したい場合じゃないとつかわないかもな、と思います。

サブエージェントの使い方

上記を参考にサブエージェントの定義ができたら、あとは普通に Gemini CLI を起動してみましょう。

gemini

起動後に /agents list でエージェントが正しく読み込まれているか確認できます。

/agents list

定義したエージェント名が一覧に表示されていれば準備完了です。

自動委譲

起動後に自然言語でタスクを伝えると、Gemini CLI が自動的にどのサブエージェントを使うか判断してくれます。

このような指示を与えると、メインエージェントが「well architect観点のレビューは well_archi_reviwer に任せよう」と判断して動いてくれます。実際に動かしてみると、どのサブエージェントが呼び出されているか、画像のようにターミナル上に表示されます。

@構文で明示的に指定する

「このタスクは絶対このエージェントに任せたい」という場合は、@エージェント名 で直接指定することもできます。

こういった形で依頼することでサブエージェントに定義した動きをしてくれます。

自動判断では意図しないエージェントが選ばれることもあるので、「このタスクはこのエージェントに任せたい」と明確に決まっているときは @構文で直接指定するのがいいかなと思います。

どちらを使うか

どのエージェントを呼ぶと心に決めているときはもちろん@構文がいいですが、指示した内容に適切なサブエージェントが存在するかわからないケースや、実はマッチするサブエージェントがあるような場合、勝手に目的にあったサブエージェントを使ってくれます。そのため、どちらか意識しなくても自然と必要なときに@構文でやるようになってくるかなと思いました。

ただ、フローが決まっていてどのエージェントを何の順番で呼ぶかが明確な場合は @構文 で直接指名する方が確実です。意図しないエージェントが選ばれるリスクをなくせるため、複数エージェントを決まった順序で動かすオーケストレーター構成では @構文 を主に使って行く形になるかなと思います。

エージェント定義を変更したときは

セッション中にエージェント定義ファイルを追加・変更した場合は、/agents reload コマンドで再起動なしにリロードできます。

/agents reload

注意：サブエージェントのネストはできない

1つ重要な制約として、サブエージェントは別のサブエージェントを呼び出せません。「エージェントがさらにエージェントを雇う」という多段委譲はできない設計になっています。無限ループやトークン爆発を防ぐための仕様とのことです。

シングルエージェントとの違い・サブエージェントのメリット

実際に使ってみて感じたメリットを自分なりに整理してみました。

まとめ

Gemini CLI のサブエージェント機能について、定義方法・使い方について自分なりに整理してみました。

使ってみて一番感じたのは、エージェントを操ってる感がすごくて面白いのと、それでいて利用した結果の精度の高さや、作業の効率化にもつながっていて、かなりいいなと思いました。
上記のような恩恵を受けられるというメリットがありながらも、Markdown ファイルを .gemini/agents/ に置くだけで簡単にサブエージェント化することができるのも大きいです。
あとは感覚として自分がチームをマネージメントするように、人員調整、役割分担を行い、1つのゴールに向かって仮想チーム構成を組んで進めてる感じがいいなと思いました。

実際にサブエージェントを使って並列・多フェーズのパイプラインを組む実践編は Qiita に書きましたので、興味のある方はそちらもどうぞ。
Gemini CLI でサブエージェントオーケストレートしてブログ書かせてみた

参考

• Gemini CLI サブエージェント ドキュメント
• Gemini CLI コマンドリファレンス（/agents）