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

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

Свойства YAML frontmatter

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

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

Tools

Property управляет custom agenttools , какие инструменты доступны вашему агенту, включая те, что с MCP-серверов.

У вас custom agent будет доступ к инструментам сервера MCP, которые настроены как в его agent profile и/или в настройках репозитория. Для получения дополнительной информации о настройке MCP-серверов общего репозитория на GitHub, см. Настройте MCP-серверы для вашего репозитория.

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

• Включить все доступные инструменты: полностью опустите свойство tools или используйте для tools: ["*"] включения всех доступных инструментов. Это включает все инструменты сервера MCP, agent profile настроенные в настройках и/или репозитории.
• Включить определенные инструменты: Предоставьте список имен или псевдонимов определенных инструментов (например, tools: ["read", "edit", "search"]), чтобы включить только эти инструменты. Доступные псевдонимы инструментов см. в разделе Псевдонимы инструментов ниже.
  • Обратите внимание, что если в вашем репозитории настроены MCP-серверы, вы можете сделать доступными custom agentтолько определённые инструменты из этих серверов. Имена инструментов с определенных серверов MCP могут начинаться с имени сервера, за которым следует /. Например: some-mcp-server/some-tool.
  • Вы также можете явно включить все инструменты с определенного сервера MCP с помощью some-mcp-server/*.
  • Инструменты расширений VS Code могут использовать имя расширения как прокси, например azure.some-extension/some-tool.
• Отключить все инструменты: Используйте пустой список (tools: []) для отключения всех инструментов для агента.

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

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

Следующие псевдонимы инструментов доступны для custom agents. Регистр всех псевдонимов нечувствителен:

| Основной псевдоним | Совместимые псевдонимы | Cloud agent Отображение | Цель | | ------------- | -------------------------------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | 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 | "Custom agent" инструменты | Позволяет вызвать другого custom agent для выполнения задачи. | | web | WebSearch, WebFetch | В настоящее время не применимо к cloud agent. | Позволяет получать контент из URL-адресов и выполнять веб-поиск | | todo | TodoWrite | В настоящее время не применимо к cloud agent. | Создает структурированные списки задач и управляет ими. Сегодня не поддерживается cloud agent , но поддерживается VS Code. |

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

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

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

Следующий пример agent profile показывает агента с 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 agent profile — это YAML-представление формата конфигурации JSON, используемого для настройки MCP-серверов для репозиториев на GitHub.

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

Тип сервера MCP

Для совместимости stdio тип, используемый в Claude Code и VS Code , сопоставляется с cloud agentтипом local .

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

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

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

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

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

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

Примеры agent profile конфигураций

В следующих примерах показано, как может выглядеть agent profile для общих задач написания тестов или планирования реализации проекта. Для получения дополнительного вдохновения см. примеры Custom agents в библиотеке настройки. Вы также можете найти более конкретные примеры в коллекции сообщества 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.

Обработка custom agents

Custom agents Имена

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

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

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

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

В tools списке фильтруется набор инструментов, доступных агенту — как встроенных, так и полученных с серверов MCP. Когда вы настраиваете инструменты в agent profile, поведение зависит от того, что вы указываете:

• Если инструменты не указаны, все доступные инструменты включены
• Пустой список инструментов (tools: []) отключает все инструменты
• Определенный список (tools: [...]) включает только эти инструменты

Конфигурации сервера MCP

Для конфигураций сервера MCP существует определённый порядок обработки, который обеспечивает правильное поведение при переопределении: сначала обрабатываются готовые конфигурации MCP (такие GitHub как MCP), затем custom agent конфигурация MCP, а затем конфигурации MCP, указанные через настройки репозитория. Это позволяет каждому уровню переопределять настройки предыдущего уровня по мере необходимости.

Дополнительные материалы

• GitHub Copilot CLI
• Справочник команды GitHub Copilot CLI