Субагенты¶

Субагент — это временный помощник, которого основной агент запускает в фоне для самостоятельного решения исследовательской подзадачи. Каждый субагент работает в изолированном read-only контексте, параллельно с основным диалогом, а готовый результат автоматически возвращается агенту.

В CLI агент решает сам, когда завести субагента, — обычно тогда, когда для ответа или следующего шага нужна информация, которую можно собрать независимо. Повлиять на поведение агента можно формулировками: например, попросить изучить несколько вариантов параллельно или вернуть только выводы. Готовые роли можно запускать и явно — меткой @agent:<имя> в начале сообщения (см. Явный запуск роли).

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

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

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

Защита от зависаний:

• лимит шагов — не более 64 шагов на одну задачу;
• сторожевой таймер (watchdog) — если субагент долго не завершает ни одного шага, задача помечается как зависшая: её можно продлить или отменить;
• бюджет времени — по умолчанию 30 минут, после чего задача останавливается;
• кулдаун опроса — агент не может проверять статус задачи чаще, чем раз в 30 секунд.

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

Ожидание субагентов¶

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

Настройка allowParentToContinue меняет поведение: агент продолжает работу, не дожидаясь субагентов, а готовые результаты приходят по мере готовности — на ближайшей границе инструментов или отдельным ходом.

Остановка с субагентами¶

Клавиши Esc и Ctrl + C во время ответа останавливают не только ответ агента, но и всех работающих субагентов сессии: остановленный агент не должен продолжать тратить запросы через субагентов. Если субагенты были запущены, в диалоге появится сообщение, сколько из них остановлено.

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

Доставка результата¶

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

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

Роли субагентов¶

Помимо универсального субагента-исследователя, можно описывать собственные роли — именованные наборы инструкций и ограничений в Markdown-файлах.

Роль — это файл <workspace>/.koda/agents/<имя>.md или ~/.kodacli/agents/<имя>.md (глобальная папка). Файл в workspace перекрывает глобальный с тем же именем.

---
name: reviewer
description: Проверка диффа и поиск проблем в изменённом коде
model: inherit
tools:
  - read_file
  - search_file_content
---

Проверяй изменения на типичные ошибки: утечки ресурсов, обработку ошибок,
нарушения стиля проекта. Возвращай список проблем с путями и строками.

Поля файла:

• name — имя роли; строчные буквы, цифры и дефисы, до 64 символов; должно совпадать с именем файла;
• description — обязательное описание роли, до 500 символов; по нему агент выбирает роль и работает поиск в подсказках @;
• model — необязательное поле; точное имя модели или inherit — наследовать модель из настроек субагентов;
• reasoningEffort — необязательное поле; уровень рассуждений для запросов роли; без ключа — уровень из настроек;
• tools — необязательное поле; список только из «читающих» инструментов — роль может лишь сузить общий набор, расширить права нельзя;
• текст после шапки — инструкции роли: они попадают в системный промпт субагента вместо универсальных.

Ограничения каталога: файл не больше 64 КиБ, до 128 ролей в папке, символические ссылки и вложенные папки не читаются. Файл с неизвестным полем шапки, пустым телом или превышающий лимиты не загружается — он показывается с ошибкой в списке ролей.

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

Управление ролями¶

Каталог ролей и действия над ними — командой /subagents roles:

/subagents roles
/subagents roles enable <имя>
/subagents roles disable <имя>
/subagents roles create <имя> [--global]
/subagents roles delete <имя>

• без аргументов — каталог ролей: имя, источник (workspace или глобальная), модель, уровень рассуждений и ошибки файлов;
• enable / disable — включить или выключить роль по имени, не трогая файл; выключенные роли хранятся в настройке disabledAgentNames;
• create — создать файл роли из шаблона: с флагом --global — в ~/.kodacli/agents, без — в .koda/agents workspace; существующий файл не перезаписывается;
• delete — удалить файл роли.

Агент следит за папками ролей: изменение файла — сохранение в редакторе, удаление руками, команды другой сессии — подхватывается без перезапуска.

Явный запуск роли¶

Роль можно запустить самому, не полагаясь на решение модели: начните абзац сообщения меткой @agent:<имя>.

@agent:reviewer проверь незакоммиченные изменения

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

Пока набирается agent: после @, подсказки показывают все роли; после двоеточия список фильтруется по имени и описанию. То же правило действует в сообщениях из Telegram: @agent:reviewer проверь диф запускает роль до обращения к модели.

Панель агентов¶

За ходом задач удобно следить в интерактивной панели агентов. Откройте её клавишей F6 (см. горячие клавиши). Панель открывается в любой момент — в том числе пока основной агент отвечает, выполняет инструменты или ждёт подтверждения; новые события не перехватывают фокус ввода. Над строкой состояния отображается счётчик: сколько задач работает, завершено и требует внимания.

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

Действия над выбранной задачей:

• Стоп — остановить один субагент;
• Стоп всех — прервать все задачи текущей сессии разом;
• + Время — продлить работу зависшей задачи;
• Повторить — прогнать завершённую задачу заново;
• Возобновить — продолжить незавершённую задачу;
• Ответить — написать сообщение завершённому субагенту (см. Разговор с субагентом);
• Сжать — сжать историю завершённого субагента в одно резюме.

↑↓ — выбор задачи, Tab — переключение фокуса между зонами, Esc или F6 — вернуться к основному диалогу. Клавиши внутри панели управляют только панелью; Ctrl + C сохраняет обычное поведение — отмену запроса основного агента вместе с его субагентами (см. Остановка с субагентами).

Разговор с субагентом¶

Завершённого субагента можно продолжить собственным сообщением — командой /subagents prompt или кнопкой Ответить в панели.

Субагент сохраняет свою историю и описание задачи, но отвечает вам, а не агенту: результат такого хода не доставляется в основной диалог, агент о нём не узнаёт. Ответ можно прочитать в панели агентов или командой /subagents show.

Ход не блокируется выключенными субагентами: переключатель enabled ограничивает то, что запускает модель, а не вас.

Политика инструментов на один ход задаётся флагом --policy:

• read_only — по умолчанию; тот же набор, что у исследования;
• auto_edit — добавляет правку и создание файлов;
• yolo — ещё и выполнение команд.

Уровня «спросить» нет: субагенту некому задать вопрос, поэтому всё, что политика добавляет, работает без подтверждений.

Команды¶

Управление задачами из диалога — командой /subagents:

/subagents list
/subagents show <task_id>
/subagents cancel <task_id|all>
/subagents continue <task_id>
/subagents prompt <task_id> [--policy read_only|auto_edit|yolo] <message>
/subagents compress <task_id>
/subagents restart <task_id>
/subagents roles [enable|disable|create|delete] <имя>

• list — задачи текущей сессии: статус, число шагов, время работы, роль и занятость контекста каждой;
• show — полный результат одной задачи;
• cancel — остановить одну задачу или все запущенные;
• continue — продлить время зависшей задачи;
• prompt — отправить сообщение завершённому субагенту (см. Разговор с субагентом);
• compress — заменить всю историю завершённого субагента одним резюме и показать счётчик токенов «до → после»;
• restart — прогнать завершённую задачу заново или продолжить прерванную;
• roles — каталог ролей и управление ими (см. Управление ролями).

Настройка¶

Параметры субагентов задаются блоком subagents в settings.json:

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

Настройки применяются без перезапуска: CLI следит за файлом settings.json и подхватывает изменения секции subagents за доли секунды — даже если их внёс другой процесс, например Koda Desktop.

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

Инструмент run_subagent¶

Агент запускает субагентов инструментом run_subagent: он передаёт описание, полный текст задачи и имя роли, а также может проверить статус, продлить, возобновить или отменить задачу по её task_id.

Решение проблем¶

Агент не запускает субагентов¶

• проверьте, что блок subagents включён (enabled: true) — см. настройку;
• убедитесь, что модель поддерживает вызов инструментов — см. Модели.

Роль не запускается¶

• проверьте, что роль существует и включена — командой /subagents roles;
• убедитесь, что метка @agent:<имя> стоит в начале абзаца: метка посреди фразы или в блоке кода — обычный текст;
• проверьте, что модель роли доступна: роль с недоступной моделью помечается как недоступная в каталоге.

Задача не запускается: превышен лимит¶

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

Задача зависла¶

Если субагент давно не показывает прогресс, он помечается как зависший. Варианты действий:

• подождать — иногда шаг просто долгий, и прогресс возобновится;
• продлить задачу — командой /subagents continue или кнопкой «+ Время» в панели;
• отменить задачу — агент не станет перезапускать её сам, но может начать новое исследование, если вы попросите.