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

v0.2.0

Сила агентского режима в том, что он умеет не только рассуждать, но и действовать в пределах доступных ему возможностей. Именно поэтому он может продвигаться по задаче, а не просто предлагать идеи.

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

Что агент умеет делать¶

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

Читать и изучать проект¶

v0.2.0

Это особенно полезно в начале задачи, когда нужно сначала понять, как всё устроено.

При чтении файла или просмотре директории Koda подключает к результату инструкции проекта, которые к ним относятся, — включая файлы KODA.md и AGENTS.md из вложенных директорий. Так агент получает правила конкретного модуля только тогда, когда начинает с ним работать. Подробнее — в разделе «Инструкции во вложенных директориях».

Предлагать и вносить изменения¶

v0.2.0

Именно на этом этапе особенно важно держать под контролем чувствительные или большие изменения.

Правки применяются в фоне: редактирование и создание файлов не переключают активный редактор и не открывают новые вкладки — ваш курсор, выделение и несохранённый текст в текущем файле не меняются. Открыть изменённый файл можно в любой момент, кликнув по нему в чате. Изменения сохраняются на диск и поддерживают обычные Ctrl + Z / Ctrl + Shift + Z (на macOS — ⌘Z / ⇧⌘Z).

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

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

Использовать внешний контекст¶

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

Если вы заранее знаете, какие данные нужны, добавьте их сами через @. Чем контекст-провайдеры отличаются от инструментов, описано в разделе «Провайдеры и инструменты агента».

Запускать команды¶

v0.2.0

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

Агент корректно выполняет составные команды: цепочки через && и ||, перенаправления (>), многострочные команды и вложенные подоболочки.

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

Как выглядит команда в чате¶

v1.0.0

Команда отображается отдельным блоком, а не как обычный фрагмент кода:

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

Инструменты в Koda¶

Koda предоставляет набор встроенных инструментов для работы с проектом:

Большой вывод инструментов¶

v1.2.4

Результат одного вызова инструмента ограничен 2000 строк или 50 КиБ — как в Koda CLI. Ограничение действует для всех инструментов: встроенных, HTTP и MCP-серверов, а также на суммарный результат, если агент выполнил несколько вызовов одного инструмента за один шаг.

Если вывод не помещается в лимит:

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

Агент может прочитать полный вывод из сохранённого файла постранично инструментом read_file — без повторного запуска команды. Это экономит время и лимиты: например, длинный лог сборки или большой JSON-ответ не нужно получать заново.

Как управлять инструментами¶

В интерфейсе можно настроить политику для разных действий.

Обычно используются три режима:

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

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

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

Если агент использует слишком много действий¶

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

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