Введение
Если ИИ-агенты безупречно функционируют в Jupyter notebook, но дают сбои сразу в production — из-за таймаутов при вызовах API, искаженных ответов больших языковых моделей или внезапных ограничений скорости — знайте, это распространенная ситуация.
Развертывание агентов полно сюрпризов, а главная трудность заключается в грамотной обработке неудач. Для решения не требуются масштабные фреймворки: эти пять декораторов Python избавят от множества неприятностей.
1. Автоматические повторные попытки с экспоненциальной задержкой
Любой ИИ-агент общается с внешними API, и рано или поздно они подводят. OpenAI может выдать ошибку 429 из-за превышения лимита скорости, или возникнет кратковременный сбой сети. В таких случаях агент не должен сразу сдаваться.
Декоратор @retry оборачивает функцию: при возникновении указанной ошибки он делает паузу и повторяет вызов. Экспоненциальная задержка ключева: время ожидания удваивается с каждой попыткой — 1 секунда, затем 2, 4 и дальше. Так избегают нагрузки на перегруженный API.
Простую реализацию можно собрать с помощью time.sleep() и цикла, либо сразу взять готовый декоратор @retry из библиотеки Tenacity. Важно правильно настроить типы исключений: повторять при ошибках соединения и лимитах скорости, но игнорировать неудачные промты, которые провалятся снова.
2. Защита от таймаутов
Вызовы больших языковых моделей иногда зависают. Это редкость, но когда случается, агент простаивает, пользователь видит спиннер, а в параллельных потоках вся цепочка блокируется.
Декоратор @timeout устанавливает жесткий лимит времени выполнения функции. Если за 30 секунд, например, ничего не вернулось, срабатывает TimeoutError, который легко перехватить. Обычно задействуют модуль signal для синхронного кода или asyncio.wait_for() в асинхронных сценариях.
В сочетании с декоратором повторов получается мощный тандем: зависший вызов прерывается таймаутом, а логика retry запускает новую попытку. Это устраняет целую группу production-сбоев.
3. Кэширование ответов
Такой подход резко сократит расходы на API. Если агент повторно вызывает одну и ту же функцию с одинаковыми параметрами — а это часто бывает в циклах многошагового рассуждения — нет смысла платить дважды.
Декоратор @cache сохраняет результат по аргументам входа. При повторном вызове с теми же параметрами возвращает кэш мгновенно. Встроенный functools.lru_cache подойдет для базовых случаев, но для агентов лучше вариант с поддержкой TTL, чтобы записи устаревали со временем.
Это особенно полезно для паттернов с инструментами: агенты перепроверяют данные или заново загружают контекст. Кэш ускоряет работу и уменьшает счета.
4. Проверка входных и выходных данных
Большие языковые модели непредсказуемы. Запросили JSON — получили markdown-блок с лишней запятой, которая ломает парсер. Декоратор @validate перехватывает такие проблемы на границе, не давая мусору проникнуть глубже.
На входе проверяет соответствие аргументов типам и ограничениям. На выходе подтверждает, что результат укладывается в схему, а Pydantic упрощает задачу. Определяете модель ответа, декоратор пытается распарсить вывод LLM. При неудаче — повтор, исправление или дефолт.
Главный плюс: тихие искажения данных превращаются в явные ошибки, которые ловятся сразу. Отладка занимает минуты, а не часы.
5. Цепочки запасных вариантов
В production ИИ-агентам нужен резервный план. Если основная модель недоступна, векторная база не отвечает или инструмент выдает ерунду — система должна продолжить работу, а не рухнуть.
Декоратор @fallback определяет последовательность альтернативных функций. Сначала пробует главную, при ошибке переходит к следующей. Например, от GPT-4.5 к Claude, затем к локальной Llama. Или от живого запроса к БД к кэш-снимку и хардкоду.
Реализация проста: декоратор принимает список fallback-функций и проходит по ним при сбоях. Можно добавить логирование на каждом шаге, чтобы понять причину деградации. Этот подход стандартен в production ML-системах, а декоратор держит логику отдельно от бизнеса.
Заключение
Декораторы — недооцененная фича Python для создания надежных ИИ-агентов. Описанные пять шаблонов решают типичные сбои, с которыми сталкиваются после выхода из Jupyter.
Они отлично сочетаются: @retry поверх @timeout и @validate дает функцию, которая не зависает, не сдается быстро и не пропускает плохие данные. Добавьте retry к API-вызовам уже сейчас — и увидите, как упростится обработка ошибок, после чего декораторы захочется использовать повсеместно.