Агенты в 1С-Битрикс: создание фоновых задач и замена системного cron

Агенты Битрикс — встроенный планировщик задач. Они выполняются при каждом запросе к сайту (или по реальному cron) и позволяют запускать PHP-код по расписанию без настройки системного cron.

Как работают агенты

Битрикс хранит список агентов в таблице b_agent. При каждом хите проверяется: не пришло ли время запустить какой-нибудь агент. Если да — выполняется функция и планируется следующий запуск.

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

// Регистрируем агент — запускать каждые 3600 секунд (1 час)
\CAgent::AddAgent(
    'MyModule\\Agents\\CleanupAgent::run()',  // функция/метод
    'mymodule',       // модуль (можно пустую строку)
    'N',              // не разовый
    3600,             // интервал в секундах
    '',               // дата первого запуска (пустая = сразу)
    'Y',              // активен
    '',               // следующий запуск (авто)
    30                // приоритет
);

echo 'Агент зарегистрирован';

Функция агента

Функция должна возвращать своё имя для повторного запуска, или пустую строку для однократного выполнения:

namespace MyModule\Agents;

class CleanupAgent
{
    public static function run(): string
    {
        // Логика агента
        $db = \Bitrix\Main\Application::getInstance()->getConnection();
        $db->query(
            'DELETE FROM b_my_log WHERE DATE_CREATE < DATE_SUB(NOW(), INTERVAL 30 DAY)'
        );

        // Логируем
        \Bitrix\Main\Diag\Debug::writeToFile(
            'Cleanup done: ' . date('Y-m-d H:i:s'),
            '',
            '/bitrix/logs/cleanup.log'
        );

        // Возвращаем имя метода — агент запустится снова
        return __CLASS__ . '::run()';
    }
}

Управление агентами программно

// Получить список всех агентов
$agents = \CAgent::GetList(
    ['NEXT_EXEC' => 'ASC'],
    ['MODULE_ID' => 'mymodule']
);
while ($agent = $agents->Fetch()) {
    echo $agent['NAME'] . ' — ' . $agent['NEXT_EXEC'] . PHP_EOL;
}

// Деактивировать агент
\CAgent::DisableAgent($agentId);

// Удалить агент
\CAgent::RemoveAgent(
    'MyModule\\Agents\\CleanupAgent::run()',
    'mymodule'
);

// Запустить принудительно (сброс времени)
\CAgent::Execute($agentId);

Проблема: агенты не запускаются

Частая проблема — агенты не выполняются если на сайте мало трафика. Решение — подключить реальный cron:

# Добавляем в crontab (запускать каждую минуту)
* * * * * /usr/bin/php /var/www/html/bitrix/modules/main/tools/cron_events.php >> /var/log/bitrix-cron.log 2>&1

В настройках Битрикс (Настройки → Инструменты → Агенты) включите режим cron: «Агенты работают через cron».

Отладка агентов

// Временно добавить вывод в лог
define('AGENT_CHECK_PERIOD', 1); // проверять каждую секунду (только для отладки!)

// В php.ini или начале скрипта агента
ini_set('error_log', '/bitrix/logs/agents.log');

Агент vs реальный cron

Итог

Агенты Битрикс — удобный способ для лёгких задач по расписанию. Для production-проектов всегда подключайте реальный cron — это даёт точное время выполнения и не замедляет пользовательские запросы.