Почему ИИ-агент не работает

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

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

Что значит «агент не работает»

Внешне одинаково, внутри по-разному. Одно и то же слово используют для четырёх разных отказов, и лечатся они по-разному.

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

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

Агент не заканчивает. Ходит по кругу, упирается в таймаут, съедает бюджет. Правила остановки.

Агент делает лишнее. Трогает то, чего трогать не должен был. Права.

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

Агент не видит нужный контекст

Самая частая причина. Агент отвечает уверенно и неверно, потому что нужных данных в запросе просто не было.

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

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

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

Инструмент возвращает слишком много

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

Как это выглядит: первые два-три шага агент отрабатывает нормально, на четвёртом начинает путаться, на пятом отвечает так, будто забыл задачу. Он и правда её забыл — она утонула среди тридцати тысяч токенов выгрузки.

Лечение на стороне инструмента, а не модели:

• Возвращайте только нужные поля. Не весь объект, а три поля из сорока.
• Ограничивайте число элементов. Двадцать строк и признак «есть ещё» вместо тысячи строк.
• Отдавайте ссылку вместо содержимого, если содержимое может понадобиться, а может и нет.
• Обрезайте текст ошибки. Полная трассировка стека в истории агента не помогает никому.

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

История переполнена

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

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

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

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

Права шире задачи

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

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

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

Нет критерия готовности

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

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

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

Агент ходит по кругу

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

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

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

Инструкции противоречат друг другу

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

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

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

Как искать причину по шагам

Шесть шагов, по порядку. Смена модели — шаг пятый, а не первый.

1. Возьмите один неудачный прогон и прочитайте журнал целиком. Не выборку, не сводку — весь прогон от первого запроса до последнего.
2. Найдите первый шаг, где результат разошёлся с ожидаемым. Дальше смотреть бессмысленно: всё последующее — следствие.
3. Проверьте вход этого шага. Было ли в нём всё нужное. Если нет — причина в контексте, дальше не идите.
4. Проверьте выход инструментов на предыдущих шагах. Объём, формат, признаки обрезки.
5. Повторите тот же шаг вручную на той же модели и на более сильной позиции. Если на сильной получается, а на слабой нет — причина в модели.
6. Проверьте инструкции на конфликт и правила остановки на наличие.

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

Какие риски стоит закрыть заранее

Три, и все три — про последствия, а не про качество.

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

Необратимые действия. Всё, что нельзя отменить, проходит через подтверждение человеком. Список таких действий составляется письменно.

Данные. Агент, у которого есть доступ к внутренним документам и к внешнему интернету одновременно, — это канал утечки. Разводите такие права по разным прогонам.

Какие ошибки повторяются чаще всего

Четыре штуки, и все четыре — попытки лечить следствие.

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

Добавляют инструкций в промпт. Каждая новая строка увеличивает шанс конфликта с уже написанными.

Увеличивают окно контекста вместо того, чтобы сократить вход. Работает до следующего раза, стоит дороже, качество к концу прогона всё равно падает.

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

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

Чего мы не утверждаем

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

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

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

Что нужно, чтобы попробовать

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

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

Что держать в голове

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

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

Права и правила остановки не улучшают агента, но определяют цену его ошибки. Ставить их надо до первого запуска, а не после первого инцидента. Как мы проверяем факты и почему у каждой цифры стоит дата — на странице о проекте. Завести ключ и проверить свой шаг: keydealer.ru/login.