Как ИИ-агенты обрабатывают ошибки инструментов

Вы просите агента забронировать столик, он дёргает API ресторана, а тот отвечает 503 Service Unavailable. Дальше два сценария. В первом агент ловит ошибку, ждёт пару секунд и повторяет запрос. Во втором — принимает текст ошибки за результат, галлюцинирует подтверждение брони и радостно рапортует об успехе. Разница между этими сценариями и есть тема, которую редко выносят в маркетинговые презентации: как агент обрабатывает сбои инструментов (tool calls).

Фреймворки вроде LangGraph, OpenAI Agents SDK и Anthropic Claude Agent SDK за последний год сместили акцент с «как заставить модель вызвать функцию» на «что делать, когда вызов провалился». Потому что в продакшене инструменты падают постоянно: таймауты, лимиты запросов, невалидные аргументы, которые сгенерировала сама модель.

Почему ошибки инструментов — отдельная проблема

Классический сбой в коде вы видите как исключение и обрабатываете его try/except. С агентом всё сложнее: результат вызова инструмента возвращается обратно в модель как текст, и модель решает, что делать. Если вернуть ей сырой стектрейс на 40 строк, она либо застрянет, либо начнёт выдумывать.

Типичные категории отказов, с которыми сталкивается агент¹:

• Транзиентные — временные: таймаут сети, 429 Too Many Requests, 503. Лечатся повтором с задержкой.
• Ошибки аргументов — модель передала невалидный JSON, пропустила обязательное поле, перепутала тип. Лечатся переформулировкой вызова.
• Терминальные — ресурс не существует, нет прав доступа, товар удалён. Повтор бессмысленен, нужно менять план.
• Пустой результат — инструмент отработал, но ничего не нашёл. Формально не ошибка, но агент часто трактует её как провал.

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

Стратегии обработки

Повтор с экспоненциальной задержкой

Базовый приём для транзиентных ошибок. Агент повторяет вызов, увеличивая паузу между попытками (1 секунда, 2, 4) и ограничивая их число — обычно тремя-пятью. Реализуется на уровне обёртки инструмента, а не самой модели: незачем тратить токены на то, чтобы модель «думала» о повторе сетевого таймаута.

Возврат структурированной ошибки в модель

Если вызов провалился из-за аргументов, ошибку возвращают обратно в контекстное окно² в понятном виде: не стектрейс, а сообщение вроде «Поле date должно быть в формате YYYY-MM-DD, получено '12 марта'». Модель исправляет аргумент и вызывает инструмент заново. Это работает, потому что LLM хорошо реагируют на конкретные инструкции по исправлению.

Ограничение бюджета и человек в цикле

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

Валидация до вызова

Часть ошибок ловят заранее, проверяя аргументы по схеме (например, через Pydantic или JSON Schema) до того, как запрос уйдёт во внешний сервис. Не дошло до API — не потратили время и не получили лишний вектор для галлюцинации.

Как это устроено в разных фреймворках

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

Точные названия параметров и хелперов сверяйте с актуальной документацией: API этих SDK меняются от версии к версии, и то, что называлось одним образом полгода назад, сегодня может быть переименовано.

Кому это пригодится и кому нет

Пригодится, если:

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

Можно не углубляться, если:

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

Практический минимум

Если запускаете агента в продакшен, заложите хотя бы это:

1. Классифицируйте ошибки на транзиентные, аргументные и терминальные — обрабатывайте по-разному.
2. Транзиентные повторяйте с задержкой и лимитом попыток, не гоняя их через модель.
3. Аргументные возвращайте модели в человекочитаемом виде, чтобы она исправилась.
4. Терминальные не повторяйте — либо меняйте план, либо эскалируйте человеку.
5. Поставьте потолки на число шагов и на стоимость задачи.
6. Логируйте каждый вызов инструмента и его исход — без этого вы не поймёте, где агент буксует.

¹ Единой отраслевой классификации ошибок инструментов нет — деление ниже отражает распространённую практику, а не стандарт.

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