VS Code 中的自定义智能体 (Custom agents)

自定义智能体允许你配置 AI 以采用针对特定开发角色和任务定制的各种人设（Persona）。例如，你可以为安全审查员、规划师、解决方案架构师或其他专业角色创建智能体。每个人设都可以拥有自己独特的行为、可用工具和指令。

你还可以利用“移交机制”（Handoffs）在智能体之间创建引导式工作流。通过单次选择，即可从一个专业智能体无缝切换到另一个。例如，从规划智能体直接过渡到实现智能体，或在携带相关上下文的情况下移交给代码审查员。

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

什么是自定义智能体？

内置智能体为 VS Code 中的对话提供了通用配置。为了获得更具针对性的对话体验，你可以创建自己的自定义智能体。

自定义智能体由一组指令和工具组成，当你切换到该智能体时，这些指令和工具就会生效。例如，“规划”智能体可以包含生成实现计划的指令，且仅使用只读工具。通过创建自定义智能体，你可以快速切换到该特定配置，而无需每次都手动选择相关的工具和指令。

自定义智能体在 .agent.md Markdown 文件中定义，可以存储在你的工作区供他人使用，也可以存储在你的用户配置文件中，以便在不同的工作区重复使用。

你可以在后台智能体和云端智能体中复用你的自定义智能体，从而利用相同的专业配置运行自动化任务。

为什么要使用自定义智能体？

不同的任务需要不同的能力。规划智能体可能只需要用于研究和分析的只读工具，以防止意外的代码更改，而实现智能体则需要完整的编辑能力。自定义智能体允许你准确指定每个任务可用的工具，从而确保 AI 具备完成任务所需的正确能力。

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

移交机制 (Handoffs)

移交机制使你能够创建引导式的顺序工作流，并通过建议的后续步骤在智能体之间进行转换。在对话响应完成后，会出现移交按钮，允许用户带着相关上下文和预填好的提示词切换到下一个智能体。

移交机制非常适合编排多步骤工作流，让开发者在进入下一步之前能够审查和批准每一步。例如：

• 规划 → 实现：在规划智能体中生成计划，然后移交给实现智能体开始编码。
• 实现 → 审查：完成实现后，切换到代码审查智能体检查质量和安全问题。
• 编写失败测试 → 编写通过测试：生成比庞大实现更容易审查的失败测试，然后移交以通过实施必要的代码更改使这些测试通过。

要在你的智能体文件中定义移交，请将它们添加到 frontmatter 中。每个移交项都需要指定目标智能体、按钮标签以及可选的发送提示词。

---
description: Generate an implementation plan
tools: ['search', 'web']
handoffs:
  - label: Start Implementation
    agent: implementation
    prompt: Now implement the plan outlined above.
    send: false
    model: GPT-5.2 (copilot)
---

当用户看到并选择移交按钮时，他们会切换到目标智能体，并预填好提示词。如果 send: true，则提示词会自动提交以启动下一个工作流步骤。

自定义智能体文件位置

你可以为特定工作区定义自定义智能体，也可以在用户级别定义，使其在所有工作区中可用。下表列出了根据其作用域定义的自定义智能体默认文件位置。你可以使用 chat.agentFilesLocations ... 设置，为工作区自定义智能体文件配置额外位置。

要在用户数据中创建自定义智能体，请使用“智能体自定义编辑器”或使用 Chat: New Custom Agent 命令。

自定义智能体文件结构

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

头部（可选）

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

正文

自定义智能体文件正文包含自定义智能体的实现，格式为 Markdown。你可以在此处提供特定的提示词、指南或任何你希望 AI 在使用该自定义智能体时遵循的其他相关信息。

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

要在正文中引用智能体工具，请使用 #tool:<tool-name> 语法。例如，要引用 fetch 工具，请使用 #tool:web/fetch。

当你在“聊天”视图中选择该自定义智能体时，自定义智能体文件正文中的指南会被预先添加到用户的聊天提示词之前。

示例

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

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

---
name: "Strict Formatter"
description: "Agent that auto-formats code after every edit"
hooks:
  PostToolUse:
    - type: command
      command: "./scripts/format-changed-files.sh"
---

You are a code editing agent. After making changes, files are automatically formatted.

Claude 智能体格式

.claude/agents 文件夹中的智能体文件使用普通的 .md 文件，并支持 Claude 特定的 frontmatter 属性。

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

创建自定义智能体

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

1. 在“聊天”视图中，选择 配置聊天 (Configure Chat)（齿轮图标）以打开“智能体自定义编辑器”，然后选择 智能体 (Agents) 选项卡。

2. 从下拉菜单中选择 新建智能体 (工作区) 或 新建智能体 (用户)，具体取决于你希望存储智能体文件的位置。

   

   或者，从命令面板（⇧⌘P）运行 Chat: New Custom Agent 命令。

   提示

   你可以通过使用 chat.agentFilesLocations ... 设置，配置 VS Code 搜索自定义智能体文件的额外位置。这对于跨项目共享智能体或将它们保存在工作区之外的中心位置非常有用。

3. 选择位置并为自定义智能体输入文件名。这是出现在智能体下拉列表中的默认名称。

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

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

你可以通过在“智能体自定义编辑器”中打开它们来修改现有的自定义智能体。

使用 AI 生成自定义智能体

你可以使用 AI 根据角色描述生成自定义智能体。在 Agent 模式的聊天中输入 /create-agent 并描述你想要的人设（例如，“一个安全审查智能体”）。智能体会提出澄清问题，并生成一个包含适当工具、指令和 frontmatter 的 .agent.md 文件。

你还可以从持续的对话中提取自定义智能体。例如，在多轮调试会话后，询问“为这类任务制作一个智能体”，将工作流捕获为可复用的自定义智能体。

你还可以通过在“智能体自定义编辑器”下拉菜单中选择 生成智能体 (Generate Agent) 来生成自定义智能体。

自定义智能体下拉列表

如果你有多个自定义智能体，可以自定义哪些智能体出现在智能体下拉列表中。要显示或隐藏特定的自定义智能体：

1. 从智能体下拉列表中选择 配置自定义智能体。

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

工具列表优先级

当你同时在自定义智能体和提示词文件中使用 tools 时，提示词文件的工具优先级更高。有关完整的优先级顺序，请参阅提示词文件文档中的工具列表优先级。

在团队间共享自定义智能体

要在团队间共享自定义智能体，你可以创建工作区级别的自定义智能体（.github/agents 文件夹）。如果你希望在组织内的多个工作区之间共享自定义智能体，则可以在 GitHub 组织级别定义它们。

VS Code 会自动检测你的账户有权访问的组织级自定义智能体。这些智能体将与内置智能体以及你的个人和工作区自定义智能体一起出现在聊天的“智能体”下拉列表中。

要启用组织级自定义智能体的发现，请将 github.copilot.chat.organizationCustomAgents.enabled ... 设置为 true。

在 GitHub 文档中了解如何为你的组织创建自定义智能体。

常见问题

自定义智能体与聊天模式 (Chat modes) 有什么区别？

自定义智能体以前被称为“自定义聊天模式”。功能保持不变，但术语已更新，以更好地反映它们在为特定任务自定义 AI 行为方面的用途。

如果你有现有的 .chatmode.md 文件，请将它们重命名为 .agent.md 以转换为新的自定义智能体格式，并将其放置在适当的位置（ chat.agentFilesLocations ...）以继续使用它们。

如何移除自定义智能体？

要从 VS Code 中彻底移除自定义智能体：

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

要移除由扩展提供的自定义智能体，你需要卸载提供该智能体的扩展。如果你不想卸载扩展，可以改为从智能体下拉列表中隐藏该自定义智能体。请遵循自定义智能体下拉列表中的步骤。

我如何知道自定义智能体来自哪里？

自定义智能体可能来自不同的来源：内置智能体、个人配置文件中定义的智能体、当前工作区中定义的工作区智能体、组织定义的智能体或扩展提供的智能体。

要识别自定义智能体的来源：

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

安全注意事项

自定义智能体可以限制可用的工具，从而让你能够控制 AI 可以做什么。对于安全性敏感的工作流，请使用只读工具创建智能体，以防止意外修改。在仓库中共享智能体时，请审查工具列表和指令，以确保它们遵循“最小权限原则”。

相关资源

• 使用智能体进行规划
• 使用自定义指令自定义 AI
• 创建可重用的提示文件
• 在聊天中使用工具