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

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

您也可以使用「接續工作」(Handoffs) 在代理之間建立引導式工作流程。只需一個選擇，即可順暢地從一個專業代理轉換到另一個代理。例如，從規劃代理直接轉移到實作代理，或在具備相關上下文的情況下轉移給程式碼審核人員。

本文介紹如何在 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 在 VS Code 中開啟 在 VS Code Insiders 中開啟 設定來配置額外的檔案位置。

若要在使用者資料中建立自訂代理，請使用「代理自訂編輯器」或使用 **Chat: New Custom Agent** 指令。

自訂代理檔案結構

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

Header（可選）

Header 格式為 YAML Frontmatter，包含下列欄位：

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 特定的 Frontmatter 屬性：

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

建立自訂代理

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

1. 在聊天視圖中，選擇 **Configure Chat**（齒輪圖示）以開啟代理自訂編輯器，然後選擇 **Agents** 分頁。

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

   

   或者，從指令選擇區（Command Palette，⇧⌘P (Windows, Linux Ctrl+Shift+P)）執行 **Chat: New Custom Agent** 指令。

   提示

   您可以透過 chat.agentFilesLocations 在 VS Code 中開啟 在 VS Code Insiders 中開啟 設定來配置 VS Code 搜尋自訂代理檔案的其他位置。這對於在多個專案間共享代理，或將其保存在工作區之外的中心位置非常有用。

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

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

   • 填寫檔案頂部的 YAML Frontmatter，以設定自訂代理的名稱、說明、工具與其他設定。
   • 在檔案主體中新增自訂代理的指令。

您可以透過在代理自訂編輯器中開啟，來修改現有的自訂代理。

使用 AI 產生自訂代理

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

您也可以從正在進行的對話中提取自訂代理。例如，在多次除錯工作階段後，要求「製作一個用於此類任務的代理」，即可將該工作流程擷取為可重複使用的自訂代理。

您也可以從代理自訂編輯器中選擇 **Generate Agent**，來產生自訂代理。

自訂代理程式下拉式清單

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

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

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

工具清單優先順序

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

在團隊間共享自訂代理

若要在您的團隊間共享自訂代理，您可以建立工作區層級的自訂代理（.github/agents 資料夾）。如果您希望在組織內的多個工作區共享，可以在 GitHub 組織層級定義它們。

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

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

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

常見問題

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

自訂代理先前被稱為「自訂聊天模式」。功能保持不變，但術語已更新，以更好地反映其在自訂 AI 行為以執行特定任務方面的作用。

如果您有現有的 .chatmode.md 檔案，請將其重新命名為 .agent.md 以轉換為新的自訂代理格式，並將其放置在適當的位置（ chat.agentFilesLocations 在 VS Code 中開啟 在 VS Code Insiders 中開啟 ）以繼續使用它們。

如何刪除自訂代理？

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

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

若要移除由擴充功能貢獻的自訂代理，您需要解除安裝提供該代理的擴充功能。如果您不想解除安裝該擴充功能，您可以改為從代理下拉式清單中隱藏該自訂代理。請遵循 自訂代理程式下拉式清單 中的步驟。

如何知道自訂代理來自哪裡？

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

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

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

安全性考量

自訂代理可以限制可用的工具，讓您能夠控制 AI 的行為。對於安全敏感的工作流程，請建立使用唯讀工具的代理以防止意外修改。在儲存庫中共享代理時，請審核工具清單與指令，確保它們遵循「最小權限原則」。

相關資源

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