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

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

Для контекста запуска и примеров того, что команды выполняют по расписанию, см. запланированные развертывания и хранилища в Claude Managed Agents в блоге.



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

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

• Развертывания требуют конфигурацию агента и конфигурацию окружения, а также опционально принимают файлы, GitHub, хранилища памяти и хранилища секретов.
• Развертывания также требуют как минимум одно начальное событие, user.message или user.define_outcome, которое запускает работу каждой сессии.
• В 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"
    ]
  }
}

Временные метки предстоящих запусков отражают точное настроенное расписание. Однако для распределения нагрузки фактическое выполнение применяет джиттер до 15% от интервала между запусками, с минимумом в 5 секунд и максимумом в 9 минут.

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

См. справочник Create Deployment для полного списка параметров и схемы ответа.



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

• Expression: Стандартный POSIX cron (minute hour day-of-month month day-of-week). Вы можете генерировать и проверять эти cron-выражения в Claude Console.
• Timezone: Идентификатор часового пояса 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"
}

Чтобы получить отдельный запуск по ID, вызовите GET /v1/deployment_runs/{deployment_run_id}. Событие вебхука deployment_run содержит ID запуска в поле 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 (архивирование), в отличие от pause, является окончательным: расписание завершается, и развертывание не может быть изменено.

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"