GitHub Copilot Custom Agents: от универсального чата к специализированным ролям (на примере VS Code)

Многие уже используют GitHub Copilot Chat каждый день: @workspace, режимы вроде ask/edit/agent и быстрые правки кода стали частью рутины. Проблема в том, что стандартный агент в чате — универсальный, а значит часто даёт усреднённые ответы.

На практике стандартного чата часто становится недостаточно. Без заранее заданных правил агент не учитывает специфику проекта и принимает решения «по умолчанию». Такие ответы могут быть корректными технически, но часто не соответствуют вашим внутренним конвенциям и архитектурным ограничениям. В итоге это приводит к постоянному ручному управлению контекстом. Документацию и эталонные файлы приходится каждый раз явно добавлять в запрос, а роль, стек и стиль — задавать заново для каждой новой задачи.

С выходом версии VS Code 1.106 появилась возможность автоматизировать этот процесс через Custom Agents. В этой статье мы пошагово разберем два способа настройки таких агентов — через интерфейс VS Code и вручную через файлы конфигурации, детально пройдемся по доступным параметрам и соберем пример готового агента.

Содержание статьи

1. Что такое Custom Agents в GitHub Copilot Chat
2. Доступность и ограничения Custom Agents в GitHub Copilot (VS Code)
3. Инструкция: Способ 1 — Создание агента через интерфейс VS Code
4. Инструкция: Способ 2 — Создание агента вручную через файл
5. Конфигурации и полезные настройки
— Настройка YAML заголовка агента
— Таблица доступных YAML frontmatter параметров
— Настройка tools в файле агента
— Инструкции и управление контекстом
6. Пример готового Custom Agent

Что такое Custom Agents в GitHub Copilot Chat

Custom agent - это переключаемая роль для Copilot Chat — набор инструкций и разрешённых инструментов (Tools), который применяется при выборе агента. По сути это специализированная роль для нейросети: в отличие от стандартного чата, у агента есть чёткая «инструкция по эксплуатации» и доступ только к тем инструментам, которые вы ему разрешили.

Такие агенты позволяют:

• быстро переключаться между сценариями (например, “QA automation reviewer” и “Implementer”);

• закрепить правила работы (стек, стиль, ограничения) и снизить вариативность ответов;

• сократить объём повторяющихся вводных и ручного контекста между задачами.

Доступность и ограничения Custom Agents в GitHub Copilot (VS Code)

Перед тем как перейти к пошаговой настройке, стоит проговорить несколько моментов. Это сэкономит время, если у вас «нет нужной кнопки» или агент не появляется в списке.

1. Функция Custom Agents в VS Code доступна начиная с версии VS Code 1.106. Если версия ниже — пункта меню для настройки агентов может не быть.

2. В Copilot Free plan функция custom instructions and agents на момент публикации статьи не включена — для создания кастомных агентов нужен платный план (например, Pro/Pro+ и выше). Планы и ограничения могут меняться, поэтому лучше свериться с актуальной страницей тарифов.

3. Некоторые возможности агентов в VS Code появляются раньше многих других IDE, но иногда помечаются как experimental (экспериментальные фичи) — из-за этого детали поведения могут отличаться между версиями. При этом базовый сценарий с .agent.md в workspace/user profile — это поддерживаемая часть функциональности.

Сначала нужно убедиться, что:

• установлены расширения GitHub Copilot и GitHub Copilot Chat

• вы авторизованы в GitHub аккаунт в VS Code (Copilot активирован)

• у вас активна подписка Copilot, которая поддерживает нужные agent-функции

Теперь можем перейти непосредственно к настройке.

Способ 1 — Создание агента через GitHub Copilot Chat

Cамый простой путь через UI

Перед стартом прочитайте: Доступность и ограничения Custom Agents

1. В окне Copilot Chat под полем ввода сообщения (рядом с выбором моделей) найдите выпадающее меню Agent
   

   

2. В выпадающем списке выберите Configure Custom Agents....
   

   

3. В управлении агентами (еще один выпадающий список) нажмите + Create New Custom Agent....
   

   

4. Выберите расположение (location), где будет создан файл агента
   

   

   Workspace (.github/agents/) — агент будет доступен только в рамках текущего workspace. Плюс этого варианта в том, что файл лежит в репозитории и им удобно делиться с командой. По факту VS Code сохранит файл в папку проекта .github/agents/.
   

   User profile (User Data / User Profile) — агент будет доступен во всех ваших workspace, но только вам (как часть пользовательского профиля). VS Code сам положит файл в профильную директорию. На macOS это обычно внутри ~/Library/Application Support/Code/User/.
   

   
   В обоих случаях агенты из этих локаций автоматически появляются в списке Custom Agents в Copilot Chat в VS Code.
   

5. Укажите имя агента, например "AQA" (automation QA). Ограничения на имя файла: только символы: . - _ a-z A-Z 0-9.
   

   

6. В выбранной локации появится файл AQA.agent.md с готовым шаблоном примерно такого вида:

   --- description: 'Describe what this custom agent does and when to use it.' tools: [] --- Define what this custom agent accomplishes for the user, when to use it, and the edges it won't cross. Specify its ideal inputs/outputs, the tools it may call, and how it reports progress or asks for help.

7. Заполните шаблон под свою задачу. Минимально необходимо:
   

   а) заполнить description в YAML заголовке

   б) описать поведение агента в теле файла: что он делает, какие входные данные ожидает, в каком виде выдаёт результат (и где проходит граница — что он не должен делать)
   

   Остальные параметры — опциональные.

   

   Список доступных конфигураций и опций для агента смотрите в разделе Конфигурации и полезные настройки.
   

8. Вернитесь в Copilot Chat: в выпадающем списке с агентами должен появиться ваш новый Custom Agent (обычно они подтягиваются автоматически).
   

   

9. Выберите своего агента вместо стандартного Agent — и работайте в нужной роли и по заданным правилам.
   Для наглядности и быстрого старта я добавила пример готового Custom Agent в конце статьи.

Способ 2 — Создание агента вручную, через создание файла в workspace

Будет полезно, если вы хотите добавить агента в репозиторий без UI — например, чтобы закоммитить файл и раздать его команде через PR.

Перед стартом прочитайте: Доступность и ограничения Custom Agents

1. В корне проекта создайте папку .github/agents/

   <repo>/ .github/ agents/

2. Внутри папки создайте файл agent_name.agent.md (Имя файла может содержать только символы: ., -, _, a-z, A-Z, 0-9)
   

   

3. Скопируйте в файл шаблон (или сразу готовый пример Custom Agent)

   --- description: 'Describe what this custom agent does and when to use it.' tools: [] --- Define what this custom agent accomplishes for the user, when to use it, and the edges it won't cross. Specify its ideal inputs/outputs, the tools it may call, and how it reports progress or asks for help.

4. Заполните шаблон под свою задачу. Минимально необходимо:
   

   а) заполнить description в YAML заголовке

   б) описать поведение агента в теле файла: что он делает, какие входные данные ожидает, в каком виде выдаёт результат (и где проходит граница — что он не должен делать)
   

   Остальные параметры — опциональные.

   

   Список доступных конфигураций и опций для агента смотрите в разделе Конфигурации и полезные настройки.
   

5. Откройте Copilot Chat и проверьте список агентов (под полем ввода, рядом с выбором моделей): созданный Custom Agent должен появиться там автоматически.
   

   

6. Выберите своего агента вместо стандартного Agent — и работайте в нужной роли и по заданным правилам.
   Для наглядности и быстрого старта я добавила пример готового Custom Agent в конце статьи.

Конфигурации и полезные настройки

Настройка YAML заголовка агента

В YAML заголовках указывается имя агента, краткое описание, а также метаданные и поведение агента, которые Copilot читает до основного промпта. Как минимум это name и description — они показываются в списке агентов и помогают быстро понять, «кто он» и для каких задач. Дополнительно, в VS Code через YAML можно задавать и другие поля, которые управляют тем, как агент будет отображаться и работать в Copilot Chat.

Ссылки на официальные справочники по доступным параметрам YAML заголовка:
- GitHub Copilot — Custom Agents configuration
- VS Code — Custom Agent file structure

Если внимательно посмотреть обе страницы, видно, что набор параметров отличается: у VS Code он шире (например, есть model, argument-hint, handoffs). При этом GitHub-спецификация прямо отмечает, что часть VS Code параметров для Copilot на GitHub.com будет игнорироваться — это важно, если вы хотите делиться одними и теми же Custom Agents между разными IDE/сценариями.

Таблица доступных YAML frontmatter параметров

Показать таблицу

Параметры	GitHub (Web/Org/Repo)	VS Code	Описание и возможности	Примеры значений
name	✅	✅	Публичное имя. Определяет, как агент отображается в списке. В VS Code, если свойство опущено, именем становится название файла (без расширения).	QA Automation Expert
description (required)	✅	✅	Описание. Краткое описание назначения и возможностей агента. Содержит описание задач, которые решает агент.	Специализируется на написании автотестов (Pytest, Playwright), анализе логов CI/CD и генерации отчетов о покрытии кода. Помогает находить баги в pull request.
target	✅	✅	Ограничитель среды. Позволяет скрыть агента там, где он бесполезен. Например, если ваш агент умеет только настраивать CI/CD через API Гитхаба, вы ставите target: github-copilot. Пример опций: vscode или github-copilot. По умолчанию доступен везде.	vscode
tools	✅	✅	Доступные агенту инструменты. Список функций, которые агент может вызывать. Можно перечислять через запятую или списком. Ограничивает возможности агента ради безопасности или точности.	['vscode', 'execute', 'read', 'search', 'web', 'agent', 'todo']
infer	✅	✅	Разрешение авто-вызова агента. Если true, Copilot может автоматически использовать этого агента, если запрос пользователя совпадает с его описанием. Если false, агент вызывается вручную - только через @ (например, @auto-qa)	true
mcp-servers	❌	✅	Внешние контексты. Настройка серверов Model Context Protocol. Позволяет агенту подключаться к внешним локальным или облачным ресурсам (БД, API, файловые системы).	playwright-controller: command: npx args: ["-y", "@mcp/playwright-server"]
metadata	✅	❌	Тегирование. Пары "ключ-значение" (только строки) для категоризации агентов. Используется администраторами для управления большим каталогом агентов внутри компании.	team: quality-assurancepriority: highstandard: iso-25010
model	❌	✅	Выбор модели ИИ. Позволяет закрепить за агентом конкретную LLM (например, gpt-4o или claude-3.5-sonnet), игнорируя настройки пользователя по умолчанию. Модель должна быть подключена в Copilot	Claude Sonnet 4.5
argument-hint	❌	✅	Подсказка в чате. Текст-плейсхолдер, который видит пользователь в поле ввода. Помогает понять, как пользователям взаимодействовать с custom agent.	"Укажите название тестового сценария и конфигурации браузера для запуска теста"
handoffs	❌	✅	Интерактивные переходы. Список кнопок-действий, которые появляются после ответа агента. Позволяют быстро передать контекст другому агенту (agent), задать ему конкретный вопрос (prompt) и сразу отправить его (send: true).	- label: "Создать Bug Report" agent: github-issues prompt: "Создай issue на основе найденных ошибок в этом тесте: " send: false- label: "Исправить код" agent: copilot prompt: "Предложи исправление для кода, чтобы тесты проходили: " send: true

Настройка tools в файле агента

Доступные варианты настройки инструментов:

• tools: [] отключает любые инструменты для агента — он будет отвечать только текстом.

• Если tools не указан вообще, в GitHub-конфигурации это означает «все инструменты» (аналог tools: ["*"]).

• Для использования конкретного набора инструментов, необходимо перечислить их внутри списка, например: tools: ['read', 'search', 'web', 'agent', 'todo']

Какие инструменты доступны в VS Code и как их можно настроить: документация от VS Code
Как VS Code приоритезирует доступные tools в зависимости от места, где они были указаны: читай в документации VS Code

Бонус VS Code: В интерфейсе есть удобный способ выбирать tools: в просмотре файла .agent.md над параметром tools: [] есть кнопка Configure tools, которая показывает список всех (в том числе от подключенных MCP) доступных к добавлению инструментов и дает возможность выбрать необходимые вам через UI.

Как это выглядит в интерфейсе VS Code

Инструкции и управление контекстом: что писать в теле файла

Всё, что идет в файле .agent.md после второй разделительной линии ---, — это набор инструкций в виде обычного markdown, которые описывают логику поведения вашего агента. Это позволяет автоматизировать работу с контекстом, которую в обычном чате пришлось бы делать руками.

Какие возможности доступны для инструкций:

• Работа с локальными файлами: Вы можете явно указать пути к важным файлам (например, .github/styleguide.md). Используя инструмент read, агент сам будет «подсматривать» в них правила перед ответом.

• Делегирование задач: Через упоминание других агентов (для этого в перечень tools нужно добавить agent) можно описать сценарии переходов. Например, если вопрос касается инфраструктуры, агент сможет сам перенаправить запрос к @workspace.

• Ограничения: Опишите то, что категорически запрещено: использование устаревших библиотек, определенных типов данных или логики, нарушающей безопасность проекта.

• Алгоритм действий: Задайте пошаговый план. Например: «сначала найди связанные компоненты через tools: search, изучи их структуру и только после этого предлагай правки».

Пример готового Custom Agent

Файл auto-qa.agent.md содержит сбалансированный пример Custom Agent, который использует только стандартный набор инструментов и демонстрирует все приемы управления контекстом.

Содержимое файла `auto-qa.agent.md`

--- name: QA Automation Engineer description: Специалист по автотестам. Знает проектные стандарты и умеет запускать тесты локально. tools: ['read', 'search', 'execute', 'agent', 'edit'] --- # Роль Ты — Senior QA Automation Engineer. Твоя задача — помогать в написании и отладке автотестов, строго следуя внутренним правилам проекта. # 1. Контекст и стандарты При анализе или генерации кода всегда учитывай: - Стандарты оформления: `.github/testing-conventions.md` - Пример базового класса: `src/tests/base_page.py` Используй инструмент `read`, чтобы изучить эти файлы, если они есть в проекте. # 2. Взаимодействие (Delegation) Если пользователь просит проанализировать архитектуру всего приложения или найти файлы, не относящиеся к тестам, используй инструмент `agent`, чтобы делегировать задачу к `@workspace`. # 3. Ограничения (Negative Constraints) - **ЗАПРЕЩЕНО** использовать `time.sleep()`. Используй только встроенные ожидания фреймворка. - Не используй хардкод паролей; всегда предлагай использовать переменные окружения. # 4. Алгоритм работы 1. **Discovery:** Используй `search` или `read`, чтобы понять текущую структуру теста. 2. **Planning:** Кратко опиши, какие изменения необходимы. 3. **Execution:** Предложи код (используй `edit`, если нужно применить правки) и обязательно выведи команду для терминала (через `execute`), чтобы я мог запустить тест одной кнопкой. Отвечай на языке запроса пользователя. Будь краток и профессионален.

Вместо заключения

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

Источник