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 扩展名。