Многие уже используют 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)
Перед тем как перейти к пошаговой настройке, стоит проговорить несколько моментов. Это сэкономит время, если у вас «нет нужной кнопки» или агент не появляется в списке.
Функция Custom Agents в VS Code доступна начиная с версии VS Code 1.106. Если версия ниже — пункта меню для настройки агентов может не быть.
В Copilot Free plan функция custom instructions and agents на момент публикации статьи не включена — для создания кастомных агентов нужен платный план (например, Pro/Pro+ и выше). Планы и ограничения могут меняться, поэтому лучше свериться с актуальной страницей тарифов.
Некоторые возможности агентов в VS Code появляются раньше многих других IDE, но иногда помечаются как experimental (экспериментальные фичи) — из-за этого детали поведения могут отличаться между версиями. При этом базовый сценарий с
.agent.mdв workspace/user profile — это поддерживаемая часть функциональности.
Примечание: раньше эта настройка называлась custom chat modes (
.chatmode.md). VS Code всё ещё может распознавать такие файлы и предлагать миграцию в.agent.md.
Сначала нужно убедиться, что:
установлены расширения GitHub Copilot и GitHub Copilot Chat
вы авторизованы в GitHub аккаунт в VS Code (Copilot активирован)
у вас активна подписка Copilot, которая поддерживает нужные agent-функции
Теперь можем перейти непосредственно к настройке.
Способ 1 — Создание агента через GitHub Copilot Chat
Cамый простой путь через UI
Перед стартом прочитайте: Доступность и ограничения Custom Agents
В окне Copilot Chat под полем ввода сообщения (рядом с выбором моделей) найдите выпадающее меню Agent
В выпадающем списке выберите Configure Custom Agents....
В управлении агентами (еще один выпадающий список) нажмите + Create New Custom Agent....
Выберите расположение (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.
Укажите имя агента, например "AQA" (automation QA). Ограничения на имя файла: только символы:
.-_a-zA-Z0-9.
В выбранной локации появится файл
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.
Заполните шаблон под свою задачу. Минимально необходимо:
а) заполнить
descriptionв YAML заголовкеб) описать поведение агента в теле файла: что он делает, какие входные данные ожидает, в каком виде выдаёт результат (и где проходит граница — что он не должен делать)
Остальные параметры — опциональные.
Важно: шаблон от VS Code содержит
tools: []— пустой массив означает «не давать агенту инструменты» (он будет отвечать только текстом). Если вы хотите, чтобы агент мог работать с workspace, настройте tools или уберите это поле, чтобы действовали стандартные настройки.Список доступных конфигураций и опций для агента смотрите в разделе Конфигурации и полезные настройки.
Вернитесь в Copilot Chat: в выпадающем списке с агентами должен появиться ваш новый Custom Agent (обычно они подтягиваются автоматически).
Выберите своего агента вместо стандартного
Agent— и работайте в нужной роли и по заданным правилам.
Для наглядности и быстрого старта я добавила пример готово��о Custom Agent в конце статьи.
Способ 2 — Создание агента вручную, через создание файла в workspace
Будет полезно, если вы хотите добавить агента в репозиторий без UI — например, чтобы закоммитить файл и раздать его команде через PR.
Перед стартом прочитайте: Доступность и ограничения Custom Agents
В корне проекта создайте папку
.github/agents/<repo>/ .github/ agents/
Внутри папки создайте файл
agent_name.agent.md(Имя файла может содержать только символы:.,-,_,a-z,A-Z,0-9)
Скопируйте в файл шаблон (или сразу готовый пример 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.
Заполните шаблон под свою задачу. Минимально необходимо:
а) заполнить
descriptionв YAML заголовкеб) описать поведение агента в теле файла: что он делает, какие входные данные ожидает, в каком виде выдаёт результат (и где проходит граница — что он не должен делать)
Остальные параметры — опциональные.
Важно: шаблон от VS Code содержит
tools: []— пустой массив означает «не давать агенту инструменты» (он будет отвечать только текстом). Если вы хотите, чтобы агент мог работать с workspace, настройте tools или уберите это поле, чтобы действовали стандартные настройки.Список доступных конфигураций и опций для агента смотрите в разделе Конфигурации и полезные настройки.
Откройте Copilot Chat и проверьте список агентов (под полем ввода, рядом с выбором моделей): созданный Custom Agent должен появиться там автоматически.
Выберите своего агента вместо стандартного 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: | vscode |
tools | ✅ | ✅ | Доступные агенту инструменты. Список функций, которые агент может вызывать. Можно перечислять через запятую или списком. Ограничивает возможности агента ради безопасности или точности. | ['vscode', 'execute', 'read', 'search', 'web', 'agent', 'todo'] |
infer | ✅ | ✅ | Разрешение авто-вызова агента. Если | 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 (например, | Claude Sonnet 4.5 |
argument-hint | ❌ | ✅ | Подсказка в чате. Текст-плейсхолдер, который видит пользователь в поле ввода. Помогает понять, как пользователям взаимодействовать с custom agent. | "Укажите название тестового сценария и конфигурации браузера для запуска теста" |
handoffs | ❌ | ✅ | Интерактивные переходы. Список кнопок-действий, которые появляются после ответа агента. Позволяют быстро передать контекст другому агенту ( | - 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
Безопасность и Tools: Указывая конкретные инструменты в tools, вы ограничиваете «права» агента. Это хорошая практика, чтобы агент случайно не начал менять файлы, если он предназначен только для чтения документации.
Бонус VS Code: В интерфейсе есть удобный способ выбирать tools: в просмотре файла .agent.md над параметром tools: [] есть кнопка Configure tools, которая показывает список всех (в том числе от подключенных MCP) доступных к добавлению инструментов и дает возможность выбрать необходимые вам через UI.
Как это выглядит в интерфейсе VS Code
Инструкции и управление контекстом: что писать в теле файла
Всё, что идет в файле .agent.md после второй разделительной линии ---, — это набор инструкций в виде обычного markdown, которые описывают логику поведения вашего агента. Это позволяет автоматизировать работу с контекстом, которую в обычном чате пришлось бы делать руками.
Какие возможности доступны для инструкций:
Работа с локальными файлами: Вы можете явно указать пути к важным файлам (например,
.github/styleguide.md). Используя инструментread, агент сам будет «подсматривать» в них правила перед ответом.Делегирование задач: Через упоминание других агентов (для этого в перечень tools нужно добавить
agent) можно описать сценарии переходов. Например, если вопрос касается инфраструктуры, агент сможет сам перенаправить запрос к@workspace.Ограничения: Опишите то, что категорически запрещено: использование устаревших библиотек, определенных типов данных или логики, нарушающей безопасность проекта.
Алгоритм действий: Задайте пошаговый план. Например: «сначала найди связанные компоненты через tools:
search, изучи их структуру и только после этого предлагай правки».
На заметку: Хотя текстовые инструкции универсальны, возможность агента реально «сходить» в файл или запустить терминал зависит от поддержки конкретных инструментов в вашей IDE. Список может расширяться в зависимости от версии Copilot. Документация о tools в GitHub
Пример готового 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 переходит из режима «объясни мне базу» в режим реальной помощи по проекту. После того как агент начнет понимать специфику вашего кода с первого запроса, возвращаться к стандартному чату с бесконечными уточнениями вы не захотите.
