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
    model: GPT-5.2 (copilot)
---

当用户看到交接按钮并选择它时，他们将切换到目标代理，并预先填充了提示。如果设置了 send: true，提示会自动提交以启动下一个工作流程步骤。

自定义代理文件结构

自定义代理文件是 Markdown 文件，使用 .agent.md 扩展名，并具有以下结构。

头部（可选）

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

正文

自定义代理文件主体包含自定义代理实现，格式为 Markdown。您可以在此处提供希望 AI 在此自定义代理中遵循的具体提示、指南或任何其他相关信息。

您可以通过使用 Markdown 链接引用其他文件，例如重用说明文件。

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

当您在“聊天”视图中选择自定义代理时，自定义代理文件主体中的指南将作为前缀添加到用户聊天提示中。

示例

---
description: Generate an implementation plan for new features or refactoring existing code.
name: Planner
tools: ['fetch', 'githubRepo', '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: ['codebase', 'fetch', 'usages']
---
Research thoroughly using read-only tools. Return a summary of findings.

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

创建自定义代理

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

1. 从代理下拉列表中选择“配置自定义代理”，然后选择“创建新的自定义代理”，或在命令面板（⇧⌘P (Windows, Linux Ctrl+Shift+P)）中运行 Chat: New Custom Agent 命令。

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

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

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

   提示

   您可以通过使用 来配置 VS Code 搜索自定义代理文件的其他位置

   chat.agentFilesLocations

   • 在 VS Code 中打开
   • 在 VS Code Insiders 中打开

   设置。这对于在项目间共享代理或将它们保存在工作区外部的中央位置很有用。

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

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

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

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

自定义代理下拉列表

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

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

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

工具列表优先级

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

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

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

在团队间共享自定义代理

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

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

要启用组织级别自定义代理的发现，请设置

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

常见问题

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

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

如果您有现有的 .chatmode.md 文件，请将它们重命名为 .agent.md 以将其转换为新的自定义代理格式，并将它们放置在适当的位置（）

如何删除自定义代理？

要从 VS Code 中完全删除自定义代理：

• 从工作区或用户配置文件中删除相应的 .agent.md 文件。
• 从代理下拉列表中选择“配置自定义代理”，将鼠标悬停在列表中的自定义代理上，然后选择垃圾桶图标。

要删除由扩展程序贡献的自定义代理，您需要卸载提供该代理的扩展程序。如果您不想卸载扩展程序，可以改用在代理下拉列表中隐藏该自定义代理。请按照自定义代理下拉列表中的步骤操作。

如何知道自定义代理的来源？

自定义代理可以来自不同来源：内置代理、用户配置文件中的用户定义代理、当前工作区中的工作区定义代理、组织定义代理或扩展程序贡献的代理。

要确定自定义代理的来源：

1. 从代理下拉列表中选择“配置自定义代理”。
2. 将鼠标悬停在列表中的自定义代理上。源位置将显示在工具提示中。

相关资源

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