Автопилоты

Автопилоты позволяют агентам автоматически начинать работу по расписанию — достаточно настроить выражение cron и часовой пояс, и Предиктор Икс самостоятельно создаст задачу, не требуя вашего участия. Это подходит для периодических проверок, регулярных отчетов и ночных задач по очистке — своего рода "постоянные поручения". В отличие от трех других способов запуска (назначение задач, @-упоминание и чат, где инициатором выступаете вы), основное отличие автопилотов в том, что они зависят от времени.

Настройка автопилота

Создайте новый автопилот на странице Autopilot в вашем рабочем пространстве. Укажите следующие параметры:

• Name (Имя) — отображаемое название
• Agent (Агент) — кому будет назначено выполнение
• Priority (Приоритет) — наследуется созданной задачей (семантика аналогична приоритету задачи/issue)
• Description / prompt (Описание / промпт) — описание работы, которую агент получает при каждом запуске
• Execution mode (Режим выполнения) — см. ниже
• Triggers (Триггеры) — хотя бы одно расписание (cron + часовой пояс) или вебхук

Выбор режима выполнения

У автопилота есть два режима выполнения. Начните с режима "create issue".

• Режим создания задачи (create_issue) — по умолчанию, рекомендуется. Каждый запуск сначала создает задачу (issue) в рабочем пространстве (заголовок поддерживает плейсхолдер {{date}}, который заменяется на дату в формате YYYY-MM-DD по UTC; любые другие токены {{...}} отклоняются при создании, чтобы случайная опечатка не попала в заголовок задачи), а затем назначает эту задачу агенту через стандартный процесс назначения. Вся работа отображается на доске задач со всей историей, комментариями и статусами, как и обычная задача.
• Режим только запуска (run_only) — пропускает создание задачи и напрямую ставит задачу в очередь. Этот запуск не виден на доске — его можно найти только в истории запусков автопилота.

Запуск по расписанию

Каждому автопилоту нужен как минимум один триггер расписания. Cron использует стандартный формат из 5 полей (минута, час, день, месяц, день недели) с минимальной гранулярностью в 1 минуту (секунды не поддерживаются). Часовой пояс указывается в формате IANA (например, Asia/Shanghai) и определяет, в каком поясе будет интерпретироваться cron-выражение.

Примеры:

• 0 9 * * 1-5, Asia/Shanghai — 9 утра по пекинскому времени в будние дни
• */30 * * * *, UTC — каждые 30 минут
• 0 3 * * *, UTC — каждый день в 3 часа ночи по UTC

Сервер Предиктор Икс проверяет наличие триггеров каждые 30 секунд — фактическое время запуска может опаздывать до 30 секунд. Если сервер перезагружается во время срабатывания триггера, он наверстает пропущенные события при запуске (ничего не теряется, они выполняются сразу после старта).

Ручной запуск

Чтобы не ждать срабатывания по cron во время отладки, запустите автопилот вручную:

• UI: нажмите "Run now" на странице сведений об автопилоте
• CLI:

predictorx autopilot trigger <autopilot-id>

Ручной запуск проходит через тот же процесс выполнения, что и по расписанию — единственное отличие в поле source в записи запуска, которое помечается как manual.

Запуск через вебхук

Автопилоты также могут запускаться через входящие HTTP-вебхуки. Добавьте триггер Webhook на странице автопилота; Предиктор Икс создаст уникальный URL вида:

https://<your-predictorx-host>/api/webhooks/autopilots/awt_…

Отправьте POST-запрос с JSON по этому URL — Предиктор Икс запишет событие с source = webhook, сохранит тело запроса как trigger_payload запуска и назначит выполнение агенту точно так же, как при запуске по расписанию.

curl -X POST "$Предиктор Икс_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d '{"event":"demo.received","eventPayload":{"message":"hello"}}'

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

Структура полезной нагрузки (Payload)

Вы можете отправлять свою структуру:

{ "event": "github.pull_request.opened", "eventPayload": { } }

…или любой JSON-объект/массив. Предиктор Икс нормализует их во внутренний конверт:

{
  "event": "<inferred>",
  "eventPayload": <ваше тело запроса>,
  "request": { "receivedAt": "<rfc3339>", "contentType": "application/json" }
}

Если вы не указываете поле event, Предиктор Икс выводит его из стандартных заголовков и полей тела (X-GitHub-Event + поле action, X-Gitlab-Event, X-Event-Type, поля event/type/action). Если соответствий не найдено, событию присваивается имя webhook.received.

При настройке GitHub или подобных сервисов устанавливайте заголовок Content-Type в application/json — form-encoded данные не принимаются.

Фильтры событий

Триггер вебхука срабатывает на каждый входящий POST-запрос, что удобно для простых случаев, но избыточно, если источник отправляет много разных событий (например, GitHub — один вебхук репозитория может доставлять push, pull_request, workflow_run, check_suite и другие). Секция Event filters в настройках вебхука позволяет ограничить события, которые должны запускать автопилот; все остальные записываются в историю доставки со статусом ignored и причиной event_filtered, при этом запуск или задача не создаются.

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

Примеры:

Откуда берется имя события и действие

Предиктор Икс определяет имя event и action из входящего запроса в следующем порядке — побеждает первое совпадение.

1. Конверт в теле запроса. Если тело является JSON-объектом со строковым полем event, это значение считается именем события. Опциональный объект eventPayload предоставляет кандидатов на действие из своих полей action / state / conclusion / status.

curl -X POST "$Предиктор Икс_WEBHOOK_URL" \
  -H 'Content-Type: application/json' \
  -d '{"event":"trigger","eventPayload":{"action":"true"}}'
# определено: event = trigger, кандидат действия = true

2. Заголовки. Если конверта в теле нет, Предиктор Икс считывает известные заголовки:

• X-GitHub-Event: <event> — объединяется с полем тела action (если есть), образуя github.<event>.<action>.
• X-Gitlab-Event: <event> — становится gitlab.<event>.
• X-Event-Type: <event> — передается как есть.

# GitHub-стиль: заголовок дает имя события, тело — действие.
curl -X POST "$Предиктор Икс_WEBHOOK_URL" \
  -H 'X-GitHub-Event: workflow_run' \
  -H 'Content-Type: application/json' \
  -d '{"action":"completed"}'
# определено: event = github.workflow_run.completed
#        → совпадает с фильтром workflow_run / completed

3. Резерв по полям тела. Если ни конверта, ни известных заголовков нет, Предиктор Икс ищет поля в верхнем уровне тела в порядке: event → type → action.

4. Значение по умолчанию. Если ничего не подошло, событие считается webhook.received.

Кандидаты действий в деталях. После определения события Предиктор Икс рассматривает как кандидата на действие:

• Суффикс события, если оно имеет форму provider.event.<action> (напр., github.workflow_run.completed → completed).
• Поля action, state, conclusion и status — только если они являются JSON-строками. Логические значения (true) или числа не подходят.

Важное примечание. Фильтр Event name: trigger, Actions: true не означает "сработать, когда в теле есть trigger: true". Фильтры событий проверяют уже выведенное имя события и действие, а не произвольные поля.

URL — это секретный ключ

Сгенерированный URL является учетными данными. Любой, у кого он есть, может запустить автопилот. Относитесь к нему как к токену:

• Не вставляйте его в публичные обсуждения, скриншоты или чаты.
• Смените его, если он был скомпрометирован — нажмите "Rotate URL" в настройках триггера. Старый URL перестанет работать немедленно.

Семантика кодов ответов

Предиктор Икс возвращает 200 OK со статусом, чтобы механизмы повторных попыток вашего провайдера не заваливали сервер:

• {"status":"accepted",...} — запуск прошел успешно.
• {"status":"skipped",...} — исполнитель оффлайн.
• {"status":"ignored",...} — триггер/автопилот выключен или на паузе.

Self-hosted: настройка публичного URL

При установке PREDICTORX_PUBLIC_URL на сервере ответ триггера будет содержать абсолютный webhook_url. Без этого UI составляет URL на основе API-источника клиента — это подходит для десктопа, но может не сработать для кастомных reverse-прокси.

Просмотр истории запусков

Каждый запуск создает запись в истории, доступную на вкладке "History" в деталях автопилота:

• Источник (schedule / manual / webhook)
• Время начала и завершения
• Статус (issue_created / running / completed / failed / skipped)
• Связанная задача (issue или task)
• Причина ошибки (если есть)

Что происходит при сбое автопилота

Почему нет авто-ретрансляций: так как автопилоты периодичны, системные ретраи привели бы к наслоению задач друг на друга.

Что пока недоступно

Триггеры вида API еще не реализованы. Схема триггеров резервирует вид api, но входящий маршрут для него пока не работает.

Далее

• Назначение задач агентам
• @-упоминание агентов в комментариях
• Чат