# Субагенты > Как Kodik запускает дочерние задачи для исследования и реализации, и как создавать собственные профили агентов. Источник: https://docs.kodik.ru/agent/subagents Субагенты позволяют Кодику делегировать сфокусированную работу дочерним задачам. Каждый субагент работает в собственном контекстном окне и возвращает результат родительскому агенту. Это сохраняет контекст родителя чистым, пока исследование или реализация выполняются параллельно или последовательно. ## Встроенные агенты Kodik поставляется с двумя встроенными профилями субагентов. Профиль выбирает персону, предпочитаемую модель и системный промпт дочернего агента; отдельного списка разрешённых инструментов у профиля нет. **`research`** — исследователь, ориентированный на факты: собирает информацию, составляет карту кодовой базы и сверяет данные, прежде чем родитель примет решение. Он предпочитает инструменты чтения, но наследует тот же действующий набор инструментов, что и родительский ход. **`implement`** — исполнитель, ориентированный на реализацию: ограниченные по объёму изменения, команды и проверка результата. Он тоже наследует действующий набор инструментов родительского хода и подчиняется текущему режиму подтверждений. В режиме «Стандартные подтверждения» Kodik запрашивает подтверждение перед запуском именованного профиля (`implement` или пользовательского агента); Автопилот и Полный доступ запускают именованный субагент без запроса (запуск `research` не требует подтверждения ни в одном режиме). Собственные вызовы инструментов дочернего агента в любом режиме проходят через ту же политику подтверждений, что и у родителя. Все субагенты неинтерактивны — инструменты вопросов убираются из дочерних запусков, — поэтому вместо вопросов пользователю они возвращают родителю выводы или описание блокеров. ## Инструмент `sub_agent` Агент вызывает субагентов через инструмент `sub_agent`. Каждый вызов указывает: - **agent** — какой профиль использовать (например, `research`, `implement` или идентификатор пользовательского агента). - **goal** — описание задачи, которую получает субагент. - **scope** — необязательный путь или область, в которой нужно оставаться. - **expectedDeliverables** — необязательное описание того, что субагент должен вернуть. Субагент запускается как реальная дочерняя задача со своей историей сообщений и API-вызовами. Вызовы инструментов дочернего агента остаются привязаны к родительской chat-сессии, поэтому терминальные процессы, Stop и очистка сессии остаются в рамках этой задачи. Вложенные запросы к модели через Kodik proxy тоже несут id родительской задачи, поэтому usage относится к чату, который запустил дочернего агента. Результаты возвращаются родителю в виде отчёта в формате markdown. Полный справочник по инструментам см. в разделе [Инструменты](https://docs.kodik.ru/agent/tools). Субагенты наследуют ровно те инструменты провайдера, что доступны родительскому ходу — после фильтрации по режиму, пользовательских настроек инструментов, отключённых действий, доступности MCP, подтверждений, хуков и текущего корня worktree. Поэтому дочерние запуски в режимах Ask, Plan и Educator остаются только для чтения: набор инструментов родителя в этих режимах только для чтения. Дочерние запуски в режимах Code и Debug могут использовать те же инструменты с возможностью записи и MCP-инструменты, что и родитель. Жёсткие исключения для дочерних запусков: сам `sub_agent` (убирается, чтобы исключить рекурсию), `todo_write` и `generate_plan` (панели todo и плана принадлежат родительскому разговору, а прогресс дочернего агента и так виден в шагах его карточки), а также интерактивные `ask_questions`/`check_understanding` (субагент не может обращаться к пользователю — вопросы и блокеры он возвращает в итоговом отчёте). ## Фоновые субагенты Параметр `background: true` инструмента `sub_agent` запускает дочернего агента, не останавливая родителя: инструмент сразу возвращает подтверждение запуска (с `agent_id`), и основной агент продолжает работать, пока «ребёнок» исследует. Когда дочерний агент завершается — успешно, остановлен или прерван — его отчёт автоматически возвращается в разговор: - Если ход родителя ещё выполняется, отчёт подкладывается в его следующий шаг. - Если чат уже простаивает, отчёт сам начинает новый ход и отображается компактной строкой «агент отчитался». Проверить фонового агента можно инструментом `agent_status` (по `agent_id` из подтверждения запуска); `wait: true` блокирует до завершения, когда результат нужен прямо сейчас. Отчёт, полученный через `agent_status`, считается доставленным — автоматическое уведомление для этого агента пропускается, и агент не получает одни и те же результаты дважды. Пока фоновые агенты работают: - Панель над полем ввода показывает, сколько агентов работает в фоне. Разверните её, чтобы увидеть цель и живые шаги каждого агента или остановить его кнопкой «Остановить». Панель привязана к сессии — каждый чат показывает только своих агентов. - Статус сессии в боковой панели остаётся «working», пока все её агенты не завершатся. - Остановка основного хода **не** останавливает фоновых агентов — они продолжают работать и отчитываются позже. Останавливайте их из панели или карточки, либо удалением сессии. Фоновые агенты работают без подтверждений, поэтому ограничены набором инструментов только для чтения (`read_file`, `glob`, `rg`, `codebase_search`, `read_lints`, `web_fetch`, `web_search`) — без редактирования, команд оболочки и браузера. Для делегирования с записью используйте обычный (не фоновый) вызов `sub_agent`. Перезапуск IDE прерывает ещё работающих фоновых агентов; при следующем сообщении агенту сообщается о прерывании, чтобы он мог перезапустить исследование, если оно всё ещё нужно. ## Пользовательские профили агентов Вы можете определять собственные профили субагентов в виде файлов `.md` с заголовком YAML. ### Поля заголовка ``` --- name: my-agent description: Однострочное описание, отображаемое главному помощнику. model: inherit color: blue --- Вы — субагент my-agent. Опишите поведение и ограничения здесь. Тело файла используется дословно как системный промпт агента. ``` | Поле | Описание | | ------------- | ----------------------------------------------------------------------------------------------- | | `name` | Короткий идентификатор (используется как id агента). | | `description` | Показывается главному помощнику при решении о делегировании. | | `model` | Необязательное предпочтение модели для этого профиля. `inherit` — использовать модель родителя. | | `color` | Необязательный цветовой маркер, отображаемый в настройках. | Используйте тело файла, чтобы описать желаемое поведение агента. Инструменты во время выполнения всегда определяются текущим режимом чата и настройками инструментов агента, а не каждым профилем. ### Где размещать файлы агентов | Область | Расположение | Примечания | | ---------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------- | | **Проект** | `.kodik/agents/*.md` в корне рабочего пространства | Добавляется в систему контроля версий; все участники команды получают одинаковых агентов. | | **Пользователь (глобально)** | `~/.kodik/Agents/*.md` | Личные агенты, не привязанные к проекту. | | **Плагин** | `<корень плагина>/agents/*.md` | Распространяются через систему плагинов. | Включённые проектные, пользовательские и плагинные профили перечисляются в системном промпте главного ассистента, чтобы он мог выбирать их для делегирования. Settings → Sub Agents и работающий ассистент находят эти пользовательские профили из одних и тех же источников. ### Именование и идентификаторы - Агенты проекта имеют пространство имён `project:`. - Пользовательские агенты имеют пространство имён `user:`. - Агенты плагинов имеют пространство имён `:`. Передайте полный идентификатор с пространством имён инструменту `sub_agent`, если хотите вызвать конкретный пользовательский агент. ## Ограничения Все субагенты — встроенные и пользовательские — имеют следующие ограничения: - **Наследуемые инструменты** — субагенты получают те же действующие инструменты, что и родительский ход, включая MCP-инструменты, когда они доступны родителю. - **Запрет рекурсивного делегирования** — инструмент `sub_agent` всегда убирается внутри субагента, независимо от заголовка профиля. - **Родительские панели остаются родительскими** — инструменты `todo_write` и `generate_plan` всегда убираются внутри субагента; список todo и панель плана принадлежат родительскому разговору, а прогресс дочернего агента показывают шаги его карточки. - **Неинтерактивность** — инструменты `ask_questions` и `check_understanding` убираются внутри субагента; выводы и блокирующие вопросы он возвращает родителю в итоговом отчёте. - **Режимы только для чтения остаются только для чтения** — режимы Ask, Plan и Educator по-прежнему могут делегировать, но их дочерние запуски наследуют родительский набор инструментов только для чтения. - **Вызовы инструментов остаются структурированными** — вызовы инструментов субагента используют ту же нативную нормализацию аргументов, что и родительские вызовы, включая пакетные ходы. Панель активности показывает нормализованные дочерние шаги вместо сырого JSON вызовов инструментов. Само делегирование не обрывается по фиксированному таймауту; если список файлов или текстовый поиск субагента выполняется слишком долго, Kodik возвращает ошибку инструмента, чтобы он сузил запрос вместо зависания всего запуска. ## Когда использовать субагенты Субагенты наиболее полезны, когда: - Нужно собрать широкий контекст из нескольких областей кодовой базы до того, как родитель вносит изменения. - Чётко ограниченная задача реализации может выполняться изолированно, не затрагивая файлы, которые также редактирует родитель. - Вы хотите, чтобы родитель координировал несколько параллельных исследований и синтезировал результаты. Для небольших сфокусированных задач, когда у агента уже достаточно контекста, вызов субагента добавляет накладные расходы без пользы.