自定义代理配置

此参考文章提供了自定义代理的详细配置信息。有关创建自定义代理的一般信息，请参阅为 Copilot 云代理创建自定义代理。

注意

自定义代理目前在 JetBrains IDE、Eclipse 和 Xcode 中公开预览，且可能会更改。

YAML 前置属性

下表列出了您在 GitHub.com、Copilot CLI 和受支持的 IDE（除另有说明外）中可以为代理配置文件配置的属性。属性描述中会注明任何特定环境的行为。配置文件的名称（去除 .md 或 .agent.md）用于在不同层级之间进行去重，以便最低层级的配置具有最高优先级。

属性	类型	用途
`name`	string	自定义代理的显示名称。可选。
`description`	必需 string	自定义代理的目的和功能描述
`target`	string	自定义代理的目标环境或上下文（`vscode` 或 `github-copilot`）。如果未设置，则默认在两个环境中均可用。
`tools`	字符串列表，字符串	自定义代理可以使用的工具名称列表。支持逗号分隔的字符串和 yaml 字符串数组两种格式。如果未设置，默认使用所有工具。参见工具。
`model`	string	自定义代理执行时使用的模型。如果未设置，则继承默认模型。
`disable-model-invocation`	boolean	阻止 Copilot 云代理根据任务上下文自动使用此自定义代理。当设置为 `true` 时，必须手动选择该代理。将 `disable-model-invocation: true` 等同于 `infer: false`。如果两者均被设置，`disable-model-invocation` 优先。如果未设置，默认值为 `false`。
`user-invocable`	boolean	控制用户是否可以选择此自定义代理。当设置为 `false` 时，用户无法手动选择，只能通过编程方式访问。如果未设置，默认值为 `true`。
`infer`	boolean	已废弃。请改用 `disable-model-invocation` 和 `user-invocable`。该属性用于让 Copilot 云代理根据任务上下文自动使用此自定义代理。当设置为 `false` 时，必须手动选择代理。如果未设置，默认值为 `true`。
`mcp-servers`	object	应由自定义代理使用的额外 MCP 服务器和工具。在 VS Code 以及其他 IDE 的自定义代理中不使用。
`metadata`	对象，由名称和值对组成，均为字符串	允许为代理添加有用的数据注解。在 VS Code 以及其他 IDE 的自定义代理中不使用。

在 YAML 前置属性下方的 Markdown 内容中定义代理的行为、专长和指令。提示的最大长度为 30,000 个字符。

注意

VS Code 和其他 IDE 自定义代理的 argument-hint 与 handoffs 属性目前不支持 GitHub.com 上的 Copilot 云代理。为确保兼容性，这些属性将被忽略。
有关 VS Code 中自定义代理文件结构的更多信息，请参阅 VS Code 文档中的 VS Code 中的自定义代理。

工具

自定义代理的 tools 属性决定哪些工具对您的代理可用，包括来自 MCP 服务器的工具。

您的自定义代理可以访问在其代理配置文件和/或仓库设置中配置的 MCP 服务器工具。有关在仓库中为云代理配置 MCP 服务器的更多信息，请参阅使用模型上下文协议 (MCP) 扩展 GitHub Copilot 云代理。

您可以通过以下方式配置 tools：

启用所有可用工具：完全省略 tools 属性，或使用 tools: ["*"] 来启用所有可用工具。这将包括在代理配置文件和/或仓库设置中配置的所有 MCP 服务器工具。
启用特定工具：提供特定工具名称或别名的列表（例如 tools: ["read", "edit", "search"]），仅启用这些工具。可用的工具别名请参见下文工具别名。
- 请注意，如果您的仓库已配置 MCP 服务器，您可以仅为自定义代理提供这些服务器中的特定工具。特定 MCP 服务器的工具名称可以使用服务器名称加斜杠（/）作为前缀。例如 some-mcp-server/some-tool。
- 您也可以使用 some-mcp-server/* 明确启用某一 MCP 服务器的全部工具。
- 来自 VS Code 扩展的工具可以使用扩展名称作为代理，例如 azure.some-extension/some-tool。
禁用所有工具：使用空列表（tools: []）来禁用代理的所有工具。

所有未识别的工具名称都会被忽略，这允许在代理配置文件中指定特定产品的工具而不会导致问题。

工具别名

以下工具别名可用于自定义代理。所有别名均不区分大小写。

主要别名	兼容别名	云代理映射	用途
`execute`	`shell`, `Bash`, `powershell`	Shell 工具：`bash` 或 `powershell`	在对应操作系统的 Shell 中执行命令。
`读取`	`Read`, `NotebookRead`	`view`	读取文件内容。
`edit`	`Edit`, `MultiEdit`, `Write`, `NotebookEdit`	编辑工具：例如 `str_replace`、`str_replace_editor`	允许大语言模型进行编辑。具体参数可能有所不同。
`search`	`Grep`, `Glob`	`search`	搜索文件或文件中的文本。
`agent`	`custom-agent`, `Task`	“自定义代理”工具	允许调用另一个自定义代理来完成任务。
`web`	`WebSearch`, `WebFetch`	目前不适用于云代理。	允许从 URL 获取内容并执行网络搜索。
`todo`	`TodoWrite`	目前不适用于云代理。	创建并管理结构化任务列表。当前云代理不支持，但在 VS Code 中受支持。

“开箱即用” MCP 服务器的工具名称

以下 MCP 服务器已为 Copilot 云代理开箱即用，可通过命名空间进行引用。

MCP 服务器名称	可用工具
`github`	所有只读工具默认均可用，但服务器收到的 token 仅限于源仓库。`github/*` 包含全部工具，或者您可以使用 `github/<tool name>`，其中 `<tool name>` 来自该 MCP 服务器的文档。
`playwright`	所有 playwright 工具默认均可用，但服务器配置为只能访问 localhost。`playwright/*` 包含全部工具，或者使用 `playwright/<tool name>`（`<tool name>` 同样取自 MCP 服务器文档）。默认情况下，其 token 的访问范围被限制在源代码仓库。

MCP 服务器配置详情

下面的示例代理配置展示了一个配置了 MCP 服务器和机密的代理。同时，仅在 YAML 前置属性的 tools 中启用了该 MCP 服务器的一个工具。

---
name: my-custom-agent-with-mcp
description: Custom agent description
tools: ['tool-a', 'tool-b', 'custom-mcp/tool-1']
mcp-servers:
  custom-mcp:
    type: 'local'
    command: 'some-command'
    args: ['--arg1', '--arg2']
    tools: ["*"]
    env:
      ENV_VAR_NAME: ${{ secrets.COPILOT_MCP_ENV_VAR_VALUE }}
---

Prompt with suggestions for behavior and output

代理配置文件中的 mcp-servers 属性是用于为 Copilot 云代理配置 MCP 服务器的 JSON 配置格式的 YAML 表示。

大多数子属性与 JSON 表示相同。下面的章节描述了 Copilot 云代理中 MCP 配置的初始实现与自定义代理相关的更改。有关 JSON 配置格式的更多信息，请参阅使用模型上下文协议 (MCP) 扩展 GitHub Copilot 云代理。

MCP 服务器类型

出于兼容性考虑，Claude Code 和 VS Code 使用的 stdio 类型映射为云代理的 local 类型。

MCP 服务器环境变量和机密

注意

如果您的 MCP 服务器需要机密或环境变量，则必须在每个使用该自定义代理的仓库的 Copilot 环境中进行配置。有关设置环境变量的更多信息，请参阅自定义 GitHub Copilot 云代理的开发环境。

自定义代理的 MCP 配置支持与现有仓库级 MCP 配置相同的环境变量和机密替换功能。与仓库级配置类似，机密和变量可以来源于仓库设置中的 “copilot” 环境。引用这些值的语法已扩展，以支持 GitHub Actions 和 Claude Code 中常见的模式。

仓库级 MCP JSON 配置和自定义代理 YAML 配置均支持以下语法模式：

$COPILOT_MCP_ENV_VAR_VALUE - 环境变量和标题
${COPILOT_MCP_ENV_VAR_VALUE} - 环境变量和标题（Claude Code 语法）
${COPILOT_MCP_ENV_VAR_VALUE:-default} - 带默认值的环境变量和标题

自定义代理 YAML 配置还支持以下额外语法模式：

${{ secrets.COPILOT_MCP_ENV_VAR_VALUE }} - 环境变量和标题
${{ vars.COPILOT_MCP_ENV_VAR_VALUE }} - 环境变量和标题

示例代理配置文件

以下示例演示了在编写测试或规划项目实现等常见任务时，代理配置文件可能的样子。更多灵感请参阅自定义库中的自定义代理示例。您还可以在 awesome-copilot 社区集合中找到更具体的示例。

测试专家

此示例通过省略 tools 属性来启用所有工具。

Text

---
name: test-specialist
description: Focuses on test coverage, quality, and testing best practices without modifying production code
---

You are a testing specialist focused on improving code quality through comprehensive testing. Your responsibilities:

- Analyze existing tests and identify coverage gaps
- Write unit tests, integration tests, and end-to-end tests following best practices
- Review test quality and suggest improvements for maintainability
- Ensure tests are isolated, deterministic, and well-documented
- Focus only on test files and avoid modifying production code unless specifically requested

Always include clear test descriptions and use appropriate testing patterns for the language and framework.

---
name: test-specialist
description: Focuses on test coverage, quality, and testing best practices without modifying production code
---

You are a testing specialist focused on improving code quality through comprehensive testing. Your responsibilities:

- Analyze existing tests and identify coverage gaps
- Write unit tests, integration tests, and end-to-end tests following best practices
- Review test quality and suggest improvements for maintainability
- Ensure tests are isolated, deterministic, and well-documented
- Focus only on test files and avoid modifying production code unless specifically requested

Always include clear test descriptions and use appropriate testing patterns for the language and framework.

实现规划师

此示例仅启用了一部分工具。

Text

---
name: implementation-planner
description: Creates detailed implementation plans and technical specifications in markdown format
tools: ["read", "search", "edit"]
---

You are a technical planning specialist focused on creating comprehensive implementation plans. Your responsibilities:

- Analyze requirements and break them down into actionable tasks
- Create detailed technical specifications and architecture documentation
- Generate implementation plans with clear steps, dependencies, and timelines
- Document API designs, data models, and system interactions
- Create markdown files with structured plans that development teams can follow

Always structure your plans with clear headings, task breakdowns, and acceptance criteria. Include considerations for testing, deployment, and potential risks. Focus on creating thorough documentation rather than implementing code.

---
name: implementation-planner
description: Creates detailed implementation plans and technical specifications in markdown format
tools: ["read", "search", "edit"]
---

You are a technical planning specialist focused on creating comprehensive implementation plans. Your responsibilities:

- Analyze requirements and break them down into actionable tasks
- Create detailed technical specifications and architecture documentation
- Generate implementation plans with clear steps, dependencies, and timelines
- Document API designs, data models, and system interactions
- Create markdown files with structured plans that development teams can follow

Always structure your plans with clear headings, task breakdowns, and acceptance criteria. Include considerations for testing, deployment, and potential risks. Focus on creating thorough documentation rather than implementing code.