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

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

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

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

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

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

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

**Получает:**

- текст задания от основного агента — единственный источник знаний о задаче;
- [правила проекта](/docs/rules) и `AGENTS.md` — они подмешиваются субагенту по тем же условиям, что и основному диалогу;
- список доступных [навыков](/docs/skills) — субагент может загрузить нужный сам;
- список других субагентов — если вложенность разрешена (см. ниже).

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

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

Подтверждения тоже не изолированы. Если субагенту нужно разрешение — запустить команду в терминале, применить правку, — запрос всплывает в основном чате, рядом с полем ввода, с указанием, какой именно субагент его ждёт. Что и когда спрашивается, задаётся [режимом запуска](/docs/agent/security/run-modes).

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

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

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

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

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

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

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

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

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

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

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

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

На практике: пять субагентов, запущенных параллельно, — это пять контекстов и пять оплачиваемых запросов. Но идут они на Auto, а не на выбранную вами модель, поэтому объёмный поиск через субагента обычно обходится дешевле, чем тот же поиск руками основного агента на дорогой модели. Полный каталог и цены — в [Моделях и ценах](/docs/models-and-pricing).

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

По умолчанию — нет. Субагент работает в изоляции и не порождает других субагентов.

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

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

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

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

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

Делегирование работает в режиме **Агент**. В режиме [Планирование](/docs/agent/plan-mode) модель получает жёстко ограниченный набор инструментов — только чтение, поиск и планировочная обвязка, — и запуск субагентов из него вырезается: субагент получил бы полный набор инструментов и тем самым обошёл бы ограничения режима. В режиме «Обсуждение» доступны только чтение и поиск, запуска субагентов среди них тоже нет.

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

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

Свой субагент — это 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`:

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

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

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

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

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

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

| Значение | Что даёт |
| :--- | :--- |
| `read` | Чтение файлов и Jupyter Notebook |
| `search` | Поиск по коду и по файлам |
| `edit` | Создание и правка файлов |
| `execute` | Команды в терминале, задачи, тесты |
| `web` | Обращение к веб-страницам |
| `agent` | Запуск вспомогательных агентов |
| `todo` | Список задач |
| `vscode` | Служебные инструменты редактора |
| `execute/getTerminalOutput` | Отдельный инструмент из группы — через слэш |
| `github/issue_read` | Инструмент, который приносит расширение или [MCP-сервер](/docs/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 подсвечивает ошибки шапки: неизвестные поля, неверные типы значений, устаревшие атрибуты.

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

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

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

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

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

Отдельного вызова через `/имя` для агентов нет: слеш-команды в WorkAI относятся к [навыкам](/docs/skills) и промптам.

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

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

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

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

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

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

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

## Дальше

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