Subagents

Субагент — это вспомогательный агент, которому основной агент WorkAI поручает часть работы вместо того, чтобы делать её самому. Субагент работает в отдельном контексте, ничего не знает о вашей переписке кроме присланного ему задания и возвращает родительскому агенту одно итоговое сообщение — не весь ход поиска. В основном диалоге остаётся только выжимка.

Зачем это нужно #

Объёмное исследование кода — «где используется эта функция», «как устроен этот модуль» — порождает десятки прочитанных файлов и результатов поиска. Всё это забивает контекст основной сессии, хотя для самого диалога бесполезно. Субагент берёт эту работу на себя: копается в коде у себя и отдаёт только находки.

Как это работает #

• Синхронно. Основной агент ждёт результата — фоновых субагентов, за которыми можно было бы наблюдать отдельно, в WorkAI нет.
• Без памяти о разговоре. Субагент видит только текст задания, которое ему сформулировал основной агент. Поэтому задание пишется самодостаточным: весь нужный контекст и явное указание, что именно вернуть.
• Одно итоговое сообщение. Субагент не ведёт диалог и не задаёт вам уточняющих вопросов — инструмент вопросов ему отключён, как и общий список задач. Его ответ попадает основному агенту, а не вам напрямую: чтобы вы увидели итог, основной агент пересказывает его сам.
• Виден в чате. Пока субагент работает, в ответе разворачивается блок с его именем и коротким описанием задачи, а внутри — что он сейчас делает: ищет код, читает файлы, обращается к сети. Когда субагент закончил, блок сворачивается — раскрыть его можно в любой момент.

Что субагент получает на входе и что возвращает #

Контекст субагента собирается заново, а не копируется из вашего диалога.

Получает:

• текст задания от основного агента — единственный источник знаний о задаче;
• правила проекта и AGENTS.md — они подмешиваются субагенту по тем же условиям, что и основному диалогу;
• список доступных скиллов — субагент может загрузить нужный сам;
• список других субагентов — если вложенность разрешена (см. ниже).

Не получает: историю переписки, файлы и вкладки, которые вы прикрепили к своему запросу, общий список задач. Всё, что должно дойти до субагента, основной агент обязан пересказать в задании.

Возвращает одно текстовое сообщение — то, что он написал последним. Промежуточные шаги в основной диалог не попадают. При этом правки файлов, которые субагент успел сделать, остаются в проекте и показываются в родительском ответе как обычные изменения: изолирован контекст, а не рабочая копия.

Подтверждения тоже не изолированы. Если субагенту нужно разрешение — запустить команду в терминале, применить правку, — запрос всплывает в основном чате, рядом с полем ввода, с указанием, какой именно субагент его ждёт. Что и когда спрашивается, задаётся режимом запуска.

Встроенный субагент Explore #

Explore — единственный субагент, который WorkAI подключает сам. Это быстрый режим исследования кодовой базы: он параллелит независимые поиски и чтения вместо того, чтобы делать их по очереди, и возвращает список найденного — файлы, функции, похожие уже существующие решения, которые можно взять за образец.

Explore работает только на чтение. Ему доступны поиск по коду, чтение файлов, обращение к веб-страницам, чтение задач и pull request'ов GitHub, а также просмотр вывода терминала и упавших тестов — без запуска команд и без правки файлов. Порождать других агентов Explore тоже не может: это запрещено ему в файле описания.

Настраивать Explore не нужно, и выбрать его вручную в списке режимов нельзя: он не пользовательский режим, а именно вспомогательный агент. Попросить его в чате словами при этом можно — например «изучи, где обрабатывается авторизация»: основной агент делегирует эту работу Explore.

На какой модели работает субагент #

Всегда на модели Auto — той, которую WorkAI назначает централизованно (см. Автовыбор модели), независимо от того, какую модель вы выбрали для основного диалога. Смысл в предсказуемой цене и скорости вспомогательной работы: поиск и суммаризация не должны идти по цене фронтирной модели.

Поле model в файле собственного субагента при таком запуске игнорируется, как и попытка модели указать модель самой. Дополнительно субагент запускается с пониженным уровнем рассуждений — вспомогательная задача не требует глубокого reasoning.

Как посмотреть, чем занят субагент #

Блок субагента в ответе — не просто индикатор. В нём видно имя агента, короткое описание задачи, текущий инструмент и время работы («Работает 12 с» → «Работал 12 с»); во всплывающей подсказке заголовка — сколько этот субагент стоил. Блок кликабельный: он открывает переписку субагента целиком — задание, все его шаги и итог. В окне агентов это отдельный чат, в обычном окне — вкладка редактора только для чтения.

Если вы предпочитаете видеть всю активность субагента прямо в теле ответа, выключите настройку chat.subagents.useRichRendering (по умолчанию включена). В окне агентов она ни на что не влияет: там субагент всегда открывается отдельным чатом.

Как субагенты влияют на списание Ⓦ #

Запрос субагента — это отдельный запрос к модели, и он оплачивается как обычный: по токенам модели, на которой субагент выполняется. Отдельного тарифа или скидки на субагентов нет.

На практике: пять субагентов, запущенных параллельно, — это пять контекстов и пять оплачиваемых запросов. Но идут они на Auto, а не на выбранную вами модель, поэтому объёмный поиск через субагента обычно обходится дешевле, чем тот же поиск руками основного агента на дорогой модели. Полный каталог и цены — в моделях и тарифах.

Могут ли субагенты запускать субагентов #

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

Вложенность включается настройкой chat.subagents.allowInvocationsFromSubagents. Когда она включена, глубина дерева ограничена пятью уровнями: дойдя до предела, WorkAI просто перестаёт выдавать инструмент запуска на следующий уровень.

Сколько субагентов работает одновременно #

Основной агент может запустить несколько субагентов в одном шаге — они пойдут параллельно. Типичный сценарий, на который настроен агент, — 2–4 субагента за раунд, по одному на независимую область задачи (например, фронтенд и бэкенд). Разом порождать десяток агент не станет: для задачи с множеством подзадач он разбивает их на раунды.

Сверху есть жёсткий предел клиента: одновременно исполняется не больше 8 параллельных инструментов, включая субагентов. Значение меняется настройкой workai.chat.parallelToolConcurrencyLimit (от 1 до 32).

В каких режимах доступно делегирование #

Делегирование работает в режиме Agent. В Plan Mode модель получает жёстко ограниченный набор инструментов — только чтение, поиск и планировочная обвязка, — и инструмент запуска субагентов из него вырезается: субагент получил бы полный набор инструментов и тем самым обошёл бы ограничения режима. В Ask доступны только инструменты чтения и поиска, запуска субагентов среди них тоже нет.

На бесплатных моделях каталога инструкция о делегировании агенту не отправляется — там он выполняет исследование сам.

Собственные субагенты #

Свой субагент — это markdown-файл с YAML-шапкой и телом-промптом. Тот же формат, в котором описаны и встроенные агенты WorkAI.

Где размещать файл #

Путь	Область действия
.github/agents/	Проект — файл лежит в репозитории и доступен всем, кто открывает эту рабочую область.
.claude/agents/	Проект — совместимость с форматом Claude Code.
~/.claude/agents/	Все проекты текущего пользователя (формат Claude Code).
~/.copilot/agents/	Все проекты текущего пользователя (формат Copilot).

Файл называйте <имя>.agent.md. В самих папках агентов подходит и обычный .md: любой markdown-файл, лежащий прямо в такой папке, кроме README.md, читается как описание агента. Именно прямо в папке: файл, убранный на уровень глубже в подкаталог-категорию, найден не будет.

Поля в шапке файла #

Поле	Назначение
name	Имя агента, как оно показывается в интерфейсе. Если не указано — берётся из имени файла.
description	Что агент делает и когда его использовать. По этому тексту модель решает, делегировать ли ему задачу, — пишите конкретно.
argument-hint	Подсказка о том, какие входные данные агент ожидает.
tools	Набор инструментов, доступных агенту. Если не указан — агент получает набор родителя.
model	Модель для этого агента. При запуске в качестве субагента игнорируется — субагенты всегда идут на Auto.
agents	Каких вспомогательных агентов этому агенту разрешено использовать; '*' — всех доступных, [] — никого.
user-invocable	Можно ли выбрать агента вручную в интерфейсе. По умолчанию — можно.
disable-model-invocation	true запрещает вызывать агента как вспомогательного: он остаётся только ручным.
handoffs	Кнопки перехода к другому агенту после того, как этот закончил работу.
target	К какому окружению относятся поля шапки (vscode, github-copilot).
hooks	Хуки жизненного цикла, действующие только пока активен этот агент.

Тело файла под шапкой — обычный текст: инструкция, что агент должен делать, когда его вызывают.

Открывающий --- должен быть самой первой строкой файла, и обе строки --- идут без отступа — иначе шапка не распознаётся и поля не прочитаются.

Пример #

Файл .github/agents/code-reviewer.agent.md:

---
name: Code Reviewer
description: Ревью diff перед коммитом — ищет баги, проблемы безопасности и отклонения от стиля проекта.
tools: ['search', 'read']
user-invocable: true
---
Ты — ревьюер кода. Проверяй только переданный diff, не весь проект.

## Что искать
- Логические ошибки и краевые случаи
- Утечки секретов и небезопасные паттерны
- Отклонения от стиля соседнего кода

## Формат ответа
Список замечаний с указанием файла и строки, без общих слов.

Как ограничить набор инструментов #

Поле tools — это белый список: что перечислено, то агенту и доступно. Если поля нет, агент наследует те инструменты, которые включены в текущем диалоге, — то есть ограничения нет.

Перечислять можно группами и поштучно:

Значение	Что даёт
read	Чтение файлов и блокнотов
search	Поиск по коду и по файлам
edit	Создание и правка файлов
execute	Команды в терминале, задачи, тесты
web	Обращение к веб-страницам
agent	Запуск вспомогательных агентов
todo	Список задач
vscode	Служебные инструменты редактора
execute/getTerminalOutput	Отдельный инструмент из группы — через слэш
github/issue_read	Инструмент, который приносит расширение или MCP-сервер

Составлять список руками необязательно: над строкой tools в открытом файле агента появляется ссылка Configure Tools… — она открывает тот же список инструментов, что и в чате, с галочками, и переписывает строку за вас.

Три ограничения действуют поверх вашего списка и снимаются только тем, что описано выше: пока агент работает как субагент, у него нет списка задач, нет инструмента вопросов к пользователю и нет запуска субагентов (если не включена вложенность).

Файлы агентов в формате Claude #

Файлы из .claude/agents/ читаются как есть, включая привычные там имена инструментов: Read, Grep, Glob, Bash, Edit, Write, WebFetch, WebSearch, Task, NotebookEdit, AskUserQuestion. WorkAI переводит их в свои эквиваленты сам — переписывать шапку не нужно.

Обратная сторона: имя, которого нет в этом списке, при переводе просто отбрасывается. Если после переноса агент оказался без части инструментов, проверьте tools — скорее всего, там имя, которого WorkAI не знает.

Как создать субагента #

• /create-agent в чате — опишите роль словами, агент соберёт файл сам.
• Команда New Custom Agent… — спросит каталог и имя и создаст заготовку с заполненной шапкой.
• Руками — заведите файл по одному из путей выше. Пока файл открыт в редакторе, WorkAI подсвечивает ошибки шапки: неизвестные поля, неверные типы значений, устаревшие атрибуты.

Как проверить, что субагент подхватился #

Команда Настроить пользовательские агенты… (палитра команд или меню настройки чата → Пользовательские агенты) открывает список всех найденных файлов агентов. Если вашего в списке нет — проблема в расположении или в имени файла, а не в содержимом. Оттуда же агент открывается на редактирование и включается/выключается.

Второй способ — журнал: команда Open Agent Debug Logs. Событие Agent Discovery показывает, какие файлы агентов найдены, какие пропущены и почему (ошибка разбора, агент выключен). Событие Resolve Customizations показывает следующий шаг — что из найденного дошло до модели; агент с запрещённым автовызовом будет там помечен как пропущенный.

Как запустить своего субагента #

• Автоматически. Если в шапке не стоит disable-model-invocation: true, основной агент может делегировать задачу сам, ориентируясь на description. Поэтому описание — самое важное поле файла: в каждый запрос попадают только имя, описание и подсказка об аргументах каждого агента, по ним и принимается решение.
• Через список режимов. Агент с user-invocable: true (по умолчанию) появляется в переключателе режимов рядом с Agent, Ask и Plan — тогда вы говорите с ним напрямую, а не через основного агента.
• Словами в чате. Достаточно назвать агента по имени в запросе — основной агент передаст задачу именно ему.

Отдельного вызова через /имя для агентов нет: слеш-команды в WorkAI относятся к скиллам и промптам.

Чем субагент отличается от скилла и от правила #

Все три — файлы в репозитории, которые меняют поведение агента, но включаются они по-разному и стоят разного.

	Правило	Скилл	Субагент
Когда включается	Всегда или по glob-паттерну файлов	Когда модель сочла задачу подходящей	Когда агент решил делегировать кусок работы
Что это по сути	Постоянное требование	Процедура «как делать X»	Исполнитель с собственным заданием
Свой контекст	Нет	Нет	Да
Отдельный оплачиваемый запрос	Нет	Нет	Да
Что видно в диалоге	Ничего	Загруженная инструкция	Итог работы, шаги скрыты

Практическое правило: если задача решается за один-два шага и промежуточные результаты не мешают — это скилл. Если работа объёмная и её «черновик» не должен попасть в основной диалог (исследование, сбор контекста, независимая проверка) — это субагент. Промежуточный вариант тоже есть: скилл с полем context: fork выполняется отдельным вспомогательным агентом, оставаясь скиллом по способу вызова.

Почему субагент не запускается #

Разберите по порядку — причины идут от самых частых:

• Файла нет в списке агентов. Проверьте расположение: файл должен лежать прямо в одной из папок агентов, а не в подкаталоге, и иметь расширение .agent.md (либо любое .md, кроме README.md, если он в самой папке агентов).
• Ошибка в шапке. Если YAML не разобрался, файл пропускается целиком и агента как будто нет. В Agent Discovery он будет с причиной пропуска.
• Агент выключен в списке «Настроить пользовательские агенты…».
• Пустое или размытое description. Модель выбирает агента по описанию; «помогает с кодом» не даёт ей никакого сигнала. Пишите, при каких задачах агента звать.
• Стоит disable-model-invocation: true — тогда агент доступен только вручную, сам он выбран не будет.
• Имя названо неточно. Обращение по имени работает при точном совпадении, включая регистр. Если имя не совпало, основной агент получит ошибку «агент не найден» и, скорее всего, сделает работу сам.
• Текущий режим ограничивает список. Поле agents в шапке активного режима задаёт, кому он вправе делегировать: agents: [] запрещает делегирование полностью.
• Режим не Agent. В Plan и Ask запуска субагентов нет вовсе.

Дальше #

• Режим планирования и его ограничения — /docs/agent/plan-mode
• Как WorkAI выбирает модель автоматически — /docs/model-router
• Переиспользуемые процедуры для агента — /docs/skills
• Постоянные инструкции для проекта — /docs/rules
• Полный каталог моделей и тарифы — /docs/models-and-pricing