自定义代理配置

          自定义代理 配置参考。

在本文中

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

注意

自定义智能体 位于适用于 JetBrains IDE、Eclipse 和 Xcode 的 公共预览版 中，并且可能会更改。

YAML frontmatter 属性

下表概述了可以在GitHub.com、Copilot 命令行界面（CLI）中以及支持的IDE中（除非另有说明）为代理资料配置的属性。 属性说明中记录了任何特定于环境的行为。 配置文件的名称（减 .md 号或 .agent.md）用于删除级别之间的重复数据，以便最低级别的配置优先。

资产类型目的
name字符串的 自定义智能体显示名称。 可选。
description
          **所需的** 字符串     | 
          自定义智能体用途和功能的说明 |

| target | 字符串 | 目标环境或为自定义智能体设定的上下文（vscode或github-copilot）。 如果未设置，则默认为这两个环境。 | | tools | 字符串列表、字符串 | 可以使用的工具名称 自定义智能体 列表。 支持逗号分隔字符串和 yaml 字符串数组。 如果未设置，默认使用所有工具。 请参阅 “工具”。 | | model | 字符串 | 执行 自定义智能体 时要使用的模型。 如果未设置，则继承默认模型。 | | disable-model-invocation | 布尔 | Copilot 云代理根据任务上下文禁用自动使用此功能自定义智能体。 在true的情况下，必须手动选择代理。 设置 disable-model-invocation: true 等效于 infer: false. 如果两者都已设置， disable-model-invocation 则优先。 如果未设置，则默认为 false. | | user-invocable | 布尔 | 控制用户是否可以选择此项 自定义智能体 。 如果 false无法手动选择代理，并且只能以编程方式访问代理。 如果未设置，则默认为 true. | | infer | 布尔 | ** 已停用 **。 请改用 disable-model-invocation 和 user-invocable。 允许 Copilot 云代理 基于任务上下文自动使用此 自定义智能体。 在false的情况下，必须手动选择代理。 如果未设置，则默认为 true. | | mcp-servers | 对象 | 其他 MCP 服务器和工具，应该由自定义智能体使用。 不在VS Code 和其他集成开发环境自定义代理中使用。 | | metadata | 对象，由名称和值对组成，都是字符串 | 允许对代理进行有用数据的注释。 不在VS Code和其他集成开发环境中使用自定义代理。 |

在 YAML frontmatter 下方的 Markdown 内容中定义代理的行为、专业知识和说明。 提示最多可以包含 30,000 个字符。

注意

          `argument-hint` 和 `handoffs` 属于 VS Code 及其他 IDE 自定义代理 的属性目前在 Copilot 云代理 上不支持。 忽略它们以确保兼容性。
  • 有关 中文件结构的详细信息，请参阅 文档中的。

Tools

该 自定义智能体tools 属性控制代理程序可用的工具，包括来自 MCP 服务器的工具。

          自定义智能体 将有权访问已在 代理资料 和/或存储库设置中配置的 MCP 服务器工具。 有关在存储库中为云代理配置 MCP 服务器的详细信息，请参阅 [AUTOTITLE](/copilot/how-tos/use-copilot-agents/coding-agent/extend-coding-agent-with-mcp)。

可以使用以下方法进行配置 tools ：

  •         **启用所有可用工具**：完全省略该 `tools` 属性，或者用于 `tools: ["*"]` 启用所有可用工具。 这将包括在 代理资料 和/或存储库设置中配置的所有 MCP 服务器工具。

  •         **启用特定工具**：提供特定工具名称或别名的列表（例如）， `tools: ["read", "edit", "search"]`以仅启用这些工具。 有关可用的工具别名，请参阅下面的 [工具别名](#tool-aliases) 。
    • 请注意，如果存储库配置了 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 | Read、NotebookRead | view | 读取文件内容。 | | edit | Edit、MultiEdit、Write、NotebookEdit | 编辑工具：例如 str_replace``str_replace_editor | 允许 LLM 编辑。 参数的具体内容可能会有所不同。 | | search | Grep、Glob | search | 搜索文件或文件中的文本。 | | agent | custom-agent、Task | “自定义代理” 工具 | 允许调用不同的 自定义智能体 来完成任务。 | | web | WebSearch、WebFetch | 当前不适用于 云代理。 | 允许从 URL 提取内容并执行 Web 搜索 | | todo | TodoWrite | 目前该功能不适用 云代理。 | 创建和管理结构化任务列表。 云代理今天不支持，但受VS Code支持。 |

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

以下 MCP 服务器是开箱即用的，可以使用命名空间进行引用：

MCP 服务器名称可用工具
github默认情况下，所有只读工具都可用，但服务器接收的令牌限定为源存储库。
          `github/*` 包括所有这些，也可以参考 `github/<tool name>`，其中 `<tool name>` 是 MCP 服务器文档中的一个值。 |

| playwright | 默认情况下，所有剧作家工具都可用，但服务器配置为仅访问 localhost。 playwright/* 包括所有这些，也可以参考 playwright/<tool name>，其中 <tool name> 是 MCP 服务器文档中的一个值。 默认情况下，它有权访问的令牌限定为源代码存储库。 |

MCP 服务器配置详细信息

以下示例 代理资料 显示了具有 MCP 服务器的代理和配置的机密。 此外，在 YAML frontmatter 的 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 在 代理资料 中是用于配置 MCP 服务器的 JSON 配置格式的 YAML 表示形式。

大多数子属性与 JSON 表示形式相同。 以下各节描述与 Copilot 云代理 的 MCP 配置初始实现相比与 自定义代理 相关的更改。 有关 JSON 配置格式的详细信息，请参阅 使用模型上下文协议扩展 GitHub Copilot 云代理 （MCP）。

MCP 服务器类型

为了兼容，stdioClaude Code 使用的类型并VS Code云代理映射到“local类型”。

MCP 服务器环境变量和机密

注意

如果 MCP 服务器需要机密或环境变量，则必须在 Copilot 要使用的每个存储库 自定义智能体 的环境中配置这些机密或环境变量。 有关设置环境变量的详细信息，请参阅 自定义 GitHub Copilot 云代理的开发环境。

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

存储库级 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.

实现规划器

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

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.

处理 自定义代理

          自定义智能体 名字

在命名冲突的情况下，最低级别配置会替代更高级别的配置。 这意味着存储库级代理将优先于组织级别代理，而组织级代理将替代企业级代理。

版本控制

          自定义代理 版本控制基于 代理资料 文件的 Git 提交 SHA。 这样，就可以根据需要创建具有不同版本的 自定义代理 分支或标记。 将 自定义智能体 分配给任务时，自定义智能体 将使用该存储库和分支的 代理资料 最新版本来实例化。 当代理创建拉取请求时，为了一致性，拉取请求中的交互使用相同版本的 自定义智能体。

工具加工

该 tools 列表筛选了代理可用的工具集，无论是内置还是源自 MCP 服务器。 在对代理资料进行工具配置时，其功能取决于您所指定的内容：

  • 如果未指定任何工具，则启用所有可用工具
  • 工具列表为空（tools: []）会禁用所有工具
  • 特定列表（tools: [...]）仅允许这些工具

MCP 服务器配置

对于 MCP 服务器配置，有一个特定的处理顺序可确保适当的覆盖效果：首先处理默认的 MCP 配置（如 GitHub MCP），然后是 自定义智能体 MCP 配置，最后是通过存储库设置指定的 MCP 配置。 这样，每个级别都可以根据需要替代上一级别的设置。

延伸阅读

  •         [AUTOTITLE](/copilot/how-tos/copilot-cli)

  •         [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#custom-agents-reference)