Агенты в Битрикс: создание, настройка, запуск по cron

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

Разберём, как создать своего агента, чем принципиально отличается запуск на хитах от запуска по cron и почему второй вариант почти всегда правильнее.

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

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

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

Создание агента

Функция агента — обычная статическая функция или метод класса:

<?php // /local/php_interface/classes/Agents.php

class ProjectAgents
{
    public static function clearOldOrders()
    {
        // ... полезная работа ...

        // обязательно: возвращаем вызов самого себя
        return 'ProjectAgents::clearOldOrders();';
    }
}

Регистрация агента — разовое действие, а не код в init.php:

<?php

CAgent::AddAgent(
    'ProjectAgents::clearOldOrders();',  // вызов
    'main',                              // модуль
    'N',                                 // только один экземпляр
    86400,                               // интервал в секундах
    '',                                  // дата первой проверки
    'Y',                                 // активность
    '',                                  // дата первого запуска
    30                                   // сортировка
);

Важный момент: не помещайте AddAgent в init.php. Файл выполняется на каждом хите, и агент будет добавляться снова и снова. Регистрацию делают один раз — из установщика модуля или временным скриптом.

Проверить, что агент уже существует, можно перед добавлением:

<?php

$exists = CAgent::GetList([], ['NAME' => 'ProjectAgents::clearOldOrders();'])->Fetch();

if (!$exists) {
    CAgent::AddAgent('ProjectAgents::clearOldOrders();', 'main', 'N', 86400);
}

Два режима запуска

Здесь лежит главное решение, влияющее и на скорость сайта, и на надёжность.

На хитах — режим по умолчанию

Агенты проверяются и выполняются во время обработки обычного запроса посетителя. Человек открыл страницу — и заодно, не подозревая об этом, запустил обмен с 1С.

Проблемы очевидны:

• Случайный посетитель ждёт. Ему досталась страница, на которой отработал тяжёлый агент.
• Ограничение по времени. Агент упирается в max_execution_time, как обычный скрипт.
• Нет посетителей — нет выполнения. Ночью, когда трафика нет, агенты не запускаются. Утром они выполнятся все разом.
• Непредсказуемое время. «Раз в час» превращается в «когда повезёт».

На cron — правильный вариант

Агенты выполняются отдельным процессом по расписанию операционной системы.

Настройка состоит из двух шагов. Сначала отключаем запуск на хитах — в /bitrix/php_interface/dbconn.php:

<?php
define('BX_CRONTAB_SUPPORT', true);

Затем добавляем задание в crontab:

*/5 * * * * /usr/bin/php -f /home/site/public_html/bitrix/modules/main/tools/cron_events.php

Что это даёт:

• посетители не ждут выполнения фоновых задач;
• нет ограничения по времени выполнения;
• агенты работают независимо от посещаемости;
• расписание становится предсказуемым.

Отдельно нужно перевести на cron и отправку почты — за неё отвечает свой скрипт. Механика очереди писем разобрана в статье CEvent::CheckEvents() в Битрикс.

Что делать, если агенты не выполняются

Порядок проверки:

1. Откройте список агентов в разделе Настройки → Настройки продукта → Агенты. Посмотрите на дату следующего запуска.
2. Дата в прошлом и не меняется — агент либо не запускается вообще, либо падает с ошибкой.
3. Проверьте активность — агент мог быть отключён.
4. Проверьте, что функция существует. Если класс не подключён, вызов молча не сработает.
5. Проверьте cron, если включён режим BX_CRONTAB_SUPPORT: задание может быть не добавлено, и тогда агенты не выполняются вообще.
6. Посмотрите лог PHP — фатальная ошибка внутри агента остановит его.

Ловушка при переходе на cron: если константу объявили, а задание в crontab не добавили, агенты перестают работать полностью. Сайт при этом выглядит здоровым — просто перестаёт приходить почта и не обновляются данные.

Отладка

Агент выполняется в фоне, где вывод на экран бессмысленен. Логируйте начало и конец:

<?php

public static function clearOldOrders()
{
    \Bitrix\Main\Diag\Debug::writeToFile(
        'старт',
        'clearOldOrders',
        '/local/logs/agents.log'
    );

    try {
        // ... работа ...
    } catch (\Throwable $e) {
        \Bitrix\Main\Diag\Debug::writeToFile(
            $e->getMessage(),
            'clearOldOrders ERROR',
            '/local/logs/agents.log'
        );
    }

    return 'ProjectAgents::clearOldOrders();';
}

Обратите внимание на try/catch: необработанное исключение внутри агента прерывает выполнение всей очереди агентов, а не только этого одного.

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

• Нет return с вызовом. Агент отрабатывает один раз и удаляется, а разработчик неделю ищет, почему задача выполнилась только однажды.
• Регистрация в init.php. Дубликаты агентов накапливаются с каждым хитом.
• Тяжёлая работа в одном проходе. Обработка десятков тысяч записей упрётся во время выполнения. Разбивайте на порции с сохранением позиции.
• Константа BX_CRONTAB_SUPPORT без задания в crontab. Агенты не выполняются совсем.
• Нет обработки исключений. Одна ошибка останавливает всю очередь.
• Агент выполняется дольше своего интервала. Запуски накладываются друг на друга — используйте флаг «только один экземпляр».

Итог

Агенты — штатный планировщик 1С-Битрикс. Периодический агент обязан возвращать строку собственного вызова, иначе выполнится однократно. Регистрировать агента нужно один раз, а не на каждом хите.

Главное решение при настройке — перевести агенты на cron. Запуск на хитах означает, что фоновые задачи выполняются за счёт случайных посетителей, упираются в ограничение времени и не работают ночью. Настройка занимает пять минут и заметно улучшает и скорость сайта, и предсказуемость фоновых задач.