メインコンテンツへスキップ
サブエージェントを利用すると、メインのエージェントが独立したワーカーを立ち上げて、サブタスクを処理できます。サブエージェントは親エージェントとツールおよびコードベースの前提情報を共有しますが、独自の会話チェーンで動作し、親の会話履歴は引き継ぎません。これは、コードベースの調査、テストの実行、機能の並行実装など、独立して集中的に進めることで効果が高まるタスクに役立ちます。 エージェントに明示的にサブエージェントを利用するよう依頼することもできます (例: 「サブエージェントで認証の仕組みを調査して」) 。また、独立して進めたほうが効果的だと判断した場合は、エージェント自身が委任することもあります。 私たちの測定では、サブエージェント全体的なコーディング性能を向上させる同時にコストを削減します。

サブエージェントの仕組み

エージェントがサブエージェントを起動すると、利用可能なサブエージェントプロファイルのいずれかを選択し、そのサブエージェントをフォアグラウンドとバックグラウンドのどちらで実行するかを決めます。サブエージェントは次の2つのモードで実行できます。

フォアグラウンド

セッション内でインライン実行されます。親エージェントは一時停止し、サブエージェントの完了を待ってから処理を続けます。ツール呼び出しが発生した場合は、その都度承認または拒否できます。

バックグラウンド

親エージェントが作業を続ける間、並行して実行されます。サブエージェントが完了すると、親エージェントに自動的に通知されます。承認されていないツールは自動的に拒否されます。
サブエージェントの生の出力は直接表示されません。サブエージェントが完了すると、親エージェントが結果を読み取り、重要な検出結果とアクションを要約して知らせます。

サブエージェントのコスト

サブエージェントはそれぞれ独立したエージェントセッションとして実行され、各自の前提情報ウィンドウと推論呼び出しを持つため、親とは別にコストが発生します。親の費用に含まれるのは親自身の作業分のみで、親が生成したサブエージェントごとに追加の使用量が加算されます。
プロンプトベースのプランでは、各サブエージェントでもユーザーメッセージと同様に追加のクレジットが消費されます。消費されるクレジット数はサブエージェントが利用するモデルによって異なるため、複数のサブエージェントを生成するタスク (またはそれらをnestするタスク) では、より多くのクレジットが消費されます。
コストはサブエージェントの数に応じて増えるため、多数のサブエージェントに分岐するタスク (またはそれらを入れ子にするタスク) ほど高コストになります。並列実行や前提情報を絞り込むことのメリットが追加コストに見合う場合に、サブエージェントを意図的に利用してください。

サブエージェントはどのモデルを使いますか?

サブエージェントは、モデルピッカーで選択したモデルですべて実行されるわけではありません。どのモデルを使うかは、各プロファイルごとに決まっています。
subagent_general は親のモデルを引き継ぎます。プレミアムモデルを使っている場合、general サブエージェントもそれぞれ独自の前提情報ウィンドウと推論呼び出しを持つ同じプレミアムモデルで実行されます。そのため、複数の general サブエージェントに分岐するタスクでは、コストがその分増えていきます。作業内容がコード変更ではなく調査であれば、explore サブエージェント (または、より安価な model: を固定した custom subagent) を依頼してください。
デフォルトのサブエージェントモデル は固定のモデル名ではありません。生成時にルーター経由で解決され、管理者が上書きすることもできます (以下を参照) 。既定の Subagent router 設定では、SWE-1.6 に解決されます (プランのティアに応じて、高速または低速な SWE-1.6 バリアントが使われます) 。
CLI では現在、実行中のサブエージェントがどのモデルを使っているかはサブエージェントパネルに表示されません。

モデルの選択に影響する要素

プロンプト内でサブエージェント用のモデル名を指定する方法はありません — run_subagent ツールが受け取るのはモデルではなく profile です。使える手段は 2 つあります。
  1. 自然言語で profile を指定する。 explore サブエージェントを依頼すると (「explore サブエージェントで auth の仕組みを調査して」など) 、処理は低コストなデフォルトのサブエージェントモデルで実行されます。コード変更を依頼すると subagent_general が使われ、選択したモデルで実行されます。
  2. カスタムサブエージェント の profile でモデルを固定する。 AGENT.mdmodel: は、書き込み可能なサブエージェントを親とは異なるモデルで実行する唯一の方法です。サブエージェント内で実行される スキル でも、フロントマター に model: を設定して profile のモデルを上書きできます。

Enterprise Controls

管理者は、org/enterprise 設定の デフォルトのサブエージェントモデル 設定で、サブエージェントが利用するモデルと、サブエージェント自体を実行可能にするかどうかを管理できます。この設定は、subagent_explore と、model: を固定していないカスタムサブエージェントに使用されるモデルを制御します。subagent_general は常に親エージェントのモデルに従うため、変更されません。
デフォルトのサブエージェントモデル設定
選択肢は 3 つあります。

サブエージェントプロファイル

各サブエージェントは、その機能を決定する特定のプロファイルで実行されます。組み込みプロファイルは 2 種類あります。
エージェントは、タスクに応じて適切なプロファイルを自動的に選択します。explore サブエージェントは調査や理解に最適で、general サブエージェントは変更を加えられます。各プロファイルがどのようにモデルを選択するかについては、サブエージェントはどのモデルを利用しますか? を参照してください。2 つのプロファイルは同じモデルで実行されるわけではありません。
独自のカスタム サブエージェントプロファイルを定義することもできます。詳細は、以下の カスタムサブエージェント を参照してください。

ツールの権限

ツールの権限の動作は、サブエージェントがフォアグラウンドで実行されているか、バックグラウンドで実行されているかによって異なります。
  • フォアグラウンドのサブエージェント はメインのエージェントと同様に動作し、通常どおりツール呼び出しを承認または拒否するよう求められます。
  • バックグラウンドのサブエージェント は、現在のセッション中にすでに付与したツールの権限を引き継ぎます。事前に承認されていないツールは自動的に拒否されます。バックグラウンドのサブエージェントが新しい権限の承認を求めることはできません。
バックグラウンドのサブエージェントが、必要なツールが拒否されたために失敗した場合は、そのサブエージェントをフォアグラウンドで再開して、必要な権限を承認できます。詳しくは、以下の Resuming Subagents を参照してください。

サブエージェントの監視

サブエージェントのインジケーター

バックグラウンドでサブエージェントが実行されている場合は、入力欄の下にステータスを示すインジケーターが表示されます。入力欄で を押すとインジケーターに移動でき、Enter を押すとサブエージェントパネルを開けます。 フォアグラウンドでサブエージェントが実行されている場合、スピナーには 「サブエージェント実行中 · Ctrl+B でバックグラウンド実行」 と表示されます。

サブエージェントパネル

サブエージェントパネルでは、アクティブなサブエージェントと完了済みのサブエージェントをすべて閲覧・管理できます。各サブエージェントのプロファイル、タイトル、ステータス、経過時間、ツール呼び出し回数が表示されます。

フォアグラウンド / バックグラウンドの切り替え

サブエージェントの実行中に、フォアグラウンドとバックグラウンドを切り替えられます。
  • フォアグラウンドのサブエージェントをバックグラウンドに切り替える: フォアグラウンドのサブエージェントの実行中に Ctrl+B を押します。サブエージェントはバックグラウンドで処理を続け、親エージェントが再開します。
  • バックグラウンドのサブエージェントをフォアグラウンドに切り替える: サブエージェントパネルを開き、実行中のバックグラウンド サブエージェントで f を押します。サブエージェントの出力がインラインで表示されます。
サブエージェントをバックグラウンドに移した時点で、親エージェントのツール呼び出しはすでに完了しているため、親エージェントは独立して処理を続行します。サブエージェントの結果は親エージェントの現在のパイプラインには反映されませんが、完了すると通知されます。

サブエージェントのキャンセル

実行中のサブエージェントは、次の 2 つの方法でキャンセルできます。
  1. サブエージェントパネルから: パネルを開き、実行中のサブエージェントで x を押します。
  2. フォアグラウンドのサブエージェント: 現在実行中のフォアグラウンドのサブエージェントをキャンセルするには、Ctrl+C または Esc を押します。

サブエージェントの再開

キャンセルされたサブエージェント、失敗したサブエージェント、または完了したサブエージェントは、新しいプロンプトで再開できます。エージェントにサブエージェントの再開を依頼すると、中断したところから続行します。再開したサブエージェントは常にフォアグラウンドで実行されるため、以前に拒否されたツール呼び出しも承認できます。 これは特に次のような場合に便利です。
  • バックグラウンドで実行していたサブエージェントが、必要なツールの利用を拒否されたために失敗した場合 — フォアグラウンドで再開して、必要な権限を付与できます。
  • サブエージェントは完了したものの、その結果に基づいて追加のフォローアップ作業を行わせたい場合。
  • サブエージェントが途中でキャンセルされてしまい、続きを実行させたい場合。

ネストの深さ

デフォルトでは、サブエージェントは自身のサブエージェントを起動できません。起動できるのはルートエージェントのみです。無制限にネストされるのを防ぐため、サブエージェント内ではサブエージェント ツール (run_subagentread_subagent) は無効になっています。 ただし、カスタム サブエージェントプロファイルでは、フロントマターで max-nesting フィールドを設定することで、ネストした起動を有効にできます。この値はデフォルトの最大深度を上書きし、ツリーがその上限内に収まっている限り、サブエージェントが子サブエージェントを起動できるようにします。 たとえば、max-nesting: 3 を設定すると、次のチェーンが可能です。
ネストされたサブエージェントは、コストを大幅に増やす可能性があります。ネストが1段深くなるごとに、それぞれ独自のコンテキストウィンドウと推論呼び出しを持つ追加のエージェントが生成されます。この機能は、必要性をよく検討したうえで利用してください。

カスタムサブエージェント

カスタムサブエージェントは実験的な機能です。形式、動作、設定オプションは今後のリリースで変更される可能性があります。
組み込みのsubagent_exploreおよびsubagent_generalプロファイルに加えて、独自のカスタムサブエージェントプロファイルを定義できます。カスタムサブエージェントを使用すると、それぞれに固有のシステムプロンプト、ツールの制限、モデルのオーバーライド、権限を持つ、ワークフロー内の特定のタスク向けに最適化された専用ワーカーを作成できます。これは、 (高価になる可能性がある) プライマリモデルでは実行されない書き込み可能なサブエージェントを使う方法でもあります。model:と必要なツールを指定してください。

カスタムサブエージェントの作成

カスタムサブエージェントは、agents/ 配下の名前付きディレクトリ内にある AGENT.md ファイルとして定義されます。ディレクトリ名がプロファイルの識別子になります。
以下もサポートされています:

AGENT.md の形式

AGENT.md ファイルは、skills と同じ YAML フロントマター を使用し、その後にサブエージェントのシステムプロンプトが続きます:

フロントマター のフィールド

カスタムサブエージェント の利用方法

定義すると、カスタム サブエージェントプロファイルは組み込みプロファイルと並んで表示されます。エージェントは利用可能な各プロファイルの説明を確認し、サブエージェント を起動する際に最も適切なものを選択します。また、プロファイル名を指定して、特定のプロファイルを利用するようエージェントに依頼することもできます (例: 「reviewer サブエージェント を使ってこのコードをレビューして」) 。 組み込みプロファイル名 (例: subagent_explore, subagent_general) と競合するカスタム サブエージェントプロファイルは、警告が表示されたうえでスキップされます。

他のツールからのインポート

カスタムサブエージェントは、Claude Code のエージェント形式からもインポートできます。
Claude Code のエージェントファイルでは、フロントマター に allowed-tools ではなく tools を使用します。どちらの形式も自動的にサポートされます。

使用例

読み取り専用調査エージェント

テスト実行エージェント