Что сломалось? Инструмент Whatbroke для отладки ИИ-агентов: как отследить скрытые сбои и изменения

Зачем нужен Whatbroke: проблема скрытых поломок ИИ-агентов

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

Обычный текстовый diff здесь бессилен. Он сравнивает строки, а не логику. Если агент вчера искал информацию в базе, а сегодня решил ответить по памяти, diff ничего не заметит. Код не изменился, но поведение сломалось. Именно эту проблему решает Whatbroke - открытый CLI-инструмент, который сравнивает запуски агентов и подсвечивает скрытые аномалии: пропадающие вызовы инструментов, изменение аргументов, рост стоимости и задержек.

Разработчики, которые уже внедряют ИИ-агентов в production, сталкиваются с этой болью ежедневно. Модель обновилась, провайдер изменил API, промпт слегка подкрутили - и агент начинает вести себя иначе. Без автоматического контроля такие регрессии могут неделями оставаться незамеченными. Whatbroke делает этот контроль системным и воспроизводимым.

Как работает Whatbroke: прокси-режим и анализ логов

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

Прокси-режим: отладка без изменения кода

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

Настройка сводится к смене адреса, куда стучится агент. Вместо прямого обращения к API он идет через локальный прокси. Это добавляет небольшую задержку - обычно миллисекунды, - но для отладки и тестирования такой компромисс приемлем. В production прокси-режим использовать не стоит, но для CI и локальных экспериментов он подходит идеально.

Поддержка популярных форматов логов

Если команда уже собирает телеметрию через OpenTelemetry, Langfuse или LangSmith, Whatbroke умеет конвертировать эти логи в свой формат. Никакой двойной работы: данные, которые уже есть в системе мониторинга, становятся материалом для сравнения запусков. Это снижает порог входа - не нужно менять привычные инструменты, достаточно добавить Whatbroke как еще один слой анализа.

Какие сбои находит Whatbroke: примеры из практики

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

Пропадающие вызовы инструментов. Агент поддержки вчера обращался к базе знаний перед ответом, а сегодня - нет. Причина может быть в изменении промпта или в том, что модель стала самоувереннее после обновления. Результат: клиент получает ответ без проверки фактов. Whatbroke видит, что вызов search_knowledge_base исчез из трассировки, и помечает это как отклонение.

Изменение аргументов. Агент продолжает вызывать инструмент, но с другими параметрами. Например, раньше он указывал temperature=0.1 для генерации точных ответов, а теперь - temperature=0.7. Или модель по умолчанию сменилась с gpt-4o на gpt-4o-mini. Внешне поведение выглядит нормально, но качество ответов падает. Whatbroke сравнивает аргументы вызовов и показывает расхождения.

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

Рост задержек. Агент стал медленнее отвечать. Причин много: смена провайдера, увеличение длины промпта, лишние вызовы инструментов. Для пользователя задержка в две секунды вместо одной - это заметная разница. Whatbroke фиксирует время каждого шага и помогает найти узкое место.

Интеграция в CI/CD: автоматический контроль регрессий

Сценарий выглядит так: в CI-пайплайне после каждого коммита запускается тестовый прогон агента на наборе типовых задач. Whatbroke сравнивает свежие логи с эталонными - теми, что были записаны, когда агент работал корректно. Если обнаружены отклонения, пайплайн падает, а разработчик получает уведомление с конкретным списком различий.

Этот подход уже применяется в проектах, где стабильность агентов критична. Например, если вы поддерживаете SQL-агента, который генерирует запросы к базе данных, регрессия может привести к некорректным выборкам. О том, как организовать оценку качества таких агентов с помощью Langfuse и подхода LLM-as-a-Judge, мы рассказывали в разборе кейсов с митапа «ИИшная».

Whatbroke не требует переписывать пайплайн. Это легковесная утилита, которая запускается одной командой и возвращает код выхода: 0 - изменений нет, 1 - обнаружены отклонения. Ее можно встроить в GitHub Actions, GitLab CI, Jenkins или любой другой оркестратор.

Безопасность и локальность: данные остаются у вас

Whatbroke работает полностью локально. Логи агентов не отправляются на внешние серверы, не проходят через облачные сервисы и не попадают к третьим лицам. Для компаний, которые работают с чувствительными данными - финансовыми, медицинскими, персональными, - это принципиальное требование. Многие облачные решения для мониторинга агентов требуют отправки телеметрии вовне, что автоматически ставит крест на их использовании в regulated industries.

Локальность также означает, что инструмент продолжает работать без интернета. Вы можете запустить сравнение на изолированной машине, в закрытом контуре или на ноутбуке разработчика - результат будет одинаковым. Это особенно ценно для команд, которые уже используют локальные модели и агентов. Например, после того как xAI открыла исходный код терминального агента Grok Build, разработчики получили возможность запускать ИИ-агентов полностью на своих мощностях. Whatbroke органично дополняет такой стек, не нарушая принципа изоляции.

Ограничения и правильное позиционирование Whatbroke

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

Инструмент требует эталонных логов. Без них сравнение невозможно. Первый запуск всегда будет записью эталона, и только со второго прогона начнется анализ. Это значит, что в самом начале проекта, когда агент еще нестабилен, польза от Whatbroke ограничена. Но как только поведение зафиксировано, инструмент становится незаменимым.

Прокси-режим добавляет задержку. Для тестов и CI это некритично, но в production под нагрузкой лишний сетевой хоп может замедлить ответы. Разработчики Whatbroke прямо рекомендуют не использовать прокси на боевых серверах. Для мониторинга production-среды лучше полагаться на штатные системы телеметрии и импортировать логи постфактум.

Еще один нюанс: Whatbroke фокусируется на регрессиях поведения, а не на логических ошибках в коде. Если агент написан с багом, который стабильно воспроизводится, инструмент примет это поведение за эталон и не увидит проблемы. Поэтому его правильное место - в связке с классическим тестированием, а не вместо него. О том, как выстроить культуру автоматических проверок при работе с ИИ-кодом, мы писали в разборе подхода Роберта Мартина к коду нейросетей.

Как начать использовать Whatbroke: первые шаги

Whatbroke - проект с открытым исходным кодом. Установка стандартна для CLI-утилит: клонируете репозиторий, устанавливаете зависимости, запускаете. Документация на GitHub описывает базовые сценарии и флаги командной строки.

Простейший эксперимент занимает пять минут. Запустите агента через прокси, дайте ему пару тестовых задач, сохраните логи как эталон. Затем измените промпт или обновите модель, повторите прогон и сравните результаты командой whatbroke diff baseline.jsonl new_run.jsonl. Инструмент покажет, какие вызовы пропали, какие аргументы изменились и насколько выросла стоимость.

Для команд, которые уже используют VS Code с ИИ-агентами в отдельных процессах (о нововведениях версии 1.130 мы рассказывали в обзоре обновления редактора), Whatbroke может стать дополнительным уровнем контроля. Агент работает изолированно, а его поведение проверяется автоматически при каждом изменении кодовой базы.

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