Visual Studio Code 中的子代理 (Subagents)

在處理複雜任務時，您可以將子任務委派給子代理。子代理是一個獨立的 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.

呼叫子代理

代理啟動與使用者呼叫

子代理通常是由代理啟動的，而非由使用者在聊天中直接呼叫。若要允許主代理呼叫子代理，請確保已啟用 runSubagent 工具。

預設情況下，子代理本身無法呼叫進一步的子代理。若要啟用遞迴巢狀，請啟用 chat.subagents.allowInvocationsFromSubagents 在 VS Code 中開啟 在 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.

在提示詞指令中，您可以透過建議針對特定子任務進行隔離研究或平行分析，來暗示代理使用子代理。

執行自訂代理作為子代理

預設情況下，子代理會繼承主聊天階段的代理，並使用相同的模型與工具。若要為子代理定義特定行為，請使用自訂代理。自訂代理可以指定自己的模型、工具與指令。當作為子代理使用時，這些設定會覆寫從主階段繼承的預設值。

主代理在呼叫子代理時也可以請求特定模型。詳情請參閱子代理的模型選擇章節。

控制子代理呼叫

您可以透過兩個 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 的自訂代理皆可作為子代理使用。如果兩個或多個代理具有類似的名稱或描述，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 在 VS Code 中開啟 在 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 中的聊天階段