CAgent — регистрация и частые ошибки агентов в Битрикс

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

Регистрация агента

<?php

CAgent::AddAgent(
    'syncStockBalances();',      // вызываемая функция как строка
    'my.module',                 // модуль, к которому привязан агент
    'N',                         // периодичность: N — по интервалу
    3600,                        // интервал в секундах
    '',                          // дата первого запуска (пусто — сейчас)
    'Y',                         // активен
    '',
    50                           // сортировка среди агентов
);

Ключевая особенность API агентов — функция передаётся не как callable, а как строка PHP-кода, которая будет выполнена через eval в момент срабатывания. Отсюда следует требование к сигнатуре: функция должна быть либо глобальной, либо доступной в этой строке без дополнительного контекста (например, статический метод класса).

Обязательное требование: функция должна возвращать себя

<?php

function syncStockBalances(): string
{
    // ... логика синхронизации остатков ...

    return 'syncStockBalances();'; // агент выполнится снова через заданный интервал
}

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

Обработка ошибок внутри агента

<?php

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

    return 'syncStockBalances();'; // выполнится снова, даже если была ошибка
}

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

Просмотр и управление агентами

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

Программное удаление агента

<?php

CAgent::RemoveAgent('syncStockBalances();', 'my.module');

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

Забытый агент после отладки

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

Требования к времени выполнения кроном

Агенты запускаются не сами по себе, а при заходе на сайт любого посетителя (если не настроен запуск по cron) или по системному cron через agents.php. На проектах с низкой посещаемостью и без настроенного cron-задания агенты могут срабатывать значительно реже заданного интервала — стоит убедиться, что для критичных по времени агентов настроен именно cron, а не расчёт на визиты пользователей.

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

• Функция не возвращает строку самовызова. Агент автоматически деактивируется после первого выполнения.
• Необработанное исключение внутри агента. Прерывает выполнение до return — тот же эффект деактивации.
• Забытый отладочный агент с коротким интервалом. Годами создаёт незаметную фоновую нагрузку на сервер.
• Расчёт на визиты вместо системного cron. Критичный по времени агент срабатывает непредсказуемо редко на малопосещаемых сайтах.

Итог

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