Субагенты

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

Встроенные агенты

Kodik поставляется с двумя встроенными профилями субагентов. Профиль выбирает персону, предпочитаемую модель и системный промпт дочернего агента; отдельного списка разрешённых инструментов у профиля нет.

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

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

В режиме «Стандартные подтверждения» Kodik запрашивает подтверждение перед запуском именованного профиля (implement или пользовательского агента); Автопилот и Полный доступ запускают именованный субагент без запроса (запуск research не требует подтверждения ни в одном режиме). Собственные вызовы инструментов дочернего агента в любом режиме проходят через ту же политику подтверждений, что и у родителя.

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

Инструмент sub_agent

Агент вызывает субагентов через инструмент sub_agent. Каждый вызов указывает:

• agent — какой профиль использовать (например, research, implement или идентификатор пользовательского агента).
• goal — описание задачи, которую получает субагент.
• scope — необязательный путь или область, в которой нужно оставаться.
• expectedDeliverables — необязательное описание того, что субагент должен вернуть.

Субагент запускается как реальная дочерняя задача со своей историей сообщений и API-вызовами. Вызовы инструментов дочернего агента остаются привязаны к родительской chat-сессии, поэтому терминальные процессы, Stop и очистка сессии остаются в рамках этой задачи. Вложенные запросы к модели через Kodik proxy тоже несут id родительской задачи, поэтому usage относится к чату, который запустил дочернего агента. Результаты возвращаются родителю в виде отчёта в формате markdown. Полный справочник по инструментам см. в разделе Инструменты.

Субагенты наследуют ровно те инструменты провайдера, что доступны родительскому ходу — после фильтрации по режиму, пользовательских настроек инструментов, отключённых действий, доступности 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:<name>.
• Пользовательские агенты имеют пространство имён user:<name>.
• Агенты плагинов имеют пространство имён <pluginId>:<name>.

Передайте полный идентификатор с пространством имён инструменту sub_agent, если хотите вызвать конкретный пользовательский агент.

Ограничения

Все субагенты — встроенные и пользовательские — имеют следующие ограничения:

• Наследуемые инструменты — субагенты получают те же действующие инструменты, что и родительский ход, включая MCP-инструменты, когда они доступны родителю.
• Запрет рекурсивного делегирования — инструмент sub_agent всегда убирается внутри субагента, независимо от заголовка профиля.
• Родительские панели остаются родительскими — инструменты todo_write и generate_plan всегда убираются внутри субагента; список todo и панель плана принадлежат родительскому разговору, а прогресс дочернего агента показывают шаги его карточки.
• Неинтерактивность — инструменты ask_questions и check_understanding убираются внутри субагента; выводы и блокирующие вопросы он возвращает родителю в итоговом отчёте.
• Режимы только для чтения остаются только для чтения — режимы Ask, Plan и Educator по-прежнему могут делегировать, но их дочерние запуски наследуют родительский набор инструментов только для чтения.
• Вызовы инструментов остаются структурированными — вызовы инструментов субагента используют ту же нативную нормализацию аргументов, что и родительские вызовы, включая пакетные ходы. Панель активности показывает нормализованные дочерние шаги вместо сырого JSON вызовов инструментов. Само делегирование не обрывается по фиксированному таймауту; если список файлов или текстовый поиск субагента выполняется слишком долго, Kodik возвращает ошибку инструмента, чтобы он сузил запрос вместо зависания всего запуска.

Когда использовать субагенты

Субагенты наиболее полезны, когда:

• Нужно собрать широкий контекст из нескольких областей кодовой базы до того, как родитель вносит изменения.
• Чётко ограниченная задача реализации может выполняться изолированно, не затрагивая файлы, которые также редактирует родитель.
• Вы хотите, чтобы родитель координировал несколько параллельных исследований и синтезировал результаты.

Для небольших сфокусированных задач, когда у агента уже достаточно контекста, вызов субагента добавляет накладные расходы без пользы.