前言
在使用GitHub Copilot进行日常开发时，我们面临着不同类型的任务：需求规划、代码实现、代码审查、重构优化等。不同的任务往往需要AI扮演不同的角色，使用不同的工具集，遵循不同的工作方式。例如，规划阶段需要AI只读代码进行分析，而实现阶段则需要完整的编辑能力；代码审查需要关注安全和质量，而重构需要关注架构和性能。
传统的做法是在每次切换任务时手动调整工具和指令，这不仅繁琐，还容易遗漏关键配置。Copilot Custom Agents（自定义代理）正是为了解决这一问题而设计的功能，它允许你为不同的开发角色和任务预先配置专属的AI代理，并通过简单的切换快速进入相应的工作模式。
本文将深入介绍Copilot Custom Agents的功能特性、配置方法、工作流设计和最佳实践，帮助你构建高效的AI辅助开发工作流。
Copilot Custom Agents是什么
Copilot Custom Agents是VS Code中GitHub Copilot的自定义代理功能，它允许开发者创建具有特定角色定位、工具集和行为指令的专属AI代理。每个自定义代理就像一个针对特定任务优化的AI助手，可以快速切换使用。
核心特点
- 角色定制：为不同的开发角色（如规划师、实现者、审查者）创建专属代理
- 工具隔离：每个代理可以配置专属的工具集，避免不必要的工具干扰
- 行为定义：通过指令定义代理的工作方式和响应风格
- 快速切换：通过代理下拉菜单一键切换不同的工作模式
- 工作流编排：使用
Handoffs功能在代理之间创建引导式工作流 - 团队共享：代理定义文件可以提交到代码仓库，团队成员共享使用
- 跨项目复用：可以在用户配置文件中定义全局代理，跨工作区使用
与内置代理的区别
GitHub Copilot提供了几个内置代理（如@workspace、@terminal等），它们提供通用的功能配置。而Custom Agents允许你根据具体的开发场景和团队需求创建更专业化的代理配置，实现更精准的任务定制。
关键概念
| 概念 | 说明 |
|---|---|
Agent文件 | 定义自定义代理的.agent.md文件 |
Tools（工具） | 代理可用的工具集，如文件搜索、代码编辑、终端执行等 |
Instructions（指令） | 定义代理如何工作的具体指导原则 |
Handoffs（交接） | 代理之间的流程切换机制 |
Workspace Agent | 工作区级别的代理，存储在项目的.github/agents目录 |
User Agent | 用户级别的代理，存储在用户配置文件目录 |
Organization Agent | 组织级别的代理，由GitHub组织统一管理 |
解决什么问题
Copilot Custom Agents主要解决以下几类问题：
任务模式切换困难
不同的开发任务需要不同的工作模式，传统方式需要手动调整配置。
场景示例：
- 规划阶段需要只读工具避免意外修改代码
- 实现阶段需要完整的文件编辑能力
- 审查阶段需要专注于质量和安全分析
- 重构阶段需要代码搜索和结构分析工具
工具使用混乱
当所有工具都可用时，AI可能选择不合适的工具，影响效率和结果质量。
场景示例：
- 规划时不应该编辑代码，但
AI可能尝试修改文件 - 快速原型开发时不需要完整的测试工具
- 代码审查时不需要执行终端命令
重复配置工作
每次开始新任务都需要重新说明要求和约束，效率低下。
场景示例：
- 每次做代码审查都要提醒
AI关注安全问题 - 每次规划都要说明生成实施计划的格式
- 每次实现都要强调遵循项目规范
工作流不连贯
在不同任务阶段之间切换时缺乏流畅的衔接，需要手动复制上下文。
场景示例：
- 规划完成后需要手动切换到实现模式
- 实现完成后需要手动准备代码审查上下文
- 测试失败后需要手动准备修复提示
团队协作不一致
团队成员使用不同的工作方式和配置，导致输出质量不一致。
场景示例：
- 不同成员使用不同的规划流程
- 代码审查关注点不统一
- 实施方法和标准各异
核心功能
代理定义与配置
代理文件结构
自定义代理使用.agent.md文件定义，采用Markdown格式，包含YAML格式的前置元数据（frontmatter）和Markdown格式的指令内容：
---
description: 生成功能实现计划
name: 规划代理
tools: ['fetch', 'githubRepo', 'search', 'usages']
model: Claude Sonnet 4.5
handoffs:
- label: 开始实现
agent: 实现代理
prompt: 现在开始实现上述计划。
send: false
---
# 规划指令
你处于规划模式。你的任务是生成实现计划...
前置元数据字段
| 字段 | 说明 | 必填 |
|---|---|---|
description | 代理的简要描述，显示在聊天输入框的占位符文本中 | 否 |
name | 代理名称，未指定时使用文件名 | 否 |
argument-hint | 输入提示文本，引导用户如何与代理交互 | 否 |
tools | 代理可用的工具列表，可包含内置工具、工具集、MCP工具或扩展提供的工具 | 否 |
model | 使用的AI模型，未指定时使用当前选择的模型 | 否 |
infer | 是否允许作为子代理使用，默认为true | 否 |
target | 目标环境，可选值：vscode或github-copilot | 否 |
mcp-servers | MCP服务器配置列表（用于GitHub Copilot） | 否 |
handoffs | 定义代理之间的交接流程 | 否 |
工具配置
工具可以是：
| 工具类型 | 说明 | 示例 |
|---|---|---|
| 内置工具 | Copilot内置的基础工具 | search（搜索）、fetch（获取网页）、usages（代码引用） |
| 工具集 | 预定义的工具组合 | read-only（只读工具集） |
MCP工具 | Model Context Protocol服务器提供的工具 | 使用<server-name>/*格式包含整个MCP服务器的工具 |
| 扩展工具 | 由VS Code扩展提供的工具 | 扩展注册的自定义工具 |
工具配置示例：
# 只使用只读工具
tools: ['read-only']
# 使用特定工具
tools: ['search', 'fetch', 'githubRepo', 'usages']
# 包含MCP服务器的所有工具
tools: ['myserver/*', 'search']
# 不配置tools则使用默认工具
Handoffs工作流
Handoffs（交接）是Custom Agents的核心特性之一，它允许你创建引导式的顺序工作流，在代理之间流畅过渡。
Handoffs的价值
- 流程引导：为复杂工作流提供清晰的步骤指引
- 上下文传递：自动携带相关上下文到下一个代理
- 提示预填充：预先准备好下一步的提示词
- 人工审核：每一步完成后允许开发者审核和批准
Handoffs配置
handoffs:
- label: 开始实现 # 按钮显示文本
agent: 实现代理 # 目标代理标识
prompt: 现在开始实现上述计划。 # 发送到目标代理的提示
send: false # 是否自动提交提示，默认false
Handoffs使用场景
- 规划 → 实现：规划阶段生成实施方案，然后交接到实现代理开始编码
- 实现 → 审查：实现完成后，切换到代码审查代理检查质量和安全
- 编写失败测试 → 实现代码：先生成失败的测试用例便于审查，再交接实现代码使测试通过
- 问题分析 → 方案设计 → 代码实现：多阶段工作流的顺序执行
工具优先级
当同时存在多个工具配置来源时，VS Code按以下优先级确定最终可用的工具列表：
- Prompt文件中指定的工具（最高优先级）
- Prompt文件引用的Custom Agent的工具
- 选中的Agent的默认工具（最低优先级）
这种优先级机制允许你在不同层次灵活控制工具的可用性。
代理作用域
Workspace级别
- 存储位置：
.github/agents/目录 - 作用范围：仅在当前工作区可用
- 适用场景：项目特定的工作流和角色
- 团队共享：可以提交到
Git仓库供团队使用
User级别
- 存储位置：用户配置文件目录
- 作用范围：所有工作区共享
- 适用场景：个人习惯和通用工作流
- 个人使用：不会影响团队其他成员
Organization级别（实验性）
- 配置方式：在
GitHub组织层面定义 - 作用范围：组织内所有成员
- 启用方式：设置
github.copilot.chat.customAgents.showOrganizationAndEnterpriseAgents为true - 适用场景：企业级规范和流程统一
使用方法
创建自定义代理
通过命令创建
步骤一：打开代理配置
从代理下拉菜单选择Configure Custom Agents，或在命令面板（⇧⌘P）运行Chat: New Custom Agent命令。
步骤二：选择位置
选择代理文件的存储位置：
- Workspace：创建在
.github/agents目录，仅当前项目使用 - User profile：创建在用户配置文件目录，跨项目使用
步骤三：命名代理
输入代理文件名，这将作为代理在下拉菜单中的默认名称。
步骤四：编写配置
在新创建的.agent.md文件中：
- 填写前置元数据配置代理的名称、描述、工具等
- 在文件正文中编写代理的具体工作指令
手动创建
你也可以直接在合适的位置创建.agent.md文件：
# Workspace级别
mkdir -p .github/agents
touch .github/agents/planner.agent.md
# User级别（macOS/Linux）
mkdir -p ~/.config/Code/User/agents
touch ~/.config/Code/User/agents/planner.agent.md
使用自定义代理
切换代理
在VS Code的聊天视图中：
- 点击代理下拉菜单
- 选择你创建的自定义代理
- 输入提示开始对话
切换代理后，该代理的指令和工具配置会自动应用到后续的对话中。
使用Handoffs
当代理配置了handoffs时：
- 完成当前代理的任务后，聊天响应下方会显示
handoff按钮 - 点击按钮切换到目标代理
- 如果
send: false，提示会预填充但不自动发送，你可以审核和修改 - 如果
send: true，提示会自动发送到目标代理
管理自定义代理
编辑代理
从代理下拉菜单选择Configure Custom Agents，然后从列表中选择要修改的代理，直接编辑.agent.md文件。
显示/隐藏代理
如果有多个自定义代理，可以控制哪些显示在下拉菜单中：
- 从代理下拉菜单选择
Configure Custom Agents - 将鼠标悬停在代理上
- 点击眼睛图标切换显示/隐藏状态
删除代理
完全删除自定义代理：
- 方式一：直接删除对应的
.agent.md文件 - 方式二：从
Configure Custom Agents列表中，悬停在代理上点击垃圾桶图标
查看代理来源
要确定代理的来源：
- 从代理下拉菜单选择
Configure Custom Agents - 将鼠标悬停在代理上
- 工具提示中会显示来源位置（内置、用户、工作区、组织或扩展）
迁移旧的Chat Modes
Custom Agents之前称为Custom Chat Modes，使用.chatmode.md文件。VS Code仍然识别这些旧文件，并提供快速修复操作来重命名和移动它们到新的.github/agents目录，扩展名改为.agent.md。
应用场景
规划代理（Planning Agent）
场景描述：需要为新功能或重构任务生成详细的实施计划，不涉及代码修改。
配置示例：
---
name: 规划代理
description: 为新功能或重构任务生成实施计划
tools: ['fetch', 'githubRepo', 'search', 'usages', 'read-only']
model: Claude Sonnet 4.5
handoffs:
- label: 实施计划
agent: 实现代理
prompt: 实施上述计划。
send: false
---
# 规划指令
你处于规划模式。生成详细的实施计划，不进行任何代码编辑。
计划应包括：
- **概述**：功能或重构任务的简要描述
- **需求**：功能性和非功能性需求列表
- **实施步骤**：详细的分步实施指南
- **测试策略**：验证实施所需的测试
- **风险和考虑因素**：潜在问题及缓解策略
使用流程：
- 切换到
Planner代理 - 输入功能需求或重构目标
- 审查生成的实施计划
- 点击
实施计划按钮切换到实现代理
实现代理（Implementation Agent）
场景描述：根据规划或需求实施具体的代码改动。
配置示例：
---
name: 实现代理
description: 根据计划实施功能
tools: ['search', 'usages', 'edit', 'create', 'delete']
handoffs:
- label: 审查代码
agent: 代码审查代理
prompt: 审查我刚刚做的代码改动。
send: false
---
# 实现指令
你处于实现模式。你的任务是实现计划的功能或修复。
指导原则：
- 遵循现有的代码风格和项目约定
- 编写干净、可读、可维护的代码
- 为复杂逻辑添加适当的注释
- 如需要，更新相关文档
- 实现后运行测试以确保正确性
使用流程：
- 从规划代理通过
handoff切换，或直接切换到实现代理 - 输入实施要求或继承的计划上下文
- 审查和确认代码改动
- 点击
审查代码按钮进入代码审查流程
代码审查代理（Code Review Agent）
场景描述：审查代码改动，关注代码质量、安全性、性能等方面。
配置示例：
---
name: 代码审查代理
description: 审查代码改动的质量和安全性
tools: ['search', 'usages', 'githubRepo', 'read-only']
---
# 代码审查指令
你处于代码审查模式。分析代码改动并提供反馈。
审查清单：
- **代码质量**：可读性、可维护性、遵循最佳实践
- **安全性**：潜在漏洞、输入验证、数据保护
- **性能**：效率、资源使用、可扩展性问题
- **测试**：测试覆盖率、边界情况、错误处理
- **文档**：注释、API文档、README更新
提供建设性的反馈和具体的改进建议。
使用流程：
- 从实现代理通过
handoff切换 AI自动分析最近的代码改动- 获得详细的审查反馈和改进建议
- 根据反馈进行必要的修改
重构代理（Refactoring Agent）
场景描述：优化现有代码结构，提升代码质量而不改变功能。
配置示例：
---
name: 重构代理
description: 重构现有代码以提升结构和可维护性
tools: ['search', 'usages', 'edit', 'githubRepo']
---
# 重构指令
你处于重构模式。在不改变功能的前提下改进代码结构。
重点关注：
- **提取方法**：将大型函数拆分为更小、更专注的函数
- **消除重复**：识别并消除重复代码
- **改进命名**：为变量和函数使用清晰、描述性的名称
- **简化逻辑**：降低复杂度，移除不必要的条件判断
- **更新模式**：应用现代语言特性和最佳实践
始终保持现有功能，并确保重构后测试通过。
测试代理（Test-First Agent）
场景描述：先编写失败的测试用例，然后实现代码使测试通过。
配置示例：
---
name: 测试代理
description: 先编写失败的测试，然后实现代码使其通过
tools: ['search', 'create', 'edit']
handoffs:
- label: 实现代码
agent: 测试代理
prompt: 实现代码使上述测试通过。
send: false
---
# 测试优先开发指令
你处于测试优先模式。在实现前编写全面的失败测试。
流程：
1. 理解功能需求
2. 编写定义预期行为的测试用例
3. 确保测试失败（因为尚未实现）
4. 通过交接准备实现阶段
测试指南：
- 覆盖正常路径和边界情况
- 测试错误处理和验证
- 使用描述性的测试名称
- 保持测试专注且独立
文档编写代理（Documentation Agent）
场景描述：为代码、API或项目编写高质量的文档。
配置示例：
---
name: 文档编写代理
description: 生成和更新项目文档
tools: ['search', 'githubRepo', 'fetch', 'edit', 'create']
---
# 文档编写指令
你处于文档模式。创建清晰、全面的文档。
文档类型：
- **API文档**：函数签名、参数、返回值、示例
- **代码注释**：复杂逻辑的行内说明
- **README文件**：项目概述、设置说明、使用示例
- **架构文档**：系统设计、组件交互、数据流
- **用户指南**：分步教程和操作指南
使用清晰的语言，提供示例，并保持文档与代码改动同步更新。
安全审查代理（Security Audit Agent）
场景描述：专门审查代码的安全问题和漏洞。
配置示例：
---
description: 审计代码的安全漏洞和最佳实践
name: 安全代理
tools: ['search', 'usages', 'githubRepo', 'read-only']
---
# 安全审计指令
你处于安全审计模式。识别并报告安全漏洞。
安全清单：
- **输入验证**：检查SQL注入、XSS、命令注入
- **身份认证**：验证正确的认证和授权
- **数据保护**：确保敏感数据加密和保护
- **依赖安全**：检查存在漏洞的依赖项
- **API安全**：审查API端点的安全缺陷
- **错误处理**：确保错误不泄露敏感信息
提供严重程度评级和修复建议。
最佳实践
合理设计工作流
原则：
- 将复杂任务分解为多个阶段，每个阶段对应一个代理
- 使用
handoffs串联各个阶段，形成流畅的工作流 - 在关键决策点保留人工审核环节（
send: false）
示例工作流：
需求分析 → 规划设计 → 编写测试 → 代码实现 → 代码审查 → 文档更新
精准配置工具集
原则：
- 只为代理配置必要的工具，避免工具泛滥
- 规划类代理使用只读工具，避免意外修改
- 实现类代理使用编辑工具，但可以限制范围
工具选择建议：
| 代理类型 | 推荐工具 | 避免工具 |
|---|---|---|
| 规划代理 | search、fetch、githubRepo、usages | 编辑类工具 |
| 实现代理 | search、edit、create、delete | 终端执行（除非必要） |
| 审查代理 | search、usages、githubRepo | 编辑类工具 |
| 文档代理 | search、edit、create、fetch | 代码编译工具 |
编写清晰的指令
原则：
- 使用清晰的结构化指令，明确代理的职责
- 提供具体的检查清单和操作指南
- 包含反例说明，明确什么不应该做
指令模板：
# [代理名称] 指令
## 角色
你处于[角色名]模式。你的主要任务是[主要任务]。
## 目标
- [目标1]
- [目标2]
- [目标3]
## 指导原则
- [指导原则1]
- [指导原则2]
- [指导原则3]
## 禁止事项
- [禁止事项1]
- [禁止事项2]
## 输出格式
[期望的输出格式说明]
保持代理专注
原则：
- 每个代理专注于单一职责
- 避免创建"万能代理"
- 通过
handoffs组合多个专注的代理
反模式：
# ❌ 不好的例子：一个代理做所有事情
---
name: 超级代理
tools: ['*'] # 所有工具
---
你可以做所有事情：规划、实现、审查、测试、文档...
推荐模式：
# ✅ 好的例子：职责单一的代理
---
name: 规划代理
tools: ['read-only']
---
你专注于生成详细的实施计划。
利用模型选择
原则：
- 为不同代理选择合适的模型
- 复杂任务使用更强大的模型
- 简单任务可以使用快速模型
模型选择建议：
| 任务复杂度 | 推荐模型 | 适用代理 |
|---|---|---|
| 高复杂度 | Claude Sonnet 4.5 | 架构设计、复杂重构、安全审计 |
| 中等复杂度 | 默认模型 | 功能实现、代码审查 |
| 低复杂度 | 快速模型 | 简单编辑、格式化、文档更新 |
版本控制与团队共享
原则：
- 将工作区级别的代理提交到
Git仓库 - 在
README中说明代理的用途和使用方法 - 定期审查和更新代理配置
目录结构建议：
.github/
└── agents/
├── planner.agent.md
├── implementer.agent.md
├── reviewer.agent.md
└── README.md # 说明各代理的用途
渐进式采用
原则：
- 从最常用的场景开始创建代理
- 在实践中逐步完善代理配置
- 收集团队反馈持续优化
采用路径：
- 第一阶段：创建规划代理和实现代理，建立基础工作流
- 第二阶段：添加代码审查代理，提升代码质量
- 第三阶段：根据团队需求添加专项代理（如测试、文档、安全等）
- 第四阶段：优化
handoffs，建立完整的端到端工作流
性能优化
原则：
- 避免在代理指令中包含过多冗余内容
- 合理使用工具筛选，减少不必要的工具调用
- 对于组织级代理，定期清理不再使用的配置
优化检查清单：
- 指令是否简洁明确？
- 工具配置是否最小化？
-
handoffs是否必要且高效？ - 代理命名是否清晰易识别？
监控与迭代
原则：
- 定期审查代理的使用情况
- 收集团队成员的使用反馈
- 根据实际效果调整代理配置
反馈收集维度：
- 代理是否有效提升了工作效率？
- 工具配置是否合理？
- 指令是否清晰易懂？
handoffs流程是否流畅？- 是否需要新的代理类型？
安全与权限
原则：
- 谨慎配置具有写权限的工具
- 敏感操作的代理应限制使用范围
- 审查组织级代理的权限配置
安全建议：
- 规划和审查类代理优先使用只读工具
- 避免在代理中硬编码敏感信息
- 定期审计代理的工具使用情况
常见问题
Custom Agents和Chat Modes有什么区别？
Custom Agents是Custom Chat Modes的新名称，功能相同但术语更准确地反映了它们的用途。VS Code仍然识别旧的.chatmode.md文件，并提供快速修复操作将它们迁移到新格式。
如何知道一个代理来自哪里？
在代理下拉菜单中选择Configure Custom Agents，然后将鼠标悬停在代理上，工具提示会显示来源：内置、用户配置文件、工作区、组织或扩展。
可以同时使用多个代理吗？
不可以，每次只能激活一个代理。但你可以通过handoffs在代理之间快速切换，并且可以在Prompt文件中引用特定的代理。
如果指定的工具不可用会怎样？
如果配置的工具在使用时不可用，它会被忽略，代理使用其他可用的工具。建议配置前确认工具的可用性。
组织级代理如何启用？
需要将设置github.copilot.chat.customAgents.showOrganizationAndEnterpriseAgents设置为true，然后VS Code会自动发现你有权访问的组织级代理。
可以在代理中引用MCP服务器吗？
可以，在tools配置中使用<server-name>/*格式可以包含整个MCP服务器的所有工具，或者单独指定MCP工具名称。
Handoffs的prompt可以包含变量吗？
当前handoffs的prompt是静态文本，但它会继承当前对话的上下文，所以可以通过上下文传递动态信息。
如何调试自定义代理？
- 检查代理文件的
YAML语法是否正确 - 验证配置的工具名称是否存在
- 测试代理的指令是否按预期工作
- 查看
VS Code的输出面板获取错误信息
可以为代理配置快捷键吗？
目前VS Code不直接支持为代理配置快捷键，但你可以使用键盘导航：使用Tab键在代理下拉菜单中切换，使用Enter选择。
代理会影响性能吗？
代理本身不会显著影响性能。性能主要取决于所使用的工具和模型。合理配置工具集可以提升响应速度。
参考资料
官方文档
社区资源
- Awesome Copilot Repository：社区贡献的自定义代理示例
- VS Code GitHub Issues：报告问题和功能请求
扩展阅读
- Background Agents：后台代理功能
- Cloud Agents：云端代理功能
- Subagents with Custom Agents：在子代理中使用自定义代理（实验性）