VS Code 中的自定義代理

自定義代理可讓您配置 AI，使其能夠採用針對特定開發角色和任務量身定製的不同個性。例如，您可以為安全評審員、規劃員、解決方案架構師或其他專業角色建立代理。每種個性都可以擁有自己的行為、可用工具和指令。

您還可以使用交接功能建立代理之間的引導式工作流，從而只需單擊一下即可無縫地從一個專用代理過渡到另一個專用代理。例如，您可以直接從規劃代理轉到實現代理，或將上下文傳遞給程式碼評審員。

本文介紹如何在 VS Code 中建立和管理自定義代理。

注意

自定義代理自 VS Code 版本 1.106 起可用。自定義代理以前稱為自定義聊天模式。

什麼是自定義代理？

內建代理提供了 VS Code 中聊天的通用配置。為了獲得更量身定製的聊天體驗，您可以建立自己的自定義代理。

自定義代理由一組指令和工具組成，在您切換到該代理時應用。例如，“計劃”代理可能包含生成實施計劃的指令，並且僅使用只讀工具。透過建立自定義代理，您可以快速切換到該特定配置，而無需每次手動選擇相關工具和指令。

自定義代理定義在 .agent.md Markdown 檔案中，可以儲存在您的工作區供他人使用，也可以儲存在您的使用者配置檔案中，以便您可以在不同工作區中重複使用它們。

您可以在後臺代理和雲代理中重複使用自定義代理，從而能夠使用相同的專用配置執行自主任務。

為什麼要使用自定義代理？

不同的任務需要不同的功能。規劃代理可能只需要用於研究和分析的只讀工具，以防止意外的程式碼更改，而實現代理則需要完整的編輯功能。自定義代理允許您精確指定每項任務可用的工具，確保 AI 具備適合該工作的正確功能。

自定義代理還允許您提供定義 AI 應如何執行的專用指令。例如，規劃代理可以指示 AI 收集專案上下文並生成詳細的實施計劃，而程式碼評審代理則可能側重於識別安全漏洞並提出改進建議。這些專用指令可確保每次切換到該代理時都能獲得一致、適合任務的響應。

注意

子代理可以與自定義代理一起執行。瞭解有關使用自定義代理執行子代理（實驗性）的更多資訊。

交接

交接功能使您可以建立引導式順序工作流，以建議的下一步操作在代理之間進行切換。聊天響應完成後，會出現交接按鈕，允許使用者將相關上下文和預填的提示傳遞到下一個代理。

交接功能對於編排多步工作流非常有用，可以讓開發人員在移動到下一步之前控制對每個步驟的評審和批准。例如

規劃 → 實現：在規劃代理中生成計劃，然後交接給實現代理開始編碼。
實現 → 評審：完成實現，然後切換到程式碼評審代理檢查質量和安全問題。
編寫失敗的測試 → 編寫成功的測試：生成比大型實現更容易評審的失敗測試，然後交接以透過實現所需的程式碼更改使這些測試透過。

要在代理檔案中定義交接，請將其新增到 frontmatter。每個交接都指定目標代理、按鈕標籤和可選的要傳送的提示。

---
description: Generate an implementation plan
tools: ['search', 'fetch']
handoffs:
  - label: Start Implementation
    agent: implementation
    prompt: Now implement the plan outlined above.
    send: false
---

當用戶看到交接按鈕並選擇它時，他們會切換到目標代理，並預填提示。如果 send: true，則提示會自動提交以啟動下一個工作流步驟。

自定義代理檔案結構

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

注意

VS Code 會將工作區 .github/agents 資料夾中的任何 .md 檔案識別為自定義代理。

頭部（可選）

頭部格式為 YAML frontmatter，包含以下欄位

欄位	描述
`描述`	自定義代理的簡短描述，顯示為聊天輸入欄位中的佔位符文字。
`name`	自定義代理的名稱。如果未指定，則使用檔名。
`argument-hint`	顯示在聊天輸入欄位中以指導使用者如何與自定義代理互動的可選提示文字。
`tools`	可用於此自定義代理的工具或工具集名稱列表。可以包括內建工具、工具集、MCP 工具或擴充套件提供的工具。要包含 MCP 伺服器的所有工具，請使用 `<server name>/*` 格式。瞭解有關聊天中的工具的更多資訊。
`model`	執行提示時使用的 AI 模型。如果未指定，則使用模型選擇器中當前選擇的模型。
`infer`	可選的布林標誌，用於啟用將自定義代理用作子代理（預設值為 `true`）。
`target`	自定義代理的目標環境或上下文（`vscode` 或 `github-copilot`）。
`mcp-servers`	可選的模型上下文協議 (MCP) 伺服器配置 json 列表，用於與GitHub Copilot 中的自定義代理一起使用（目標：`github-copilot`）。
`handoffs`	可選的建議下一步操作或提示列表，用於在自定義代理之間進行切換。交接按鈕在聊天響應完成後顯示為互動式建議。
`handoffs.label`	顯示在交接按鈕上的顯示文字。
`handoffs.agent`	要切換到的目標代理識別符號。
`handoffs.prompt`	要傳送到目標代理的提示文字。
`handoffs.send`	可選的布林標誌，用於自動提交提示（預設值為 `false`）。

注意

如果在 Yaogong 自定義代理時某個工具不可用，則該工具將被忽略。

正文

自定義代理檔案正文包含自定義代理實現，格式為 Markdown。您可以在此處提供特定的提示、指南或 AI 在此自定義代理中應遵循的任何其他相關資訊。

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

要在正文文字中引用代理工具，請使用 #tool:<tool-name> 語法。例如，要引用 githubRepo 工具，請使用 #tool:githubRepo。

當您在聊天檢視中選擇自定義代理時，自定義代理檔案正文中的指南會新增到使用者聊天提示的前面。

自定義代理示例

以下程式碼片段顯示了一個“計劃”自定義代理檔案的示例，該檔案生成實施計劃且不進行任何程式碼編輯。有關更多社群貢獻的示例，請參閱Awesome Copilot 儲存庫。

---
description: Generate an implementation plan for new features or refactoring existing code.
name: Planner
tools: ['fetch', 'githubRepo', 'search', 'usages']
model: Claude Sonnet 4
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.

建立自定義代理

您可以在工作區或使用者配置檔案中建立自定義代理檔案。

從代理下拉列表中選擇 **配置自定義代理**，然後選擇 **建立新自定義代理**，或在命令面板（⇧⌘P（Windows、Linux Ctrl+Shift+P））中執行 **Chat: New Custom Agent** 命令。
選擇應建立自定義代理檔案的位置。
- 工作區：在工作區的 .github/agents 資料夾中建立自定義代理定義檔案，僅在該工作區內使用
- 使用者配置檔案：在當前配置檔案資料夾中建立自定義代理定義檔案，以便在所有工作區中使用
為自定義代理輸入檔名。這是代理下拉列表中顯示的預設名稱。
在新建立的 .agent.md 檔案中提供自定義代理的詳細資訊。
- 填寫檔案頂部的 YAML frontmatter，以配置自定義代理的名稱、描述、工具和其他設定。
- 在檔案正文中為自定義代理新增指令。

要更新自定義代理定義檔案，請從代理下拉列表中選擇 **配置自定義代理**，然後從列表中選擇一個自定義代理進行修改。

注意

如果您之前在工作區的 .github/chatmodes 資料夾中使用 .chatmode.md 副檔名建立了自定義聊天模式，VS Code 仍會將這些檔案識別為自定義代理。您可以使用快速修復操作將它們重新命名並移動到新的 .github/agents 資料夾，並使用 .agent.md 副檔名。

如果您有多個自定義代理，可以自定義哪些代理顯示在代理下拉列表中。要顯示或隱藏特定自定義代理

從代理下拉列表中選擇 **配置自定義代理**。
將滑鼠懸停在列表中的自定義代理上，然後選擇眼睛圖示以顯示或隱藏它在代理下拉列表中的顯示。

工具列表優先順序

您可以使用 tools 元資料欄位為自定義代理和提示檔案指定可用工具列表。提示檔案還可以透過使用 agent 元資料欄位來引用自定義代理。

聊天中可用工具的列表由以下優先順序順序確定：

在提示檔案中指定的工具（如果有）
來自提示檔案中引用的自定義代理的工具（如果有）
選定代理的預設工具（如果有）

跨團隊共享自定義代理（實驗性）

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

VS Code 會自動檢測您有權訪問的組織級別的自定義代理。這些代理會與內建代理、個人代理和工作區自定義代理一起顯示在聊天中的代理下拉列表中。

要啟用組織級別自定義代理的發現，請將 github.copilot.chat.customAgents.showOrganizationAndEnterpriseAgents 設定為 true。

瞭解如何在 GitHub 文件中為您的組織建立自定義代理。

常見問題

自定義代理與聊天模式有何不同？

自定義代理以前稱為自定義聊天模式。功能保持不變，但術語已更新，以更好地反映其在為特定任務定製 AI 行為方面的目的。

VS Code 仍會將任何現有的 .chatmode.md 檔案識別為自定義代理。您可以使用快速修復操作將它們重新命名並移動到新的 .github/agents 資料夾，並使用 .agent.md 副檔名。