VS Code 中的自定义代理

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

你也可以利用切换来创建代理之间的引导工作流程。只需一次选择，即可无缝切换到另一位专业经纪人。例如，直接从规划代理转为实施代理，或者交给具有相关上下文的代码审查员。

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

什么是定制代理？

内置代理为 VS Code 聊天提供了通用配置。为了更个性化的聊天体验，你可以创建自己的定制代理。

自定义代理由一套指令和工具组成，切换到该代理时会应用这些指令。例如，“计划”代理可以包含生成实施计划的指令，仅使用只读工具。通过创建自定义代理，你可以快速切换到该配置，无需每次手动选择相关工具和说明。

自定义代理定义在.agent.mdMarkdown 文件，可以存储在你的工作区供他人使用，或者存储在用户配置文件中，在不同工作区间重复使用。

你可以在后台代理和云代理中复用自定义代理，从而以相同的专业配置运行自主任务。

为什么要使用定制代理？

不同的任务需要不同的能力。规划代理可能只需用于研究和分析的只读工具以防止代码意外更改，而实施代理则需要完整的编辑功能。定制代理允许你精确指定每个任务可用的工具，确保AI具备相应的能力。

自定义代理还允许你提供定义AI作方式的专业指令。例如，规划代理可以指示AI收集项目背景并生成详细的实施计划，而代码审查代理则可能专注于识别安全漏洞并提出改进建议。这些专门指令确保每次切换到该代理时都能获得一致且符合任务的响应。

交接

交接功能使您能够创建引导式顺序工作流程，在代理人之间切换并提出建议的下一步步骤。聊天回复完成后，会出现切换按钮，允许用户带着相关上下文和预填提示切换到下一位客服。

交接有助于协调多步骤工作流程，使开发者能够控制在进入下一步前审查和批准每个步骤。例如：

• 规划→实施：在规划代理中生成计划，然后交给实施代理开始编码。
• 实施→审查：完成实施后切换代码审查代理，检查质量和安全问题。
• 编写失败测试→编写通过测试：生成比大型实现更容易审查的失败测试，然后交接通过实现所需的代码变更让这些测试通过。

要在代理人文件中定义交接，可以在前言中添加。每次切换都指定目标代理、按钮标签以及一个可选的发送提示：

---
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)
---

当用户看到切换按钮并选择时，他们会切换到目标代理，提示词已预先填充。如果发送：真，提示会自动提交以开始下一个工作流程步骤。

自定义代理文件结构

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

头部（可选）

该头部格式为 YAML 前置文件，包含以下字段：

正体

自定义代理文件主体包含自定义代理实现，格式为Markdown。这里是你提供具体提示、指南或其他相关信息，希望AI在这个定制代理中遵循。

你可以通过使用Markdown链接引用其他文件，例如重用指令文件。

要在正文中引用代理工具，请使用#tool：<工具名>语法。例如，引用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.

Claude 代理格式

代理文件中的.claude/agents文件夹用普通版.md文件并支持 Claude 专用的前置信息属性：

VS Code 将 Claude 专用工具名称映射到相应的 VS Code 工具。两条VS代码.agent.md支持格式（使用YAML数组作为工具）和Claude格式（使用逗号分隔字符串）。

创建一个定制代理

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

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

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

   • 工作区：在.github/agents在你工作区的文件夹里，只在该工作区内使用它。

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

   • 工作区（Claude格式）：在.claude/agents该文件夹用于兼容 Claude Code 及其他基于 Claude 的工具。

   提示

   你可以通过使用

   chat.agent文件位置

   • 在VS代码中打开
   • 在VS Code Insiders中开放

   环境。这对于跨项目共享代理或将它们放在工作空间外的中心位置非常有用。

3. 输入自定义代理的文件名。这是代理下拉菜单中默认出现的名字。

4. 在新创建的中提供定制代理的详细信息.agent.md档案。

   • 在文件顶部填写 YAML 前言，配置自定义代理的名称、描述、工具及其他设置。
   • 在文件正文中添加定制代理的说明。

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

自定义代理人下拉列表

如果你有多个自定义代理，可以自定义哪些代理出现在代理下拉菜单中。要显示或隐藏特定的定制代理：

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

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

工具列表优先级

你可以通过以下方式指定自定义代理和提示文件可用的工具列表工具元数据字段。提示文件也可以通过使用特工元数据字段。

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

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

跨团队共享定制代理

为了在团队中共享自定义代理，你可以创建一个工作区级自定义代理（.github/agents文件夹）。如果你想在组织内多个工作区共享自定义代理，可以在 GitHub 组织层面定义它们。

VS Code 会自动检测你账户可访问的组织层面定义的自定义代理。这些代理会出现在聊天中的代理下拉菜单中，与内置代理以及你的个人和工作空间定制代理并列。

为了实现组织层级定制代理的发现，设置

了解如何为你的组织创建自定义代理，请参阅GitHub文档。

常见问题解答

定制代理和聊天模式有区别吗？

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

如果你已经存在.chatmode.md文件，将其重命名为.agent.md将它们转换为新的定制代理格式并放置在合适的位置（

我该如何移除自定义代理？

要完全移除VS Code中的自定义代理：

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

要移除由扩展贡献的自定义代理，你需要卸载提供该代理的扩展。如果你不想卸载扩展，可以直接在代理下拉菜单里隐藏自定义代理。请按照“定制代理人”下拉菜单中的步骤作。

我怎么知道定制代理是从哪里来的？

自定义代理可以来自不同的来源：内置代理、你个人资料中用户自定义的代理、当前工作区中的工作区定义代理、组织定义的代理，或扩展贡献的代理。

要识别定制代理的来源：

1. 从代理下拉菜单中选择配置自定义代理。
2. 将鼠标悬停在列表中的定制代理上。源代码位置会显示在提示中。

相关资源

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