VS Code 中的自訂代理 (Custom agents)

自訂代理讓您能夠將 AI 設定為採用針對特定開發角色和任務所量身打造的各種角色。例如，您可以為安全性審查員、規劃人員、解決方案架構師或其他專業角色建立代理。每個角色都可以擁有自己的行為、可用工具和指令。

您也可以使用「接續交辦」在代理之間建立引導式工作流程。透過單次選擇，即可從一個專門的代理無縫轉換到另一個。例如，直接從規劃代理移轉至實作代理，或將相關內容交辦給程式碼審查員。

本文介紹如何在 VS Code 中建立與管理自訂代理。

什麼是自訂代理？

內建代理為 VS Code 中的聊天提供了通用配置。若要獲得更客製化的聊天體驗，您可以建立自己的自訂代理。

自訂代理包含一組指令與工具，當您切換至該代理時即會套用。例如，「規劃 (Plan)」代理可以包含用於產生實作計畫的指令，且僅使用唯讀工具。透過建立自訂代理，您可以快速切換至該特定配置，而不必每次都手動選取相關工具與指令。

自訂代理定義於 .agent.md Markdown 檔案中，可以儲存在您的工作區中供他人使用，或儲存在您的使用者設定檔中，以便在不同的工作區中重複使用。

您可以在 背景代理 和 雲端代理 中重複使用您的自訂代理，讓您能使用相同的專門配置來執行自動化任務。

為什麼要使用自訂代理？

不同的任務需要不同的能力。規劃代理可能只需要用於研究與分析的唯讀工具，以防止意外的程式碼變更；而實作代理則需要完整的編輯能力。自訂代理讓您可以精確指定每個任務可用的工具，確保 AI 具備適合該工作的能力。

自訂代理還讓您可以提供專門的指令，定義 AI 的運作方式。例如，規劃代理可以指示 AI 收集專案內容並產生詳細的實作計畫，而程式碼審查代理則可能專注於識別安全性漏洞並建議改進。這些專門指令可確保您每次切換到該代理時，都能獲得一致且符合任務需求的回答。

接續交辦 (Handoffs)

接續交辦 (Handoffs) 使您能夠建立引導式順序工作流程，在代理之間進行轉換，並提供建議的後續步驟。在聊天回應完成後，會出現接續交辦按鈕，讓使用者帶著相關內容與預先填寫的提示詞轉移至下一個代理。

接續交辦對於編排多步驟工作流程非常有用，讓開發人員在進入下一步之前，能針對每一步進行審查與核准。例如：

• 規劃 → 實作：在規劃代理中產生計畫，然後交辦給實作代理以開始撰寫程式碼。
• 實作 → 審查：完成實作後，切換至程式碼審查代理以檢查品質與安全性問題。
• 撰寫失敗測試 → 撰寫通過測試：產生比大型實作更容易審查的失敗測試，然後交辦至執行實作必要的程式碼變更，使這些測試通過。

若要在您的代理檔案中定義接續交辦，請將其新增至前言 (frontmatter)。每個接續交辦都會指定目標代理、按鈕標籤以及選用的發送提示詞：

---
description: Generate an implementation plan
tools: ['search', 'web']
handoffs:
  - label: Start Implementation
    agent: implementation
    prompt: Now implement the plan outlined above.
    send: false
    model: GPT-5.2 (copilot)
---

當使用者看到接續交辦按鈕並選擇它時，他們會切換至預先填寫好提示詞的目標代理。如果設定 send: true，系統會自動提交該提示詞以啟動下一個工作流程步驟。

自訂代理檔案位置

您可以為特定工作區或使用者層級定義自訂代理，定義後該代理將在您所有的工作區中皆可使用。下表列出了根據範圍劃分的自訂代理預設檔案位置。您可以使用 chat.agentFilesLocations ... 設定來配置工作區自訂代理檔案的額外位置。

若要在使用者資料中建立自訂代理，請使用「聊天自訂編輯器 (Chat Customizations editor)」或使用 Chat: New Custom Agent 命令。

自訂代理檔案結構

自訂代理檔案為 Markdown 檔案，使用 .agent.md 副檔名，並具有下列結構。

標頭 (Header)（選用）

標頭格式為 YAML 前言，包含下列欄位：

內文 (Body)

自訂代理檔案內文包含以 Markdown 格式編寫的自訂代理實作。您可以在此提供特定的提示詞、指引或任何您希望 AI 在此自訂代理運作時遵守的其他相關資訊。

您可以使用 Markdown 連結參考其他檔案，例如重複使用指令檔案。

若要在內文中參考代理工具，請使用 #tool:<tool-name> 語法。例如，若要參考 fetch 工具，請使用 #tool:web/fetch。

當您在聊天檢視中選擇該自訂代理時，自訂代理檔案內文中的指引會被置於使用者聊天提示詞之前。

範例

---
description: Generate an implementation plan for new features or refactoring existing code.
name: Planner
tools: ['web/fetch', 'search/codebase', 'search/usages']
model: ['Claude Opus 4.5', 'GPT-5.2']  # Tries models in order
handoffs:
  - label: Implement Plan
    agent: agent
    prompt: Implement the plan outlined above.
    send: false
---
# Planning instructions
You are in planning mode. Your task is to generate an implementation plan for a new feature or for refactoring existing code.
Don't make any code edits, just generate a plan.

The plan consists of a Markdown document that describes the implementation plan, including the following sections:

* Overview: A brief description of the feature or refactoring task.
* Requirements: A list of requirements for the feature or refactoring task.
* Implementation Steps: A detailed list of steps to implement the feature or refactoring task.
* Testing: A list of tests that need to be implemented to verify the feature or refactoring task.

---
name: Feature Builder
description: Build features by researching first, then implementing
tools: ['agent']
agents: ['Researcher', 'Implementer']
---
You are a feature builder. For each task:
1. Use the Researcher agent to gather context and find relevant patterns in the codebase
2. Use the Implementer agent to make the actual code changes based on research findings

---
name: Researcher
description: Research codebase patterns and gather context
tools: ['search/codebase', 'web/fetch', 'search/usages']
---
Research thoroughly using read-only tools. Return a summary of findings.

---
name: Implementer
description: Implement code changes based on provided context
tools: ['edit', 'read/terminalLastCommand']
---
Implement changes following existing code patterns. Make minimal, focused edits.

---
name: "Strict Formatter"
description: "Agent that auto-formats code after every edit"
hooks:
  PostToolUse:
    - type: command
      command: "./scripts/format-changed-files.sh"
---

You are a code editing agent. After making changes, files are automatically formatted.

Claude 代理格式

.claude/agents 資料夾中的代理檔案使用純 .md 檔案，並支援 Claude 特定的前言屬性：

VS Code 會將 Claude 特定的工具名稱對應到對應的 VS Code 工具。同時支援 VS Code .agent.md 格式（工具使用 YAML 陣列）與 Claude 格式（使用逗號分隔字串）。

建立自訂代理

您可以在您的工作區或使用者設定檔中建立自訂代理檔案。

1. 在聊天檢視中，選擇 Configure Chat（齒輪圖示）開啟「聊天自訂編輯器」，然後選擇 Agents 頁籤。

2. 從下拉式選單選擇 New Agent (Workspace) 或 New Agent (User)，取決於您要儲存代理檔案的位置。

   

   或者，從命令面板執行 Chat: New Custom Agent 命令 (⇧⌘P)。

   提示

   您可以使用 chat.agentFilesLocations ... 設定來配置 VS Code 搜尋自訂代理檔案的額外位置。這對於在專案間共用代理或將其保留在工作區之外的中心位置非常有用。

3. 選擇位置並為自訂代理輸入檔案名稱。這是出現在代理下拉式選單中的預設名稱。

4. 在新建立的 .agent.md 檔案中提供自訂代理的詳細資料。

   • 填寫檔案頂部的 YAML 前言，以配置自訂代理的名稱、說明、工具與其他設定。
   • 在檔案內文中新增自訂代理的指令。

您可以透過在「聊天自訂編輯器」中開啟現有的自訂代理來進行修改。

使用 AI 產生自訂代理

您可以根據角色描述使用 AI 產生自訂代理。在代理模式的聊天中輸入 /create-agent 並描述您想要的角色（例如：「安全性審查代理」）。代理會提出釐清問題並產生一個包含適當工具、指令與前言的 .agent.md 檔案。

您也可以從進行中的對話中提取自訂代理。例如，在多次除錯後，詢問「為這類任務建立一個代理」，即可將工作流程捕獲為可重複使用的自訂代理。

您也可以從「聊天自訂編輯器」中，透過下拉式選單選擇 Generate Agent 來產生自訂代理。

自訂代理下拉式選單

如果您有多個自訂代理，您可以自訂哪些代理顯示在下拉式選單中。若要顯示或隱藏特定的自訂代理：

1. 從代理下拉式選單中選擇 Configure Custom Agents。

2. 將滑鼠懸停在清單中的自訂代理上，然後選擇眼睛圖示以顯示或隱藏它。

工具清單優先順序

當您同時在自訂代理和提示詞檔案中使用 tools 時，提示詞檔案的工具優先權較高。如需完整的優先順序，請參閱提示詞檔案說明文件中的 工具清單優先順序。

跨團隊共用自訂代理

若要跨團隊共用自訂代理，您可以建立工作區層級的自訂代理 (.github/agents 資料夾)。若您希望在組織內的多個工作區共用自訂代理，則可以在 GitHub 組織層級定義它們。

VS Code 會自動偵測您帳戶有權存取的組織層級自訂代理。這些代理會與內建代理，以及您的個人與工作區自訂代理一起出現在聊天的代理下拉式選單中。

若要啟用組織層級自訂代理的探索，請將 github.copilot.chat.organizationCustomAgents.enabled ... 設為 true。

在 GitHub 說明文件中了解 如何為您的組織建立自訂代理。

常見問題

自訂代理與聊天模式 (Chat modes) 不同嗎？

自訂代理先前稱為「自訂聊天模式」。功能維持不變，但術語已更新，以更準確地反映其在針對特定任務自訂 AI 行為方面的用途。

如果您有現有的 .chatmode.md 檔案，請將其更名為 .agent.md 以轉換為新的自訂代理格式，並將其放置在正確的位置 ( chat.agentFilesLocations ...) 以繼續使用。

如何移除自訂代理？

若要將自訂代理從 VS Code 完全移除：

• 從您的工作區或使用者設定檔中刪除對應的 .agent.md 檔案。
• 從代理下拉式選單選擇 Configure Custom Agents，將滑鼠懸停在清單中的自訂代理上，並選擇垃圾桶圖示。

若要移除由擴充功能貢獻的自訂代理，您需要解除安裝提供該代理的擴充功能。若您不想解除安裝擴充功能，則可以從代理下拉式選單中隱藏該代理。請依照 自訂代理下拉式選單 中的步驟執行。

如何得知自訂代理的來源？

自訂代理可能來自不同來源：內建代理、您個人設定檔中定義的代理、目前工作區中定義的代理、組織定義的代理，或是由擴充功能貢獻的代理。

若要識別自訂代理的來源：

1. 從代理下拉式選單中選擇 Configure Custom Agents。
2. 將滑鼠懸停在清單中的自訂代理上，來源位置將會顯示在工具提示中。

安全性考量

自訂代理可以限制可用的工具，這讓您可以控制 AI 的行為。對於安全性敏感的工作流程，請建立僅使用唯讀工具的代理，以防止非預期的變更。在儲存庫中共用代理時，請審查工具清單與指令，以確保其遵循最小權限原則。

相關資源

• 使用代理進行規劃
• 使用自訂指令自訂 AI
• 建立可重複使用的提示詞檔案
• 在聊天中使用工具