Агенты: отложенные задачи

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

Что такое агент и когда он нужен

Агенты — встроенный планировщик Битрикс. Информация о них хранится в таблице b_agent: имя функции, интервал, время следующего запуска, признак периодичности. Ядро проверяет таблицу и вызывает те агенты, у которых подошло время.

Агент уместен, когда задачу нужно выполнять регулярно и в фоне:

• периодическая выгрузка заказов во внешнюю систему;
• очистка устаревших корзин, сессий, временных файлов;
• пересчёт остатков, отправка напоминаний, генерация отчётов;
• импорт данных по расписанию.

Добавление агента

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

CAgent::AddAgent(
  '\App\Agents\Sync::run();', // имя функции
  'my.module',        // модуль
  'N',             // критичность периода
  3600,            // интервал, сек
  '',              // дата проверки
  'Y',            // активность
  ''             // дата первого запуска
);

Регистрировать агент из собственного модуля правильно в методе DoInstall(), а удалять через CAgent::RemoveAgent() в DoUninstall(). Простую функцию без модуля можно добавить и напрямую, но модульный путь чище.

Требования к функции агента

Функция агента обязана вернуть собственное имя строкой, чтобы ядро перепланировало следующий запуск. Если функция не вернёт имя (вернёт пустоту или false), агент будет удалён из b_agent после выполнения.

namespace App\Agents;
class Sync {
  public static function run() {
    // полезная работа
    self::doSync();
    return '\App\Agents\Sync::run();'; // перепланировать
  }
}

Периодичность: is_period и next_exec

Поведение агента зависит от признака периодичности (is_period) и времени следующего запуска (next_exec).

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

Как агенты запускаются: хиты и cron

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

Поэтому на боевых проектах агенты переводят на cron. Тогда браузерный запуск отключают, а планировщик ОС дёргает скрипт /bitrix/modules/main/tools/cron_events.php по расписанию.

Перевод агентов на cron

Настройка выполняется в два шага.

1. В /bitrix/php_interface/dbconn.php отключить запуск на хитах: define('BX_CRONTAB_SUPPORT', true);
2. Добавить задание в crontab, например каждую минуту:

*/1 * * * * /usr/bin/php -f /var/www/html/bitrix/modules/main/tools/cron_events.php

Подводные камни

• Долгий агент на хитах тормозит сайт и может упереться в лимит времени PHP. Тяжёлые задачи — только на cron.
• Наложение запусков. Если агент не успевает отработать за интервал, при некорректной настройке может стартовать повторно. Защищайтесь блокировкой (файловый lock, семафор).
• Забытый возврат имени приводит к «исчезновению» агента после первого выполнения.
• Дубли появляются при повторной регистрации без проверки. Перед AddAgent проверяйте наличие через CAgent::GetList().

Итог

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

Мы настраиваем агенты и cron на нагруженных проектах, разносим тяжёлые задачи в очереди и защищаем их от наложений. Если нужна автоматизация фоновых процессов или корректная инфраструктура запуска — поможем спроектировать и внедрить.