Настройка пользовательских агентов

Эта справочная статья содержит подробную информацию о конфигурации для Пользовательские агенты. Для общей информации о создании Пользовательские агентысм. Создание кастомных агентов для Copilot облачный агент.

Свойства YAML frontmatter

В следующей таблице приведены свойства, которые вы можете настроить для Профили агентов , GitHub.comВторой пилот CLI, и поддерживаемых IDE (если не указано иное). Любое поведение, специфическое для окружающей среды, отмечается в описании свойства. Имя конфигурационного файла (минус .md или .agent.md) используется для дедупликации между уровнями, так что конфигурация наименьшего уровня имеет приоритет.

          **Обязательная** строка     | Описание назначения и возможностей корабля Пользовательский агент |

Определите поведение, опыт и инструкции агента в содержимом Markdown под внешним элементом YAML. Запрос может составлять максимум 30 000 символов.

Tools

Property управляет Пользовательский агентtools , какие инструменты доступны вашему агенту, включая те, что с MCP-серверов.

У вас Пользовательский агент будет доступ к инструментам сервера MCP, которые настроены как в его Профиль агента и/или в настройках репозитория. Для получения дополнительной информации о настройке MCP-серверов для облачных агентов в репозитории см. Расширение облачного агента GitHub Copilot с помощью протокола Model Context Protocol (MCP).

Вы можете настроить tools с помощью следующих подходов:

•         **Включить все доступные инструменты**: полностью опустите свойство `tools` или используйте для `tools: ["*"]` включения всех доступных инструментов. Это включает все инструменты сервера MCP, Профиль агента настроенные в настройках и/или репозитории.
  

•         **Включить определенные инструменты**: Предоставьте список имен или псевдонимов определенных инструментов (например, `tools: ["read", "edit", "search"]`), чтобы включить только эти инструменты. Доступные псевдонимы инструментов см. [в разделе Псевдонимы инструментов](#tool-aliases) ниже.
  

  • Обратите внимание, что если в вашем репозитории настроены MCP-серверы, вы можете сделать доступными Пользовательский агенттолько определённые инструменты из этих серверов. Имена инструментов с определенных серверов MCP могут начинаться с имени сервера, за которым следует /. Например: some-mcp-server/some-tool.
  • Вы также можете явно включить все инструменты с определенного сервера MCP с помощью some-mcp-server/*.
  • Инструменты расширений VS Code могут использовать имя расширения как прокси, например azure.some-extension/some-tool.

•         **Отключить все инструменты**: Используйте пустой список (`tools: []`) для отключения всех инструментов для агента.
  

Все нераспознанные имена инструментов игнорируются, что позволяет указывать инструменты, специфичные для продукта Профиль агента , без возникновения проблем.

Псевдонимы инструментов

Следующие псевдонимы инструментов доступны для Пользовательские агенты. Регистр всех псевдонимов нечувствителен:

| Основной псевдоним | Совместимые псевдонимы | Облачный агент Отображение | Цель | | ------------- | -------------------------------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | execute | shell, , Bash``powershell | Инструменты для скорлупы: bash или powershell | Выполните команду в соответствующей оболочке для операционной системы. | | 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-адресов и выполнять веб-поиск | | todo | TodoWrite | В настоящее время не применимо к Облачный агент. | Создает структурированные списки задач и управляет ими. Сегодня не поддерживается Облачный агент , но поддерживается VS Code. |

Имена инструментов для "готовых" MCP-серверов

Следующие MCP-серверы доступны из коробки и Copilot облачный агент могут быть ссылаться с помощью промежутка имён:

          `github/*` включает их все, или вы можете указать `github/<tool name>` where `<tool name>` is value из документации сервера MCP. |

| playwright | Все инструменты драматурга доступны по умолчанию, но сервер настроен только на доступ к localhost. playwright/* включает их все, или вы можете указать playwright/<tool name> where <tool name> is value из документации сервера MCP. По умолчанию маркер, к которому у него есть доступ, ограничен репозиторием исходного кода. |

Сведения о конфигурации сервера MCP

Следующий пример Профиль агента показывает агента с MCP-сервером и конфигурированным секретом. Кроме того, в свойстве tools frontmatter YAML включен только один инструмент с сервера 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 в an Профиль агента — это YAML-представление формата конфигурации JSON, используемого для настройки MCP-серверов для Copilot облачный агент.

Большинство вложенных свойств совпадают с представлением JSON. В следующих разделах описываются изменения по сравнению с первоначальной реализацией конфигурации MCP, Copilot облачный агент которые имеют отношение к Пользовательские агенты. Дополнительные сведения о формате конфигурации JSON см. в разделе AUTOTITLE.

Тип сервера MCP

Для совместимости stdio тип, используемый в Claude Code и VS Code , сопоставляется с Облачный агенттипом local .

Переменные и секреты окружения сервера MCP

          Настраиваемый агент Конфигурация MCP поддерживает те же возможности переменной среды и секретной замены, что и существующие конфигурации MCP на уровне репозитория. Как и в случае с конфигурациями на уровне репозитория, секреты и переменные могут быть получены из среды "copilot" в параметрах репозитория. Синтаксис для ссылок на эти значения был расширен для поддержки распространённых шаблонов, используемых в GitHub Actions и Claude Code.

И конфигурация MCP JSON на уровне репозитория, и конфигурация Пользовательский агент YAML поддерживают следующие синтаксические паттерны:

•         `$COPILOT_MCP_ENV_VAR_VALUE` - Переменная окружения и заголовок
  

•         `${COPILOT_MCP_ENV_VAR_VALUE}` - Переменная окружения и заголовок (синтаксис кода Клода)
  

•         `${COPILOT_MCP_ENV_VAR_VALUE:-default}` - Переменная среды и заголовок с параметрами по умолчанию
  

Конфигурация YAML поддерживает следующие дополнительные синтаксические шаблоны:Пользовательский агент

•         `${{ secrets.COPILOT_MCP_ENV_VAR_VALUE }}` - Переменная окружения и заголовок
  

•         `${{ vars.COPILOT_MCP_ENV_VAR_VALUE }}` - Переменная окружения и заголовок
  

Примеры Профиль агента конфигураций

В следующих примерах показано, как может выглядеть Профиль агента для общих задач написания тестов или планирования реализации проекта. Для получения дополнительного вдохновения см. примеры Пользовательские агенты в библиотеке настройки. Вы также можете найти более конкретные примеры в коллекции сообщества awesome-copilot .

Специалист по тестированию

В этом примере включаются все инструменты, опуская свойство tools .

---
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.

Планировщик реализации

В этом примере включается только подмножество инструментов.

---
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.

Обработка Пользовательские агенты

          Пользовательские агенты Имена

В случае конфликтов имен конфигурация самого низкого уровня переопределяет конфигурации более высокого уровня. Это означает, что агент уровня репозитория будет иметь приоритет над агентом уровня организации, а агент уровня организации будет переопределять агент уровня предприятия.

Управление версиями

          Настраиваемый агент Версионирование основано на Git-коммит-SHA для файла Профиль агента . Это позволяет создавать ветки или теги с разными версиями Пользовательские агенты по необходимости. Когда вы назначаете задачу, Пользовательский агент она Пользовательский агент будет создана с использованием последней версии Профиль агента репозитория и ветви этого репозитория. Когда агент создаёт pull request, взаимодействия внутри него используют ту же версию Пользовательский агент для согласованности.

Обработка инструментов

В 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)