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.

Claude 代理格式

.claude/agents 文件夹中的代理文件使用纯 .md 文件，并支持 Claude 特定的 frontmatter 属性

VS Code 将 Claude 特定的工具名称映射到相应的 VS Code 工具。VS Code .agent.md 格式（使用 YAML 数组表示工具）和 Claude 格式（使用逗号分隔的字符串）均受支持。

创建自定义代理

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

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

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

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

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

   • 工作区（Claude 格式）：在 .claude/agents 文件夹中创建代理文件，以兼容 Claude Code 和其他基于 Claude 的工具。

   提示

   您可以使用

   chat.agentFilesLocations

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

   设置来配置 VS Code 搜索自定义代理文件的其他位置。这对于在项目之间共享代理或将它们保存在工作区外部的中央位置非常有用。

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

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

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

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

使用 AI 生成自定义代理

您可以使用 AI 根据角色的描述生成自定义代理。在代理模式聊天中键入 /create-agent 并描述您想要的个性（例如，“安全审查代理”）。代理会提出澄清问题并生成一个带有适当工具、说明和 frontmatter 的 .agent.md 文件。

您还可以从正在进行的对话中提取自定义代理。例如，在多轮调试会话之后，询问“为这种类型的任务创建一个代理”，以将工作流程捕获为可重用的自定义代理。

自定义代理下拉列表

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

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
• 创建可重用的提示文件
• 在聊天中使用工具