Субагенты¶

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

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

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

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

Субагенты решают обе проблемы:

• исследования идут параллельно с основной работой агента;
• в контекст основной сессии попадает только итоговый результат, а не вся промежуточная переписка.

Типичные сценарии:

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

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

Запуск задачи¶

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

Субагент получает:

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

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

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

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

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

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

Агент периодически проверяет статус субагентов и обновляет панель над чатом:

Изолированный контекст¶

Каждый субагент — отдельная сессия со своей историей. Он не видит переписку родительской сессии и получает только текст задачи. Это экономит контекст: основной диалог не разбухает от промежуточных шагов исследований.

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

Статусы и прогресс¶

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

Статусы задачи:

Ограничения и защита от зависаний¶

Чтобы субагент не работал бесконечно и не «залипал», есть несколько механизмов:

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

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

Продолжение задачи (resume)¶

Завершённую задачу субагента не обязательно запускать заново с нуля — агент может продолжить ту же сессию. Это происходит, когда субагент:

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

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

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

Особенности:

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

Как настроить¶

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

Важные особенности инструментов и лимитов описаны ниже.

Инструменты субагента¶

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

Дополнительно можно включить:

• поиск по индексу кодовой базы (codebase_tool);
• веб-поиск (search_web);
• поиск по документации (docs_search);
• редактирование файлов (edit_file);
• создание файлов (create_new_file);
• выполнение команд (run_terminal_command);
• MCP-инструменты — отдельные инструменты подключённых MCP-серверов.

Важные особенности:

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

MCP-инструменты субагентов¶

Субагентам можно разрешать отдельные инструменты подключённых MCP-серверов — по одному, на вкладке Субагенты (см. Как настроить).

Особенности:

• MCP-инструменты выключены по умолчанию: в списке настроек они сгруппированы по серверу, и каждый включается отдельно;
• разрешение не зависит от подтверждений инструментов основного агента: даже инструмент, который основной агент вызывает с подтверждением, субагент выполнит автоматически;
• пока субагенту разрешён хотя бы один MCP-инструмент, запускать субагентов может только режим агента;
• сам по себе MCP-инструмент не даёт субагенту права менять локальные файлы: без явного разрешения edit_file и create_new_file он остаётся исследователем;
• если сервер отключён или инструмент исчез из конфигурации, он остаётся в списке настроек как недоступный: выключите его или восстановите сервер.

Лимит одновременных задач¶

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

Увеличение лимита ускоряет широкие исследования, но расходует больше токенов и ресурсов. Для большинства сценариев достаточно значения по умолчанию.

Во время ожидания субагентов¶

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

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

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

Уровень рассуждений субагентов¶

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

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

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

Файл роли¶

Роль — это обычный Markdown-файл с YAML-заголовком (frontmatter) и текстом инструкций.

Файлы хранятся в двух местах:

• .koda/agents/<имя>.md в корне проекта — локальные роли;
• ~/.koda/agents/<имя>.md — глобальные роли, доступные во всех проектах.

Роль проекта с тем же именем перекрывает глобальную.

---
name: reviewer
description: Проверяет изменения на баги и регрессии
tools: [read_file, grep_search, file_glob_search, ls]
---
Проверяй изменения, не редактируя файлы.
По каждой проблеме укажи серьёзность, файл, доказательство и предлагаемое исправление.

Правила описания:

• name — обязательное поле; совпадает с именем файла без .md: строчные латинские буквы, цифры и дефис, до 64 символов;
• description — обязательное поле; короткое описание роли (до 500 символов), по нему агент понимает, для чего роль нужна;
• tools — необязательное поле; только сужает общий набор инструментов субагента, расширить права нельзя: список не задан — наследуется общий набор, список пуст — субагент работает без инструментов; помимо имён встроенных инструментов можно указывать адреса разрешённых MCP-инструментов вида mcp://<сервер>/<инструмент> — см. MCP-инструменты субагентов;
• model — необязательное поле; точное название модели для этой роли; не задано или inherit — используется общий выбор модели из настроек субагентности;
• текст после frontmatter — инструкции роли; они добавляются к промпту субагента вместо универсальных.

Файл больше 64 КиБ или каталог больше 128 ролей не принимаются.

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

Ролями удобно управлять прямо на вкладке Субагенты в настройках. Роли сгруппированы в две группы — «Глобальные субагенты» и «Локальные субагенты», внутри каждой группы отсортированы по алфавиту.

Возможные действия:

• создать роль — кнопка «+» в нужной группе: Koda создаст файл с шаблоном и откроет встроенный редактор роли; текст шаблона подставляется на языке интерфейса;
• включить или отключить роль — переключатель в строке роли; отключение запрещает новые запуски, но не отменяет уже работающую задачу;
• изменить роль — иконка редактирования открывает встроенный редактор роли, где можно поменять модель, уровень рассуждений, набор инструментов и инструкции;
• удалить роль — корзина в строке с подтверждением; удаляется только файл роли, история и результаты прошлых задач сохраняются.

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

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

Если хотите запустить роль напрямую, есть два способа:

• в меню @ выберите пункт «Субагенты» и нужную роль;
• или напишите в начале абзаца @agent:имя-роли, а после него — текст задачи.

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

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

Как помочь агенту использовать субагентов¶

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

• попросите исследовать несколько вариантов параллельно: «Сравни подходы A и B, изучи их независимо»;
• укажите, что результат нужен краткий: «Собери информацию и верни только выводы»;
• для чувствительных задач напомните границы: «Сначала изучи src/auth/, потом предложи план — ничего не меняй».

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

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

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

Причины:

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

Решения:

1. Откройте настройки и проверьте, включён ли переключатель Разрешить модели запускать субагентов на вкладке Субагенты.
2. Убедитесь, что выбрана модель с поддержкой инструментов — см. Модели.

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

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

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

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

Варианты действий:

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

Результат не пришёл¶

Если задача завершилась с ошибкой (например, из-за перезапуска Koda), агент получит уведомление о том, что задачу нужно запустить заново. Просто попросите его повторить исследование — агент может как запустить новую задачу, так и продолжить прежнюю сессию с сохранённой историей.