Работа с ИИ-агентами: контроль, логи и разбор ошибок

Последние полгода я веду несколько продакшен-агентов на Claude API и n8n: они принимают заявки, проверяют оплату через эквайринг T‑Bank, дёргают СДЭК за статусами доставки и отвечают клиентам в Telegram через aiogram-бота. Работа с ИИ-агентами на практике упирается не в промпты, а в то, что происходит после запуска: агент выбрал не тот инструмент, завис на повторных вызовах или тихо съел лимит токенов за час. Ниже разбираю, как я строю логирование, мониторинг и разбор ошибок на реальных проектах, без теории про идеальный промпт-инжиниринг.

Зачем контролировать агента, если он и так работает

На тестовых десяти заявках агент отрабатывает ровно. Проблемы начинаются на проде, когда параллельно прилетают тридцать запросов, у СДЭК на пару секунд подвисает API, а модель в ответ на таймаут решает повторить вызов инструмента оплаты вместо того, чтобы остановиться. Один из моих проектов на связке WooCommerce и эквайринга T‑Bank как раз так и словил задвоенный заказ: агент получил вебхук об оплате, начал создавать заказ, вызов завис, n8n перезапустил workflow по таймауту, а агент честно создал заказ второй раз, потому что не помнил о первой попытке.

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

Логирование действий ИИ-агента: что писать в лог

Я логирую не «весь диалог», а конкретные точки, где агент принимает решения и трогает внешние системы. Для каждого шага фиксирую пять вещей: какой инструмент вызван, с какими параметрами, что вернулось, сколько это заняло по времени и сколько стоило в токенах.

На практике это выглядит как обёртка вокруг каждого tool call, которая пишет структурированную запись в базу до и после вызова:

async def call_tool(tool_name, params, request_id):
    started = time.monotonic()
    logger.info("tool_call_start", extra={
        "request_id": request_id,
        "tool": tool_name,
        "params": params,
    })
    try:
        result = await tools[tool_name](**params)
        logger.info("tool_call_done", extra={
            "request_id": request_id,
            "tool": tool_name,
            "duration_ms": int((time.monotonic() - started) * 1000),
        })
        return result
    except Exception as exc:
        logger.error("tool_call_failed", extra={
            "request_id": request_id,
            "tool": tool_name,
            "error": str(exc),
        })
        raise

Такую запись я храню в Postgres, а не в текстовом файле на сервере: через полгода в проекте с оплатами и доставками счёт логов идёт на сотни тысяч строк, и без индекса по request_id и дате искать конкретный инцидент неудобно.

Мониторинг агентов в реальном времени

Логи хороши для разбора задним числом, но узнавать о падении агента от клиента в поддержке, а не от системы, неприятно. На проектах с n8n я завожу отдельный alert-канал в Telegram: если workflow падает в Error-ветке, туда летит сообщение с номером заявки и текстом ошибки. Для aiogram-ботов то же самое делаю через middleware, который перехватывает исключения на каждом апдейте и шлёт краткую сводку админу, не роняя диалог с пользователем.

Отдельно слежу за лимитами внешних API, потому что агент, который сам решает, когда дёргать инструмент, может случайно устроить локальный наплыв запросов на СДЭК или платёжный шлюз. У СДЭК, например, есть ограничение на число запросов в минуту на один аккаунт, и если агент в цикле опроса статусов доставки не соблюдает паузы, часть запросов начинает падать с кодом 429, а это уже проблема на всю очередь заявок, а не на одну.

Из метрик, которые реально смотрю каждый день:

• Доля успешных выполнений workflow за сутки
• Среднее время ответа агента от запроса до финального сообщения
• Расход токенов в день в пересчёте на рубли
• Число повторных вызовов одного и того же инструмента подряд (признак зацикливания)

Разбор ошибок: типовые сбои ИИ-агентов и как их ловить

За практику накопился набор ошибок, которые повторяются от проекта к проекту почти в одном и том же виде.

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

Работа с ИИ-агентами в связке с n8n и Telegram-ботами

Типовая для меня схема: n8n оркестрирует вызовы к Claude API и внешним сервисам, aiogram-бот выступает интерфейсом для клиента, а Postgres хранит и диалоги, и логи инструментов в одной базе, чтобы можно было связать сообщение пользователя с конкретным вызовом СДЭК или платёжного шлюза. При падении любого шага в Error-ветке n8n уходит уведомление в отдельный служебный чат, а пользователь получает нейтральное сообщение вида «уточняю детали, отвечу через пару минут» вместо голого технического текста об ошибке.

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

Сколько стоит внедрение контроля и логирования

Цена зависит от того, строится агент с нуля или логирование и мониторинг добавляются к уже работающему решению.

Срок на базовую связку агент плюс логирование плюс алерты в Telegram обычно укладывается в 2-3 недели, если интеграций с внешними системами немного (одна CRM, один платёжный шлюз, одна служба доставки). Каждая дополнительная система увеличивает и срок, и объём тестов на дублирование запросов.

Частые вопросы

Сколько логов реально нужно хранить агенту в проде

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

Как понять, что агент завис в цикле, а не просто долго думает

Смотрю на количество повторных вызовов одного и того же инструмента с одинаковыми или почти одинаковыми параметрами подряд. Если за один диалог инструмент вызван больше 3-4 раз без изменения результата, это уже не «долго думает», а зацикливание, и оркестратор должен оборвать цепочку сам.

Можно ли обойтись без базы данных для логов, если проект небольшой

На старте можно писать логи в файл, но как только в цепочке появляется оплата или отправка заказа, я сразу переношу их в Postgres: без индекса по request_id найти конкретный инцидент среди тысяч строк в текстовом файле долго и неудобно.

Что делать, если агент регулярно упирается в лимит запросов у СДЭК или другого API

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