Субагенты¶

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• поиск по индексу кодовой базы (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 создаст файл с шаблоном и откроет его в редакторе; текст шаблона подставляется на языке интерфейса;
• включить или отключить роль — переключатель в строке роли; отключение запрещает новые запуски, но не отменяет уже работающую задачу;
• изменить роль — иконка редактирования открывает исходный Markdown-файл;
• удалить роль — корзина в строке с подтверждением; удаляется только файл роли, история и результаты прошлых задач сохраняются.

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

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

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

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

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

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

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

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

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

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

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

Причины:

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

Решения:

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

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

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

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

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

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

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

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

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