Запланированные развёртывания

Запланированное развёртывание (scheduled deployment) позволяет агенту автономно запускать сессии, обеспечивая выполнение задач с предсказуемой периодичностью. Вы создаёте развёртывания и управляете ими с помощью Deployments API, который является частью Claude API.



Создание запланированного развёртывания

При создании развёртывания вы передаёте конфигурации сессии, необходимые для выполнения, а также schedule.

• Развёртывания требуют конфигурации агента и конфигурации окружения, а также опционально принимают файлы, GitHub, хранилища памяти и хранилища секретов.
• Развёртывания также требуют начального события user.message, которое запускает работу сессии.
• В schedule вы определяете cron-выражение expression и часовой пояс timezone. Максимальная поддерживаемая гранулярность — на уровне минут.

DEPLOYMENT_ID=$(ant beta:deployments create <<YAML | jq -er '.id'
name: Weekly compliance scan
agent: $AGENT_ID
environment_id: $ENVIRONMENT_ID
initial_events:
  - type: user.message
    content:
      - type: text
        text: Run the weekly compliance scan.
schedule:
  type: cron
  expression: "0 20 * * 5"
  timezone: America/New_York
YAML
)

Ответ включает объект развёртывания с заполненным полем schedule.upcoming_runs_at, содержащим ближайшие моменты срабатывания, чтобы вы могли убедиться, что расписание задано правильно.

{
  "id": "depl_01xyz",
  "status": "active",
  "paused_reason": null,
  "schedule": {
    "type": "cron",
    "expression": "0 20 * * 5",
    "timezone": "America/New_York",
    "last_run_at": null,
    "upcoming_runs_at": [
      "2026-05-09T00:00:00Z",
      "2026-05-16T00:00:00Z",
      "2026-05-23T00:00:00Z"
    ]
  }
}

Временные метки предстоящих запусков основаны на точном заданном расписании. Однако для распределения нагрузки развёртывания могут применять случайное смещение (jitter) до 10 секунд.

Поддерживается максимум 1 000 запланированных развёртываний на организацию. Свяжитесь со службой поддержки Anthropic, если вам требуется больше.

Полный список параметров и схему ответа см. в справочнике по Create Deployment.



Семантика cron и часовых поясов

• Выражение: стандартный POSIX cron (минута час день-месяца месяц день-недели). Вы можете генерировать и проверять эти cron-выражения в Claude Console.
• Часовой пояс: идентификатор часового пояса IANA (например, "America/Los_Angeles").
• Переход на летнее время (DST): cron-расписания используют буквальное сопоставление с местным временем, поэтому "0 20 * * *" в America/New_York срабатывает в 20
  по местному времени независимо от того, действует ли EST или EDT.



Запуски развёртывания

Развёртывания могут не сработать по ряду причин: например, если ресурс environment был архивирован или если создание сессии ограничено по скорости. Каждая попытка выполнения развёртывания создаёт запись запуска развёртывания (deployment run), что позволяет отслеживать успехи и сбои независимо от жизненного цикла сессии.

Успешные развёртывания создают активные сессии, и успешный запуск развёртывания содержит связанный session_id. Чтобы отслеживать жизненный цикл сессии, следите за событиями сессии через поток событий или вебхуки. Изменения жизненного цикла развёртывания и результат каждого запланированного запуска также доставляются как события вебхуков, перечисленные на вкладках «Deployment events» и «Deployment run events» в разделе Поддерживаемые типы событий.

Получить список всех запусков развёртывания для конкретного развёртывания можно следующим образом:

ant beta:deployment-runs list --deployment-id "$DEPLOYMENT_ID"

Вы также можете отфильтровать запуски развёртывания с ошибками:

ant beta:deployment-runs list --deployment-id "$DEPLOYMENT_ID" --has-error

Неудачный запуск включает поле error с полем type, описывающим причину отклонения создания сессии (например, environment_archived_error, agent_archived_error или session_rate_limited_error). Все параметры фильтрации и схему ответа см. в справочнике по List Deployment Runs.

{
  "type": "deployment_run",
  "id": "drun_01abc124",
  "deployment_id": "depl_01xyz",
  "trigger_context": { "type": "schedule", "scheduled_at": "2026-05-09T00:00:00Z" },
  "session_id": null,
  "error": {
    "type": "environment_archived_error",
    "message": "environment `env_01abc` is archived"
  },
  "agent": { "type": "agent", "id": "agent_01ghi789", "version": 3 },
  "created_at": "2026-05-09T00:00:01Z"
}

Чтобы получить отдельный запуск по идентификатору, вызовите GET /v1/deployment_runs/{deployment_run_id}. Событие вебхука deployment_run содержит идентификатор запуска в поле data.id.



Управление жизненным циклом развёртывания

Каждое изменение жизненного цикла генерирует событие вебхука, поэтому вы можете реагировать на приостановку, возобновление или архивирование развёртывания без опроса; см. вкладку «Deployment events».

Приостановка (pause) подавляет запланированные срабатывания начиная с текущего момента; сессии, запущенные предыдущим запуском развёртывания, продолжают выполняться. Ручные запуски через эндпоинт run по-прежнему разрешены во время приостановки. Приостановка устанавливает paused_reason в значение {"type": "manual"}; возобновление очищает его.

ant beta:deployments pause --deployment-id "$DEPLOYMENT_ID"

Возобновление (unpause) возобновляет расписание со следующего запланированного срабатывания. Пропущенные срабатывания не восполняются задним числом.

ant beta:deployments unpause --deployment-id "$DEPLOYMENT_ID"

Архивирование (archive), в отличие от приостановки, является окончательным: расписание прекращается, и развёртывание больше нельзя изменить.

ant beta:deployments archive --deployment-id "$DEPLOYMENT_ID"



Поведение при сбоях

Ответы об ограничении скорости при создании сессии немедленно записываются как запуск с ошибкой session_rate_limited_error без повторных попыток; расписание повторит попытку при следующем запланированном срабатывании. Ограничения скорости на базовые вызовы API внутри сессии обрабатываются самой сессией.

Если агент развёртывания был архивирован или удалён, развёртывание автоматически архивируется в рамках той же операции; запуск развёртывания не записывается. Если субагент, на который ссылается агент, был архивирован, следующее срабатывание записывает неудачный запуск с error.type: "agent_archived_error", и развёртывание автоматически приостанавливается, чтобы вы могли обновить агента и возобновить работу. Другие невосстановимые ошибки создания сессии, такие как архивированное окружение или хранилище секретов, ведут себя аналогично: срабатывание записывает неудачный запуск, и развёртывание автоматически приостанавливается. Поле paused_reason.error.type развёртывания отражает error.type неудачного запуска.



Запуск вручную

Чтобы запустить развёртывание вне его расписания, вызовите эндпоинт run. Это немедленно создаёт сессию и записывает запуск развёртывания с trigger_context.type: "manual". Это позволяет протестировать развёртывание, прежде чем полагаться на расписание.

ant beta:deployments run --deployment-id "$DEPLOYMENT_ID"