CAgent в 1С-Битрикс: что такое агент и как его зарегистрировать

CAgent — класс модуля main в 1С-Битрикс, реализующий механизм псевдо-планировщика задач («агентов»). В отличие от системного cron, агенты не запускаются по расписанию операционной системы — они выполняются при обычных HTTP-запросах к сайту в момент, когда наступает их время. Битрикс проверяет очередь агентов при каждом запросе и запускает те, у которых время следующего запуска (NEXT_EXEC) меньше или равно текущему времени.

Как работает механизм агентов Битрикс

При каждом HTTP-запросе к сайту Битрикс выполняет проверку таблицы b_agent. Если находится запись, у которой NEXT_EXEC <= NOW() и ACTIVE = 'Y', соответствующая PHP-функция или статический метод вызывается прямо в рамках текущего запроса. После выполнения NEXT_EXEC обновляется на NOW() + AGENT_INTERVAL.

Агент-функция обязана возвращать своё собственное имя в виде строки — это сигнал Битриксу перепланировать агент на следующий интервал. Если функция возвращает пустую строку или null, агент автоматически деактивируется.

Регистрация агента через CAgent::AddAgent

<?php

// Регистрация агента (обычно в init.php или обработчике события установки модуля)
\CAgent::AddAgent(
    '\Local\User\BirthdayCouponSender::runAgent();', // Имя функции/метода
    'main',   // Модуль-владелец
    'N',      // Переодический агент: Y — да, N — однократный
    86400,    // Интервал в секундах (86400 = 1 сутки)
    '',       // Дата первого запуска (пусто — сейчас)
    'Y'       // Активен: Y/N
);

Проверка существующего агента перед регистрацией:

<?php

$agentName = '\Local\User\BirthdayCouponSender::runAgent();';

$existing = \CAgent::GetList([], ['NAME' => $agentName])->Fetch();
if (!$existing) {
    \CAgent::AddAgent($agentName, 'main', 'N', 86400, '', 'Y');
}

Агент-метод, который правильно возвращает своё имя:

<?php

public static function runAgent(): string
{
    try {
        self::sendCoupons();
    } catch (\Throwable $e) {
        self::log('error', [
            'message' => $e->getMessage(),
            'file'    => $e->getFile(),
            'line'    => $e->getLine(),
        ]);
    }

    return self::AGENT_NAME; // '\Local\User\BirthdayCouponSender::runAgent();'
}

Параметры CAgent::AddAgent

Параметр	Описание
`$name`	Имя PHP-функции или статического метода со скобками и точкой с запятой: `'MyClass::myMethod();'`
`$module`	Модуль-владелец (влияет на удаление агентов при деинсталляции модуля)
`$period`	`Y` — периодический, `N` — однократный (выполнится один раз и деактивируется)
`$interval`	Интервал в секундах между запусками
`$datecheck`	Дата первого запуска в формате `d.m.Y H:i:s`. Пустая строка — немедленно.
`$active`	`Y` — активен, `N` — создать, но не запускать

Отличие CAgent от системного crontab

Критерий	CAgent	Системный cron
Запуск	При HTTP-запросах к сайту	По расписанию ОС, независимо от трафика
Точность времени	±несколько минут (зависит от трафика)	Точно по расписанию (до минуты)
Требования	Только Битрикс	Доступ к crontab на сервере
Работа при простое	Не запускается, если нет посетителей	Запускается всегда
Ресурсы	Выполняется в процессе PHP FPM, замедляет запрос	Отдельный процесс, не влияет на HTTP

Когда использовать CAgent: для несрочных фоновых задач на сайтах с постоянным трафиком, где нет доступа к crontab хостинга (например, на виртуальном хостинге). Подходит для индексации, отправки уведомлений, пересчёта статистики.

Когда использовать crontab: для задач с точным временем запуска, тяжёлых обходов больших таблиц, скриптов с длительным временем выполнения. Системный cron не замедляет HTTP-запросы пользователей и гарантирует запуск даже при нулевом трафике.

Типичная ошибка: агент-функция не возвращает своё имя. В этом случае после первого выполнения Битрикс деактивирует агент, и задача никогда не запустится повторно. Всегда заканчивайте агент-функцию строкой return 'MyClass::myMethod();';.