Appearance
自定义代理让你为 Copilot 创建专项角色——测试专家、架构规划师、文档撰写员……每个代理有独立的工具权限和行为指令。创建后可以在 GitHub.com 的 Agent 面板或 Copilot CLI 中直接调用。
GitHub Copilot 自定义代理：创建专项 AI 代理配置
应用场景
- 为代码审查创建"代码质量审查员"，只读文件不修改
- 为测试工作创建"测试专家"，专注于测试覆盖和质量
- 为文档工作创建"文档撰写员"，熟悉项目的文档规范
- 为安全审计创建"安全分析师"，重点关注漏洞和合规
创建代理
通过 GitHub Web 界面
- 访问
https://github.com/copilot/agents - 从下拉框选择目标仓库（和可选的分支）
- 点击代理图标 → Create an agent
- 系统自动在
.github/agents/下创建模板文件my-agent.agent.md - 重命名文件（文件名即代理标识，支持
.、-、_、字母、数字） - 填写代理配置，提交到默认分支
直接创建文件
在仓库 .github/agents/ 目录下创建 your-agent-name.agent.md。
代理文件格式
markdown
---
name: test-specialist # 可选，省略时用文件名
description: 专注于测试覆盖和质量改进，不修改生产代码
tools: ["read", "search", "edit"] # 可选，省略表示允许所有工具
model: claude-opus-4-7 # 可选，指定使用的 AI 模型
target: github-copilot # 可选，限制使用范围
---
你是一位测试专家，专注于通过全面的测试来提升代码质量。你的职责：
- 分析现有测试，找出覆盖缺口
- 编写单元测试、集成测试和端到端测试
- 遵循当前项目使用的测试框架和规范
- 确保测试隔离、稳定且有良好的说明
- **只处理测试文件**，不修改生产代码，除非用户明确要求
始终为测试添加清晰的描述，并使用适合当前语言和框架的测试模式。配置字段说明
| 字段 | 必须 | 说明 |
|---|---|---|
name | 否 | 显示名称，省略时用文件名 |
description | 是 | 代理用途描述，出现在代理列表中 |
tools | 否 | 允许的工具列表；省略则允许全部 |
mcp-servers | 否 | 代理专属的 MCP 服务器配置 |
model | 否 | 指定使用的 AI 模型 |
target | 否 | vscode（只在 VS Code 可见）或 github-copilot |
代理提示词写在 YAML frontmatter 下方的 Markdown 内容中，最多 30,000 个字符。
完整示例：架构规划师
markdown
---
name: implementation-planner
description: 创建详细的技术实施方案和架构文档，不直接编写代码
tools: ["read", "search", "edit"]
---
你是一位技术规划专家，负责创建全面的实施方案。你的职责：
- 分析需求，拆解成可执行的任务
- 创建技术规格说明和架构文档
- 生成带有清晰步骤、依赖关系的实施计划
- 记录 API 设计、数据模型和系统交互
- 创建结构化的 Markdown 文档供团队参考
始终使用清晰的标题、任务拆解和验收标准来组织文档。
包含测试、部署和风险分析的考量。
专注于文档创建，而不是代码实现。代理存放位置
| 路径 | 作用范围 |
|---|---|
.github/agents/ | 当前仓库 |
agents/（在 .github-private 仓库中） | 整个组织/企业 |
~/.copilot/agents/ | 当前用户（所有项目） |
优先级：系统级 > 仓库级 > 组织级（同名代理时高优先级覆盖）。
调用自定义代理
在 GitHub.com 上：
访问 https://github.com/copilot/agents 的代理面板，选择代理后开始对话。也可以将代理分配给 Issue，让它在云端自主完成任务。
在 Copilot CLI 中：
bash
# 命令行参数
copilot --agent=test-specialist --prompt "为 src/auth.ts 补充测试"
# 交互式会话中
/agent test-specialist
# 自然语言触发
请用测试专家代理来处理这个任务常见问题
Q: 代理修改后什么时候生效？
A: 代理文件合并到仓库默认分支后生效。在 GitHub Web 的代理界面刷新页面即可看到更新。
Q: 代理的 tools 字段不写等于什么？
A: 省略 tools 字段表示代理可以使用所有可用工具。如果想限制代理只能读取不能修改，设置 tools: ["read", "search"]。
Q: 自定义代理和 Copilot CLI 的代理有什么区别？
A: 两者都用 .agent.md 格式定义，但部署位置不同。GitHub Web 用的代理放 .github/agents/，Copilot CLI 用的代理放 .github/agents/ 或 ~/.copilot/agents/——放在仓库里的代理两个平台都能用。