サブエージェントの仕組み
フォアグラウンド
セッション内でインライン実行されます。親エージェントは一時停止し、サブエージェントの完了を待ってから処理を続けます。ツール呼び出しが発生した場合は、その都度承認または拒否できます。
バックグラウンド
親エージェントが作業を続ける間、並行して実行されます。サブエージェントが完了すると、親エージェントに自動的に通知されます。承認されていないツールは自動的に拒否されます。
サブエージェントの生の出力は直接表示されません。サブエージェントが完了すると、親エージェントが結果を読み取り、重要な検出結果とアクションを要約して知らせます。
サブエージェントのコスト
プロンプトベースのプランでは、各サブエージェントでもユーザーメッセージと同様に追加のクレジットが消費されます。消費されるクレジット数はサブエージェントが利用するモデルによって異なるため、複数のサブエージェントを生成するタスク (またはそれらをnestするタスク) では、より多くのクレジットが消費されます。
サブエージェントはどのモデルを使いますか?
デフォルトのサブエージェントモデル は固定のモデル名ではありません。生成時にルーター経由で解決され、管理者が上書きすることもできます (以下を参照) 。既定の Subagent router 設定では、SWE-1.6 に解決されます (プランのティアに応じて、高速または低速な SWE-1.6 バリアントが使われます) 。
CLI では現在、実行中のサブエージェントがどのモデルを使っているかはサブエージェントパネルに表示されません。
モデルの選択に影響する要素
run_subagent ツールが受け取るのはモデルではなく profile です。使える手段は 2 つあります。
- 自然言語で profile を指定する。 explore サブエージェントを依頼すると (「explore サブエージェントで auth の仕組みを調査して」など) 、処理は低コストなデフォルトのサブエージェントモデルで実行されます。コード変更を依頼すると
subagent_generalが使われ、選択したモデルで実行されます。 - カスタムサブエージェント の profile でモデルを固定する。
AGENT.mdのmodel:は、書き込み可能なサブエージェントを親とは異なるモデルで実行する唯一の方法です。サブエージェント内で実行される スキル でも、フロントマター にmodel:を設定して profile のモデルを上書きできます。
Enterprise Controls
subagent_explore と、model: を固定していないカスタムサブエージェントに使用されるモデルを制御します。subagent_general は常に親エージェントのモデルに従うため、変更されません。

サブエージェントプロファイル
エージェントは、タスクに応じて適切なプロファイルを自動的に選択します。explore サブエージェントは調査や理解に最適で、general サブエージェントは変更を加えられます。各プロファイルがどのようにモデルを選択するかについては、サブエージェントはどのモデルを利用しますか? を参照してください。2 つのプロファイルは同じモデルで実行されるわけではありません。
ツールの権限
- フォアグラウンドのサブエージェント はメインのエージェントと同様に動作し、通常どおりツール呼び出しを承認または拒否するよう求められます。
- バックグラウンドのサブエージェント は、現在のセッション中にすでに付与したツールの権限を引き継ぎます。事前に承認されていないツールは自動的に拒否されます。バックグラウンドのサブエージェントが新しい権限の承認を求めることはできません。
サブエージェントの監視
サブエージェントのインジケーター
サブエージェントパネル
フォアグラウンド / バックグラウンドの切り替え
- フォアグラウンドのサブエージェントをバックグラウンドに切り替える: フォアグラウンドのサブエージェントの実行中に Ctrl+B を押します。サブエージェントはバックグラウンドで処理を続け、親エージェントが再開します。
- バックグラウンドのサブエージェントをフォアグラウンドに切り替える: サブエージェントパネルを開き、実行中のバックグラウンド サブエージェントで f を押します。サブエージェントの出力がインラインで表示されます。
サブエージェントをバックグラウンドに移した時点で、親エージェントのツール呼び出しはすでに完了しているため、親エージェントは独立して処理を続行します。サブエージェントの結果は親エージェントの現在のパイプラインには反映されませんが、完了すると通知されます。
サブエージェントのキャンセル
- サブエージェントパネルから: パネルを開き、実行中のサブエージェントで x を押します。
- フォアグラウンドのサブエージェント: 現在実行中のフォアグラウンドのサブエージェントをキャンセルするには、Ctrl+C または Esc を押します。
サブエージェントの再開
- バックグラウンドで実行していたサブエージェントが、必要なツールの利用を拒否されたために失敗した場合 — フォアグラウンドで再開して、必要な権限を付与できます。
- サブエージェントは完了したものの、その結果に基づいて追加のフォローアップ作業を行わせたい場合。
- サブエージェントが途中でキャンセルされてしまい、続きを実行させたい場合。
ネストの深さ
run_subagent と read_subagent) は無効になっています。
ただし、カスタム サブエージェントプロファイルでは、フロントマターで max-nesting フィールドを設定することで、ネストした起動を有効にできます。この値はデフォルトの最大深度を上書きし、ツリーがその上限内に収まっている限り、サブエージェントが子サブエージェントを起動できるようにします。
たとえば、max-nesting: 3 を設定すると、次のチェーンが可能です。
カスタムサブエージェント
subagent_exploreおよびsubagent_generalプロファイルに加えて、独自のカスタムサブエージェントプロファイルを定義できます。カスタムサブエージェントを使用すると、それぞれに固有のシステムプロンプト、ツールの制限、モデルのオーバーライド、権限を持つ、ワークフロー内の特定のタスク向けに最適化された専用ワーカーを作成できます。これは、 (高価になる可能性がある) プライマリモデルでは実行されない書き込み可能なサブエージェントを使う方法でもあります。model:と必要なツールを指定してください。
カスタムサブエージェントの作成
agents/ 配下の名前付きディレクトリ内にある AGENT.md ファイルとして定義されます。ディレクトリ名がプロファイルの識別子になります。
- プロジェクト固有
- グローバル
AGENT.md の形式
AGENT.md ファイルは、skills と同じ YAML フロントマター を使用し、その後にサブエージェントのシステムプロンプトが続きます:
フロントマター のフィールド
カスタムサブエージェント の利用方法
subagent_explore, subagent_general) と競合するカスタム サブエージェントプロファイルは、警告が表示されたうえでスキップされます。
他のツールからのインポート
Claude Code のエージェントファイルでは、フロントマター に
allowed-tools ではなく tools を使用します。どちらの形式も自動的にサポートされます。
