VS Code 中的自定义代理

自定义代理使您能够配置AI以适应特定开发角色和任务的不同个性。例如，您可以为安全审核员、计划人员、解决方案架构师或其他专业角色创建代理。每个个性可以有不同的行为、可用工具和指令。

您还可以使用 handoffs 来在座席之间创建指导性的工作流。只需单击一次，就可以无缝地从一个专业座席过渡到另一个专业座席。例如，从计划座席直接过渡到实施座席，或者将相关上下文传递给代码审查座席。

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

什么是自定义代理？

内置的Agent为 VS Code 中的聊天提供了通用配置。要获得更个性化的聊天体验，您可以创建自己的自定义代理。

自定义代理是一组在切换到该代理时应用的指令和工具。例如，“计划”代理可能包括生成实施计划的指令，并且只使用只读工具。通过创建自定义代理，您可以快速切换到特定配置，而无需每次手动选择相关工具和指令。

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

您可以将自定义代理重新用于后台代理和云代理，使您能够使用相同的专用配置运行自主任务。

为什么使用定制代理？

不同的任务需要不同的能力。规划代理可能只需要用于研究和分析的只读工具，以防止意外的代码更改，而实施代理则需要完整的编辑能力。自定义代理使您能够为每个任务指定可用的工具，确保人工智能拥有完成工作所需的能力。

自定义代理还可以让您提供专门的说明，以定义AI应如何运行。 例如，一个规划代理可以指示AI收集项目上下文并生成详细的实施计划，而一个代码审查代理可能会专注于识别安全漏洞并提出改进建议。 这些专门的说明确保每次切换到该代理时，都能得到一致且适合任务的响应。

移交

移交允许您创建带有建议下一步骤的指导性顺序工作流程，这些工作流程在座席之间进行转换。聊天响应完成后，会出现移交按钮，用户可以使用相关上下文和预填提示转到下一个座席。

Handoffs 对于编排多步骤工作流程很有用，这使得开发人员可以在移动到下一步之前控制每个步骤的审核和批准。例如：

• 规划 → 实施：在规划代理中生成计划，然后交给实施代理开始编码。
• 实施 → 审查：完成实施后，切换到代码审查代理，检查质量和安全问题。
• 编写失败的测试 → 编写成功的测试：生成易于审查的小型失败测试，然后将其交给实施所需代码更改以使测试通过的人。

要定义您的代理文件中的转接，将其添加到前段。每个转接指定目标代理、按钮标签和可选的提示以发送：

---
描述：生成实施计划
工具：['搜索'，'获取']
移交：
  - Tab： 开始实施
    代理： 实施
    提示： 现在实施上面概述的计划。
    发送： 否
    模型： GPT-5.2（Copilot）
---

当用户看到转交按钮并选择它时，他们将切换到目标代理，并且提示框会自动填充。如果发送: 真提示自动提交以启动下一个工作流程步骤。

自定义代理文件结构

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

标题（可选）

标题格式化为 YAML 前置标记，包含以下字段：

身体

自定义代理文件主体包含自定义代理的实现，格式化为Markdown。这是您提供特定提示、指南或任何其他相关信息的地方，以便在该自定义代理中，AI能够遵循这些信息。

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

在正文中引用代理工具，请使用#工具：<工具名称>语法。例如，引用github 仓库工具，使用#工具:github库输入：.

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

示例

---
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
---
# 规划说明
您处于规划模式。您的任务是为新功能或现有代码的重构生成实施计划。
不要进行任何代码编辑，只需生成计划。

该计划由一个Markdown文档组成，该文档描述了实施计划，包括以下部分：

* 概述：对功能或重构任务的简要描述。
* 要求：功能或重构任务的列表。
* 实施步骤：实施功能或重构任务的详细步骤列表。
* 测试：需要实施的测试列表，以验证功能或重构任务。

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

---
名称: 实现者
描述: 根据提供的上下文实施代码更改
工具: ['editFiles', 'terminalLastCommand']
---
按照现有的代码模式进行更改。进行最小化、专注的编辑。

克劳德代理格式

代理文件在.claude/agents文件夹使用普通.md文件和支持特定于Claude的前置事项属性：

VS Code 将 Claude-specific 工具名称映射到相应的 VS Code 工具。两者都 VS Code.代理.md格式（使用 YAML 数组表示工具）和 Claude 格式（使用逗号分隔的字符串）都支持。

创建自定义代理

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

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

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

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

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

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

   小贴士

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

   聊天.代理文件位置

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

   设置。这在跨项目共享代理或将其保留在工作区外部的中央位置时非常有用。

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

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

   • 在文件顶部填写 YAML 前置标记，以配置自定义代理的名称、描述、工具和其他设置。
   • 在文件主体中添加自定义代理的说明。

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

自定义代理下拉列表

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

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

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

工具列表优先级

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

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

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

在团队之间共享自定义代理

为了在您的团队之间共享自定义代理，您可以创建一个工作区级别的自定义代理 (.github/agents如果你希望在组织内部的多个工作区之间共享自定义代理，可以在 GitHub 组织级别定义它们。

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

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

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

常见问题

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

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

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

如何删除自定义代理？

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

• 删除相应的.代理.md从你的工作区或用户配置文件中获取文件。
• 选择配置自定义代理从代理下拉菜单中，悬停在列表中的自定义代理上，并选择垃圾桶图标。

要移除由扩展提供的自定义代理，您需要卸载提供该代理的扩展。如果您不想卸载扩展，可以选择将自定义代理从代理下拉列表中隐藏。请按照自定义代理下拉列表中的步骤操作。

我如何知道一个自定义代理来自哪里？

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

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

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

相关资源

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