Агенты не выполняются в Битрикс: диагностика

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

Первая проверка: активен ли агент вообще

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

Проверка на автоматическую деактивацию

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

Необработанное исключение внутри функции агента

<?php

function syncStockBalances(): string
{
    try {
        // ... логика синхронизации ...
    } catch (\Throwable $e) {
        AddMessage2Log('Agent error: ' . $e->getMessage(), 'my.module');
    }

    return 'syncStockBalances();';
}

Исключение, вылетевшее из тела функции без перехвата, прерывает выполнение до оператора return — с точки зрения системы это выглядит так же, как отсутствие возврата строки: агент деактивируется. Обёртка в try/catch с логированием ошибки — необходимый минимум для диагностики подобных сбоев в будущем, а не только способ их избежать.

Нет запуска: визитов нет, cron не настроен

Если агент активен и корректно возвращает строку самовызова, но всё равно не выполняется вовремя — вероятная причина в отсутствии триггера запуска. Штатный механизм "по визитам" срабатывает при заходе любого посетителя на сайт, но на малопосещаемых страницах или в ночное время визитов может просто не быть. Решение — настройка системного cron на файл agents.php, не зависящего от реального трафика.

Превышение времени выполнения агента

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

Проверка через ручной запуск

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

Логирование как обязательная практика

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

Частые ошибки

• Функция не возвращает строку повторного вызова. Самая частая причина автоматической деактивации агента.
• Нет системного cron, только визиты. Агент срабатывает непредсказуемо редко на малопосещаемых страницах.
• Отсутствует логирование результата работы агента. Невозможно быстро отличить причину сбоя без дополнительной диагностики.
• Тяжёлая операция без разбивки на порции. Прерывание по ограничению времени выполнения посередине работы.

Итог

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