Visual Studio Code のサブエージェント

複雑なタスクに取り組む際、サブタスクをサブエージェントに委任できます。サブエージェントは、トピックの調査、コードの分析、変更点のレビューなどの集中的な作業を実行し、その結果をメインエージェントに報告する独立した AI エージェントです。

サブエージェントの概念 (コンテキスト分離、同期および並列実行) の背景については、「エージェントの概念」を参照してください。

この記事では、VS Code でサブエージェントを使用する方法について、使用シナリオ、呼び出しパターン、カスタムエージェントをサブエージェントとして実行する方法を含めて説明します。

ユーザーが見るもの

サブエージェントが実行されると、チャットに折りたたみ可能なツール呼び出しとして表示されます。デフォルトでは、サブエージェントは折りたたまれた状態で表示されます。

• カスタムエージェントの名前 (指定した場合)
• 現在実行中のツール (例: 「ファイルを読み込み中...」または「コードベースを検索中...」)

サブエージェントのツール呼び出しを選択して展開し、サブエージェントが行ったすべてのツール呼び出し、サブエージェントに渡されたプロンプト、返された結果を含む詳細をすべて表示できます。

この表示により、中間ステップでメインの会話を散らかすことなく、表示する詳細の量を制御できます。

使用シナリオ

以下のシナリオは、サブエージェントが AI 支援開発ワークフローをどのように改善できるかを示しています。

Perform isolated research into different OAuth 2.0 implementation patterns for Node.js applications.
Compare each against the current implementation and return a recommendation with pros and cons.

Analyze this codebase for refactoring opportunities. Perform these tasks in parallel:
1. Find duplicate code patterns
2. Identify unused exports and dead code
3. Review error handling consistency
4. Check for security vulnerabilities

Compile the findings into a prioritized action plan.

I need to implement caching for this API. Do some isolated research on these three approaches:
1. Design a Redis-based caching solution
2. Design an in-memory caching solution with LRU eviction
3. Design a hybrid approach with tiered caching

Compare the results and recommend the best approach for our use case.

Review the changes in this PR from different angles. Perform these reviews in parallel:
- Run the security-reviewer agent to check for vulnerabilities
- Run the performance-reviewer agent to identify bottlenecks
- Run the accessibility-reviewer agent to verify a11y compliance

Consolidate findings into a single review summary.

I need to evaluate the error handling in our payment service.
Run two subagents in parallel, each with a different model:
1. Use GPT-4o to review the code for error handling gaps
2. Use Claude Sonnet 4.6 to review the code for error handling gaps

Compare their findings and highlight where they agree and disagree.

サブエージェントを呼び出す

エージェントが開始 vs. ユーザーが呼び出し

サブエージェントは通常、エージェントによって開始され、チャットでユーザーが直接呼び出すものではありません。メインエージェントがサブエージェントを呼び出せるようにするには、runSubagent ツールが有効になっていることを確認してください。

デフォルトでは、サブエージェント自体はさらにサブエージェントを呼び出すことはできません。再帰的なネストを有効にするには、 chat.subagents.allowInvocationsFromSubagents Open in VS Code Open in VS Code Insiders 設定を有効にします。ネストされたサブエージェントで詳細をご覧ください。

メインエージェントは、コンテキスト分離がいつ役立つかを決定します。タスクごとに「サブエージェントを実行」と手動で入力する必要はありません。このパターンは次のように機能します。

1. あなた (またはカスタムエージェントの指示) は複雑なタスクを説明します。
2. メインエージェントは、孤立したコンテキストから恩恵を受けるタスクの一部を認識します。
3. エージェントはサブエージェントを開始し、関連するサブタスクのみを渡します。
4. サブエージェントは自律的に動作し、要約を返します。
5. メインエージェントは結果を組み込み、処理を続行します。

孤立した調査や並列分析を提案するようにプロンプトを記述することで、サブエージェントによる委任を希望することを示唆できます。メインエージェントはサブエージェントを開始し、タスクをそれに渡し、最終結果のみを受け取ります。

サブエージェントのパフォーマンスを最適化するには、タスクと期待される出力を明確に定義します。これにより、サブエージェントは不要なコンテキストをメインエージェントに返すことなく、特定の目標に集中できます。

サブエージェントを呼び出すプロンプトを構造化する方法の例については、「使用シナリオ」セクションを参照してください。

プロンプトファイルでサブエージェントを呼び出す

プロンプトファイル内でサブエージェントを呼び出すには、runSubagent または agent ツールが tools frontmatter プロパティに含まれていることを確認してください。

---
name: document-feature
tools: ['agent', 'read', 'search', 'edit']
---
Run a subagent to research the new feature implementation details and return only information relevant for user documentation.
Then update the docs/ folder with the new documentation.

プロンプトの指示で、特定のサブタスクに対して孤立した調査や並列分析を提案することで、エージェントにサブエージェントを使用するようヒントを与えることができます。

カスタムエージェントをサブエージェントとして実行する

デフォルトでは、サブエージェントはメインチャットセッションからエージェントを継承し、同じモデルとツールを使用します。サブエージェントの特定の動作を定義するには、カスタムエージェントを使用します。カスタムエージェントは、独自のモデル、ツール、および指示を指定できます。サブエージェントとして使用される場合、これらの設定はメインセッションから継承されたデフォルト設定をオーバーライドします。

メインエージェントは、サブエージェントを呼び出すときに特定のモデルを要求することもできます。サブエージェントのモデル選択セクションで詳細をご覧ください。

サブエージェントの呼び出しを制御する

2つの frontmatter プロパティを使用して、カスタムエージェントがどのように呼び出されるかを制御できます。

• user-invocable: エージェントがチャットのエージェントドロップダウンに表示されるかどうかを制御します (デフォルトは true)。サブエージェントとしてのみアクセス可能なエージェントを作成するには、false に設定します。
• disable-model-invocation: エージェントが他のエージェントによってサブエージェントとして呼び出されるのを防ぎます (デフォルトは false)。エージェントがユーザーによって明示的にトリガーされるべき場合に true に設定します。

例えば、サブエージェントとしてのみ使用できるエージェント (ドロップダウンには表示されない) を作成するには、

---
name: internal-helper
user-invocable: false
---

This agent can only be invoked as a subagent.

カスタムエージェントをサブエージェントとして実行するには、サブエージェントにカスタムエージェントまたは組み込みエージェントを使用するよう AI にプロンプトします。例：

• このプロジェクトに最適な認証方法を調査するために、Research エージェントをサブエージェントとして実行します。
• サブエージェントで Plan エージェントを使用して、myfeature の実装計画を作成します。次に、その計画を plans/myfeature.plan.md に保存します。

サブエージェントのモデル選択

サブエージェントが実行される際、モデルは以下の優先順位で決定されます。

1. 明示的なモデルパラメータ: メインエージェントが runSubagent ツールを呼び出す際に、モデルを直接指定します。
2. エージェント構成モデル: カスタムエージェントの .agent.md frontmatter 内の model プロパティ。
3. メインモデル: 親会話を実行しているモデル。

サブエージェントに特定のモデルを要求するには、プロンプトにモデルの好みを記述します。

• Claude Sonnet 4.6 を使用してサブエージェントを実行し、このコードベースの認証パターンを調査します。
• サブエージェントで GPT-4o を使用して、このモジュールのパフォーマンスを分析します。

カスタムエージェントの指示でモデルの好みを定義して、サブエージェントのタスクを常に特定のモデルにルーティングすることもできます。

使用できるサブエージェントを制限する (実験的)

デフォルトでは、disable-model-invocation: true を持たないすべてのカスタムエージェントは、サブエージェントとして使用できます。2つ以上のエージェントが類似した名前または説明を持っている場合、AI は意図しないエージェントを選択する可能性があります。

メインエージェントの frontmatter で agents プロパティを指定し、許可されたカスタムエージェントのリストを提供することで、サブエージェントとして使用できるカスタムエージェントを制限できます。

agents プロパティは以下を受け入れます。

• 特定のエージェントのみを許可するためのエージェント名のリスト (例: ['Edit', 'Search'])
• 利用可能なすべてのエージェントを許可するための * (デフォルトの動作)
• サブエージェントの使用を禁止するための空の配列 []

例えば、テスト駆動開発 (TDD) エージェントは、Red、Green、Refactor エージェントのみをサブエージェントとして使用すべきです。制限されていない場合、TDD エージェントは、特殊な TDD エージェントの代わりに、テストを実装するために汎用的なコーディングエージェントを選択する可能性があります。

---
name: TDD
tools: ['agent']
agents: ['Red', 'Green', 'Refactor']
---
Implement the following feature using test-driven development. Use subagents to guide the following steps:
1. Use the Red agent to write failing tests
2. Use the Green agent to implement code to pass the tests
3. Use the Refactor agent to improve the code quality

ネストされたサブエージェント

デフォルトでは、サブエージェントはさらにサブエージェントを生成できません。これは、エージェントが誤ってループ内で自身を呼び出した場合の無限再帰を防ぎます。ただし、一部のワークフローでは再帰的な委任がメリットをもたらします。例えば、大きなタスクを小さなピースに分割し、各ピースを自身に委任する分割統治エージェントなどです。

ネストされたサブエージェントを有効にするには、 chat.subagents.allowInvocationsFromSubagents Open in VS Code Open in VS Code Insiders 設定 (デフォルトは false) を有効にします。有効にすると、サブエージェントは最大ネスト深度 5 まで自身のサブエージェントを生成できます。

例: 再帰エージェント

再帰エージェントは、自身の agents プロパティに自身をリストします。これにより、エージェントが問題を小さな部分に分割し、各部分を自身の新しいインスタンスに委任する分割統治パターンが可能になります。

---
name: RecursiveProcessor
tools: ['agent', 'read', 'search']
agents: [RecursiveProcessor]
argument-hint: A list of items to process
---

You process a list of items by dividing and conquering:
- If the list has more than 4 items, split it in half and delegate each half to a RecursiveProcessor subagent.
- If the list has 4 or fewer items, process the items directly.
- Merge the results from each subagent into a final result.

オーケストレーションパターン

サブエージェントは、コーディネーターエージェントが専門のワーカーエージェントに作業を委任するオーケストレーションパターンを可能にします。このアプローチは、各エージェントが最も得意なことに集中しながら、洗練されたワークフローを構築するのに役立ちます。

コーディネーターとワーカーのパターン

コーディネーターエージェントは全体のタスクを管理し、サブタスクを専門のサブエージェントに委任します。各ワーカーエージェントは、カスタマイズされたツールセットを持つことができます。例えば、計画およびレビューエージェントは読み取り専用アクセスのみを必要とし、実装者は編集機能が必要になります。

---
name: Feature Builder
tools: ['agent', 'edit', 'search', 'read']
agents: ['Planner', 'Plan Architect', 'Implementer', 'Reviewer']
---
You are a feature development coordinator. For each feature request:

1. Use the Planner agent to break down the feature into tasks.
2. Use the Plan Architect agent to validate the plan against codebase patterns.
3. If the architect identifies reusable patterns or libraries, send feedback to the Planner to update the plan.
4. Use the Implementer agent to write the code for each task.
5. Use the Reviewer agent to check the implementation.
6. If the reviewer identifies issues, use the Implementer agent again to apply fixes.

Iterate between planning and architecture, and between review and implementation, until each phase converges.

ワーカーエージェントはそれぞれ独自のツールアクセスを定義し、より限定的な焦点を持つため、より高速または費用対効果の高いモデルを選択できます。

---
name: Planner
user-invocable: false
tools: ['read', 'search']
---
Break down feature requests into implementation tasks. Incorporate feedback from the Plan Architect.

---
name: Plan Architect
user-invocable: false
tools: ['read', 'search']
---
Validate plans against the codebase. Identify existing patterns, utilities, and libraries that should be reused. Flag any plan steps that duplicate existing functionality.

---
name: Implementer
user-invocable: false
model: ['Claude Haiku 4.5 (copilot)', 'Gemini 3 Flash (Preview) (copilot)']
---
Write code to complete assigned tasks.

このパターンは、コーディネーターのコンテキストを高レベルのワークフローに集中させつつ、各ワーカーエージェントが特定のジョブに対してクリーンなコンテキストと適切な権限を持つようにします。

多角的コードレビュー

コードレビューは複数の視点から恩恵を受けます。一度のレビューでは見落とされがちな問題も、異なる視点から見ると明らかになることがあります。サブエージェントを使用して各レビュー視点を並行して実行し、その結果を統合します。

---
name: Thorough Reviewer
tools: ['agent', 'read', 'search']
---
You review code through multiple perspectives simultaneously. Run each perspective as a parallel subagent so findings are independent and unbiased.

When asked to review code, run these subagents in parallel:
- Correctness reviewer: logic errors, edge cases, type issues.
- Code quality reviewer: readability, naming, duplication.
- Security reviewer: input validation, injection risks, data exposure.
- Architecture reviewer: codebase patterns, design consistency, structural alignment.

After all subagents complete, synthesize findings into a prioritized summary. Note which issues are critical versus nice-to-have. Acknowledge what the code does well.

このパターンが機能するのは、各サブエージェントが他の視点が見つけたものに縛られることなく、新鮮な状態でコードに取り組むためです。この例では、オーケストレーターがプロンプトを通じて各サブエージェントのフォーカス領域を形成します。これは、追加のエージェントファイルを必要としない軽量なアプローチです。

関連リソース

• エージェントの概要 - VS Code のさまざまなエージェントの種類について学習します。
• カスタムエージェント - 独自の AI エージェントを作成します。
• チャットセッション - VS Code でチャットセッションを管理します。