サブエージェントを利用すると、メインエージェントが独立したワーカーを立ち上げて、サブタスクを処理できます。サブエージェントは親エージェントとツールおよびコードベースの前提情報を共有しますが、独自の会話チェーンで動作し、親の会話履歴は引き継ぎません。これは、コードベースの調査、テストの実行、機能の並行実装など、独立して集中的に進めることで効果が高まるタスクに役立ちます。
エージェントに明示的にサブエージェントを利用するよう依頼することもできます (例: 「サブエージェントで認証の仕組みを調査して」) 。また、独立して進めたほうが効果的だと判断した場合は、エージェント自身が委任することもあります。
私たちの測定では、サブエージェント は全体的なコーディング性能を向上させる と同時に 、コストを削減 します。
エージェントがサブエージェントを起動すると、利用可能なサブエージェントプロファイル のいずれかを選択し、そのサブエージェントをフォアグラウンドとバックグラウンドのどちらで実行するかを決めます。サブエージェントは次の2つのモードで実行できます。
フォアグラウンド セッション内でインライン実行されます。親エージェントは一時停止し、サブエージェントの完了を待ってから処理を続けます。ツール呼び出しが発生した場合は、その都度承認または拒否できます。
バックグラウンド 親エージェントが作業を続ける間、並行して実行されます。サブエージェントが完了すると、親エージェントに自動的に通知されます。承認されていないツールは自動的に拒否されます。
サブエージェントの生の出力は直接表示されません。サブエージェントが完了すると、親エージェントが結果を読み取り、重要な検出結果とアクションを要約して知らせます。
各サブエージェントは、その機能を決定する特定のプロファイルで実行されます。組み込みプロファイルは 2 種類あります。
プロファイル 説明 ツールアクセス subagent_explore読み取り専用でのコードベース探索と調査 読み取り専用のコードベース ツールに加えて Web 検索を利用可能。ファイルの編集や任意の URL の取得はできません (フォアグラウンドかバックグラウンドかを問わず) subagent_generalコード変更を含む汎用タスク フォアグラウンドではすべてのツールを利用可能、バックグラウンドでは事前承認済みのツールのみ利用可能
エージェントは、タスクに応じて適切なプロファイルを自動的に選択します。explore サブエージェントは調査や理解に最適で、general サブエージェントは変更を加えられます。
独自のカスタム サブエージェントプロファイルを定義することもできます。詳細は、以下の カスタムサブエージェント を参照してください。
ツールの権限の動作は、サブエージェントがフォアグラウンドで実行されているか、バックグラウンドで実行されているかによって異なります。
フォアグラウンドのサブエージェント はメインのエージェントと同様に動作し、通常どおりツール呼び出しを承認または拒否するよう求められます。バックグラウンドのサブエージェント は、現在のセッション中にすでに付与したツールの権限を引き継ぎます。事前に承認されていないツールは自動的に拒否されます。バックグラウンドのサブエージェントが新しい権限の承認を求めることはできません。
バックグラウンドのサブエージェントが、必要なツールが拒否されたために失敗した場合は、そのサブエージェントをフォアグラウンドで再開して、必要な権限を承認できます。詳しくは、以下の Resuming Subagents を参照してください。 バックグラウンドでサブエージェントが実行されている場合は、入力欄の下にステータスを示すインジケーターが表示されます。入力欄で ↓ を押すとインジケーターに移動でき、Enter を押すとサブエージェントパネルを開けます。
フォアグラウンドでサブエージェントが実行されている場合、スピナーには 「サブエージェント実行中 · Ctrl+B でバックグラウンド実行」 と表示されます。
サブエージェントパネルでは、アクティブなサブエージェントと完了済みのサブエージェントをすべて閲覧・管理できます。各サブエージェントのプロファイル、タイトル、ステータス、経過時間、ツール呼び出し回数が表示されます。
サブエージェントの実行中に、フォアグラウンドとバックグラウンドを切り替えられます。
フォアグラウンドのサブエージェントをバックグラウンドに切り替える: フォアグラウンドのサブエージェントの実行中に Ctrl +B を押します。サブエージェントはバックグラウンドで処理を続け、親エージェントが再開します。バックグラウンドのサブエージェントをフォアグラウンドに切り替える: サブエージェントパネルを開き、実行中のバックグラウンド サブエージェントで f を押します。サブエージェントの出力がインラインで表示されます。
サブエージェントをバックグラウンドに移した時点で、親エージェントのツール呼び出しはすでに完了しているため、親エージェントは独立して処理を続行します。サブエージェントの結果は親エージェントの現在のパイプラインには反映されませんが、完了すると通知されます。
実行中のサブエージェントは、次の 2 つの方法でキャンセルできます。
サブエージェントパネルから: パネルを開き、実行中のサブエージェントで x を押します。フォアグラウンドのサブエージェント: 現在実行中のフォアグラウンドのサブエージェントをキャンセルするには、Ctrl +C または Esc を押します。
キャンセルされたサブエージェント、失敗したサブエージェント、または完了したサブエージェントは、新しいプロンプトで再開できます。エージェントにサブエージェントの再開を依頼すると、中断したところから続行します。再開したサブエージェントは常にフォアグラウンド で実行されるため、以前に拒否されたツール呼び出しも承認できます。
これは特に次のような場合に便利です。
バックグラウンドで実行していたサブエージェントが、必要なツールの利用を拒否されたために失敗した場合 — フォアグラウンドで再開して、必要な権限を付与できます。
サブエージェントは完了したものの、その結果に基づいて追加のフォローアップ作業を行わせたい場合。
サブエージェントが途中でキャンセルされてしまい、続きを実行させたい場合。
デフォルトでは、サブエージェントは自身のサブエージェントを起動できません。起動できるのはルートエージェントのみです。無制限にネストされるのを防ぐため、サブエージェント内ではサブエージェント ツール (run_subagent と read_subagent) は無効になっています。
ただし、カスタム サブエージェントプロファイル では、フロントマターで max-nesting フィールドを設定することで、ネストした起動を有効にできます。この値はデフォルトの最大深度を上書きし、ツリーがその上限内に収まっている限り、サブエージェントが子サブエージェントを起動できるようにします。
たとえば、max-nesting: 3 を設定すると、次のチェーンが可能です。
Root agent (depth 0) └── Custom subagent (depth 1) — 子エージェントを生成可能 └── Child subagent (depth 2) — 子エージェントを生成可能 └── Grandchild subagent (depth 3) — 生成不可（深さの上限に達した）
ネストされたサブエージェントは、コストを大幅に増やす可能性があります。ネストが1段深くなるごとに、それぞれ独自のコンテキストウィンドウと推論呼び出しを持つ追加のエージェントが生成されます。この機能は、必要性をよく検討したうえで利用してください。
カスタムサブエージェントは実験的な機能 です。形式、動作、設定オプションは今後のリリースで変更される可能性があります。
組み込みのsubagent_exploreおよびsubagent_generalプロファイルに加えて、独自のカスタムサブエージェントプロファイルを定義できます。カスタムサブエージェントを使用すると、それぞれに固有のシステムプロンプト、ツールの制限、モデルのオーバーライド、権限を持つ、ワークフロー内の特定のタスク向けに最適化された専用ワーカーを作成できます。
カスタムサブエージェントは、agents/ 配下の名前付きディレクトリ内にある AGENT.md ファイルとして定義されます。ディレクトリ名がプロファイルの識別子になります。
.devin/agents/ └── reviewer/ └── AGENT.md
以下もサポートされています: .agents/agents/ └── reviewer/ └── AGENT.md
# Linux/macOS ~/.config/devin/agents/ └── reviewer/ └── AGENT.md # Windows %APPDATA%\devin\agents\ └── reviewer\ └── AGENT.md
AGENT.md ファイルは、skills と同じ YAML フロントマター を使用し、その後にサブエージェントのシステムプロンプトが続きます:--- name : reviewer description : Reviews code changes for correctness and style model : sonnet allowed-tools : - read - grep - glob - exec permissions : allow : - Exec(git diff) - Exec(git log) deny : - write - edit --- You are a code review subagent. Your job is to review code changes thoroughly and report findings back to the parent agent. Focus on: 1. Correctness — logic errors, edge cases, off-by-one mistakes 2. Security — potential vulnerabilities 3. Style — consistency with the rest of the codebase 4. Performance — obvious inefficiencies Always cite specific file paths and line numbers in your findings.
フィールド 型 デフォルト 説明 namestring ディレクトリ名 プロファイルの識別子 (組み込みプロファイルと重複してはいけません) descriptionstring なし プロファイル選択時にエージェントに表示されます modelstring デフォルトのサブエージェントモデル このサブエージェントが利用するモデルを上書きします allowed-toolslist すべてのツール サブエージェントが利用できるツールを制限します permissionsobject 継承 権限の上書き設定 (allow、deny、ask) max-nestinginteger なし 最大ネスト深度を上書きし、このサブエージェントが自身のサブエージェントを生成できるようにします
定義すると、カスタム サブエージェントプロファイルは組み込みプロファイルと並んで表示されます。エージェントは利用可能な各プロファイルの説明を確認し、サブエージェント を起動する際に最も適切なものを選択します。また、プロファイル名を指定して、特定のプロファイルを利用するようエージェントに依頼することもできます (例: 「reviewer サブエージェント を使ってこのコードをレビューして」) 。
組み込みプロファイル名 (例: subagent_explore, subagent_general) と競合するカスタム サブエージェントプロファイルは、警告が表示されたうえでスキップされます。
カスタムサブエージェントは、Claude Code のエージェント形式からもインポートできます。
Source File Pattern .claude/agents/*.md各 .md ファイルがサブエージェントのプロファイルになります
Claude Code のエージェントファイルでは、フロントマター に allowed-tools ではなく tools を使用します。どちらの形式も自動的にサポートされます。
--- name : researcher description : Deep codebase research and architecture analysis model : sonnet allowed-tools : - read - grep - glob --- You are a research subagent specializing in codebase exploration. Your job is to thoroughly investigate a topic and report back with: - Relevant files and their purposes - Architecture patterns and dependencies - Code flow traces with specific line references Be exhaustive — search broadly and follow references.
--- name : test-runner description : Runs tests and reports results allowed-tools : - read - grep - glob - exec permissions : allow : - Exec(npm run test) - Exec(cargo nextest) - Exec(pytest) --- You are a test runner subagent. Run the relevant test suites and report: - Which tests passed and failed - Failure messages and stack traces - Suggestions for fixing failures
