> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# サブエージェント
> フォアグラウンドまたはバックグラウンドで動作する独立したサブエージェントにタスクを委任
サブエージェントを利用すると、メインのエージェントが独立したワーカーを立ち上げて、サブタスクを処理できます。サブエージェントは親エージェントとツールおよびコードベースの前提情報を共有しますが、独自の会話チェーンで動作し、親の会話履歴は引き継ぎません。これは、コードベースの調査、テストの実行、機能の並行実装など、独立して集中的に進めることで効果が高まるタスクに役立ちます。
エージェントに明示的にサブエージェントを利用するよう依頼することもできます (例: 「サブエージェントで認証の仕組みを調査して」) 。また、独立して進めたほうが効果的だと判断した場合は、エージェント自身が委任することもあります。
私たちの測定では、**サブエージェント**は**全体的なコーディング性能を向上させる**と**同時に**、**コストを削減**します。
***
## サブエージェントの仕組み
エージェントがサブエージェントを起動すると、利用可能な**サブエージェントプロファイル**のいずれかを選択し、そのサブエージェントをフォアグラウンドとバックグラウンドのどちらで実行するかを決めます。サブエージェントは次の2つのモードで実行できます。
セッション内でインライン実行されます。親エージェントは一時停止し、サブエージェントの完了を待ってから処理を続けます。ツール呼び出しが発生した場合は、その都度承認または拒否できます。
親エージェントが作業を続ける間、並行して実行されます。サブエージェントが完了すると、親エージェントに自動的に通知されます。承認されていないツールは自動的に拒否されます。
サブエージェントの生の出力は直接表示されません。サブエージェントが完了すると、親エージェントが結果を読み取り、重要な検出結果とアクションを要約して知らせます。
### サブエージェントのコスト
サブエージェントはそれぞれ独立したエージェントセッションとして実行され、各自の前提情報ウィンドウと推論呼び出しを持つため、親とは別にコストが発生します。親の費用に含まれるのは親自身の作業分のみで、親が生成したサブエージェントごとに追加の使用量が加算されます。
プロンプトベースのプランでは、各サブエージェントでもユーザーメッセージと同様に追加のクレジットが消費されます。消費されるクレジット数はサブエージェントが利用するモデルによって異なるため、複数のサブエージェントを生成するタスク (またはそれらを[nest](/ja/cli/subagents#nesting-depth)するタスク) では、より多くのクレジットが消費されます。
コストはサブエージェントの数に応じて増えるため、多数のサブエージェントに分岐するタスク (またはそれらを[入れ子に](#nesting-depth)するタスク) ほど高コストになります。並列実行や前提情報を絞り込むことのメリットが追加コストに見合う場合に、サブエージェントを意図的に利用してください。
### Enterprise Controls
管理者は、org/enterprise 設定の **Default subagent model** 設定で、サブエージェントが利用するモデルと、サブエージェント自体を実行可能にするかどうかを管理できます。
この設定では、Devin が開始するサブエージェントのセッションで利用されるモデルを制御できます。選択肢は次の 3 つです。
| オプション | 動作 |
| ----------------------------- | --------------------------------------------------- |
| **Subagent router (default)** | Devin が、タスクと親モデルに基づくデフォルトのルーティングによって、自動的にモデルを選択します。 |
| **A specific model** | タスクや親モデルに関係なく、すべてのサブエージェントを選択したモデルに固定します。 |
| **None** | サブエージェントを完全に無効化します — Devin はサブエージェントを一切起動しません。 |
***
## サブエージェントプロファイル
各サブエージェントは、その機能を決定する特定のプロファイルで実行されます。組み込みプロファイルは 2 種類あります。
| プロファイル | 説明 | ツールアクセス |
| ------------------ | ------------------- | ------------------------------------------------------------------------------------ |
| `subagent_explore` | 読み取り専用でのコードベース探索と調査 | 読み取り専用のコードベース ツールに加えて Web 検索を利用可能。ファイルの編集や任意の URL の取得はできません (フォアグラウンドかバックグラウンドかを問わず) |
| `subagent_general` | コード変更を含む汎用タスク | フォアグラウンドではすべてのツールを利用可能、バックグラウンドでは事前承認済みのツールのみ利用可能 |
エージェントは、タスクに応じて適切なプロファイルを自動的に選択します。explore サブエージェントは調査や理解に最適で、general サブエージェントは変更を加えられます。
独自のカスタム サブエージェントプロファイルを定義することもできます。詳細は、以下の [カスタムサブエージェント](#custom-subagents) を参照してください。
***
## ツールの権限
ツールの権限の動作は、サブエージェントがフォアグラウンドで実行されているか、バックグラウンドで実行されているかによって異なります。
* **フォアグラウンドのサブエージェント** はメインのエージェントと同様に動作し、通常どおりツール呼び出しを承認または拒否するよう求められます。
* **バックグラウンドのサブエージェント** は、現在のセッション中にすでに付与したツールの権限を引き継ぎます。事前に承認されていないツールは自動的に拒否されます。バックグラウンドのサブエージェントが新しい権限の承認を求めることはできません。
バックグラウンドのサブエージェントが、必要なツールが拒否されたために失敗した場合は、そのサブエージェントをフォアグラウンドで再開して、必要な権限を承認できます。詳しくは、以下の [Resuming Subagents](#resuming-subagents) を参照してください。
***
## サブエージェントの監視
### サブエージェントのインジケーター
バックグラウンドでサブエージェントが実行されている場合は、入力欄の下にステータスを示すインジケーターが表示されます。入力欄で ↓ を押すとインジケーターに移動でき、Enter を押すとサブエージェントパネルを開けます。
フォアグラウンドでサブエージェントが実行されている場合、スピナーには **「サブエージェント実行中 · Ctrl+B でバックグラウンド実行」** と表示されます。
### サブエージェントパネル
サブエージェントパネルでは、アクティブなサブエージェントと完了済みのサブエージェントをすべて閲覧・管理できます。各サブエージェントのプロファイル、タイトル、ステータス、経過時間、ツール呼び出し回数が表示されます。
***
## フォアグラウンド / バックグラウンドの切り替え
サブエージェントの実行中に、フォアグラウンドとバックグラウンドを切り替えられます。
* **フォアグラウンドのサブエージェントをバックグラウンドに切り替える:** フォアグラウンドのサブエージェントの実行中に Ctrl+B を押します。サブエージェントはバックグラウンドで処理を続け、親エージェントが再開します。
* **バックグラウンドのサブエージェントをフォアグラウンドに切り替える:** サブエージェントパネルを開き、実行中のバックグラウンド サブエージェントで f を押します。サブエージェントの出力がインラインで表示されます。
サブエージェントをバックグラウンドに移した時点で、親エージェントのツール呼び出しはすでに完了しているため、親エージェントは独立して処理を続行します。サブエージェントの結果は親エージェントの現在のパイプラインには反映されませんが、完了すると通知されます。
***
## サブエージェントのキャンセル
実行中のサブエージェントは、次の 2 つの方法でキャンセルできます。
1. **サブエージェントパネルから:** パネルを開き、実行中のサブエージェントで x を押します。
2. **フォアグラウンドのサブエージェント:** 現在実行中のフォアグラウンドのサブエージェントをキャンセルするには、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` ファイルとして定義されます。ディレクトリ名がプロファイルの識別子になります。
```text theme={null}
.devin/agents/
└── reviewer/
└── AGENT.md
```
以下もサポートされています:
```text theme={null}
.agents/agents/
└── reviewer/
└── AGENT.md
```
```text theme={null}
# Linux/macOS
~/.config/devin/agents/
└── reviewer/
└── AGENT.md
# Windows
%APPDATA%\devin\agents\
└── reviewer\
└── AGENT.md
```
### AGENT.md の形式
`AGENT.md` ファイルは、skills と同じ YAML フロントマター を使用し、その後にサブエージェントのシステムプロンプトが続きます:
```markdown theme={null}
---
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.
```
### Frontmatter のフィールド
| フィールド | 型 | デフォルト | 説明 |
| --------------- | ------- | ----------------- | ---------------------------------------------------------------------------- |
| `name` | string | ディレクトリ名 | プロファイルの識別子 (組み込みプロファイルと重複してはいけません) |
| `description` | string | なし | プロファイル選択時にエージェントに表示されます |
| `model` | string | デフォルトのサブエージェントモデル | このサブエージェントが利用するモデルを上書きします |
| `allowed-tools` | list | すべてのツール | サブエージェントが利用できるツールを制限します。`ask_user_question` は付与できません。これは常にサブエージェントには許可されません。 |
| `permissions` | object | 継承 | 権限の上書き設定 (`allow`、`deny`、`ask`) |
| `max-nesting` | integer | なし | 最大ネスト深度を上書きし、このサブエージェントが自身のサブエージェントを生成できるようにします |
### カスタムサブエージェント の利用方法
定義すると、カスタム サブエージェントプロファイルは組み込みプロファイルと並んで表示されます。エージェントは利用可能な各プロファイルの説明を確認し、サブエージェント を起動する際に最も適切なものを選択します。また、プロファイル名を指定して、特定のプロファイルを利用するようエージェントに依頼することもできます (例: 「reviewer サブエージェント を使ってこのコードをレビューして」) 。
組み込みプロファイル名 (例: `subagent_explore`, `subagent_general`) と競合するカスタム サブエージェントプロファイルは、警告が表示されたうえでスキップされます。
### 他のツールからのインポート
カスタムサブエージェントは、Claude Code のエージェント形式からもインポートできます。
| Source | File Pattern |
| --------------------- | --------------------------------- |
| `.claude/agents/*.md` | 各 `.md` ファイルがサブエージェントのプロファイルになります |
Claude Code のエージェントファイルでは、フロントマター に `allowed-tools` ではなく `tools` を使用します。どちらの形式も自動的にサポートされます。
### 使用例
#### 読み取り専用調査エージェント
```markdown theme={null}
---
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.
```
#### テスト実行エージェント
```markdown theme={null}
---
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
```