VS Code 中的自定义代理

自定义代理使您能够配置 AI 以采用针对特定开发角色和任务量身定制的不同角色。例如，您可以为安全审查员、规划师、解决方案架构师或其他专业角色创建代理。每个角色可以有自己的行为、可用工具和指令。

您还可以使用移交在代理之间创建引导式工作流，让您只需单击一下即可从一个专业代理无缝过渡到另一个代理。例如，您可以从规划代理直接进入实现代理，或将相关上下文移交给代码审查员。

本文介绍如何在 VS Code 中创建和管理自定义代理。

什么是自定义代理？

内置代理为 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 扩展名并具有以下结构。

头部（可选）

头部格式为 YAML frontmatter，包含以下字段

正文

自定义代理文件正文包含自定义代理实现，格式为 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.

创建自定义代理

您可以在工作区或用户配置文件中创建自定义代理文件。

1. 从代理下拉列表中选择配置自定义代理，然后选择创建新的自定义代理，或者在命令面板中运行聊天：新建自定义代理命令（⇧⌘P（Windows、Linux Ctrl+Shift+P））。

2. 选择应创建自定义代理文件的位置。

   • 工作区：在工作区的 .github/agents 文件夹中创建自定义代理定义文件，仅在该工作区中使用

   • 用户配置文件：在当前配置文件文件夹中创建自定义代理定义文件，以便在所有工作区中使用

3. 输入自定义代理的文件名。这是出现在代理下拉列表中的默认名称。

4. 在新创建的 .agent.md 文件中提供自定义代理的详细信息。

   • 填写文件顶部的 YAML frontmatter 以配置自定义代理的名称、描述、工具和其他设置。
   • 在文件正文中添加自定义代理的指令。

要更新自定义代理定义文件，请从代理下拉列表中选择配置自定义代理，然后从列表中选择一个自定义代理进行修改。

自定义代理下拉列表

如果您有多个自定义代理，可以自定义哪些代理出现在代理下拉列表中。要显示或隐藏特定的自定义代理

1. 从代理下拉列表中选择配置自定义代理。

2. 将鼠标悬停在列表中的自定义代理上，然后选择眼睛图标以在代理下拉列表中显示或隐藏它。

工具列表优先级

您可以通过使用 tools 元数据字段为自定义代理和提示文件指定可用工具列表。提示文件还可以通过使用 agent 元数据字段引用自定义代理。

聊天中可用工具列表按以下优先级顺序确定

1. 提示文件中指定的工具（如果有）
2. 提示文件中引用的自定义代理中的工具（如果有）
3. 所选代理的默认工具（如果有）

跨团队共享自定义代理（实验性）

要跨团队共享自定义代理，您可以创建工作区级自定义代理（.github/agents 文件夹）。如果您想在组织内的多个工作区中共享自定义代理，可以在 GitHub 组织级别定义它们。

VS Code 会自动检测在您帐户有权访问的组织级别定义的自定义代理。这些代理会出现在聊天中的“代理”下拉列表中，以及内置代理以及您的个人和工作区自定义代理。

要启用组织级自定义代理的发现，请将 github.copilot.chat.customAgents.showOrganizationAndEnterpriseAgents 设置为 true。

了解如何在 GitHub 文档中为组织创建自定义代理。

常见问题

自定义代理与聊天模式有何不同？

自定义代理以前称为自定义聊天模式。功能保持不变，但术语已更新以更好地反映其在为特定任务自定义 AI 行为方面的目的。

VS Code 仍将任何现有的 .chatmode.md 文件识别为自定义代理。您可以使用“快速修复”操作将其重命名并移动到带有 .agent.md 扩展名的新 .github/agents 文件夹中。

相关资源

• 使用自定义指令自定义 AI
• 创建可重用的提示文件
• 在聊天中使用工具