Развёртывания по расписанию

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

Контекст запуска этой функции и примеры того, что команды выполняют по расписанию, см. в статье scheduled deployments and vaults in Claude Managed Agents в блоге.

Создание развёртывания по расписанию

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

• Развёртывания требуют конфигурации агента и конфигурации окружения, а также могут дополнительно принимать файлы, GitHub, хранилища памяти и хранилища секретов (vaults). Развёртывание, нацеленное на самостоятельно размещённое окружение, может подключать хранилища памяти; ресурсы file и github_repository требуют облачного окружения. Форма развёртывания в Claude Console в настоящее время не предлагает хранилища памяти для самостоятельно размещённых окружений; вместо этого подключайте их через API или SDK.
• Развёртывания также требуют как минимум одного начального события — user.message или user.define_outcome, — которое запускает работу каждой сессии. В файле развёртывания для ant apply текст под frontmatter становится этим user.message.
• В schedule вы задаёте cron-выражение expression и часовой пояс timezone. Максимальная поддерживаемая детализация — до минуты.

ant apply deployment.md

---
name: Weekly compliance scan
agent: agent_011CYm1BLqPXpQRk5khsSXrs
environment_id: env_01595EKxaaTTGwwY3kyXdtbs
schedule:
  type: cron
  expression: "0 20 * * 5"
  timezone: America/New_York
---

Run the weekly compliance scan.

Ответ содержит объект развёртывания с заполненным полем 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" (случайное смещение) величиной до 15% от интервала между запусками, но не менее 5 секунд и не более 9 минут.

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

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

Семантика cron и часового пояса

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

Установка бюджета на каждый запуск

Передайте необязательный объект budget при создании или обновлении развёртывания. Он имеет ту же структуру, что и бюджет сессии. Развёртывание копирует лимит в каждую запускаемую им сессию, поэтому бюджет ограничивает каждый запуск по отдельности, а не действует как совокупный потолок для всех запусков: развёртывание с лимитом "2000" может тратить примерно до $20 на каждый запуск.

Сессия, запущенная развёртыванием, ведёт себя точно так же, как любая другая сессия с бюджетом: она приостанавливается с budget_reached, когда её собственная стоимость по прейскуранту достигает лимита. Изменение бюджета развёртывания применяется к запускам, начатым после изменения; уже выполняющаяся сессия сохраняет лимит, с которым она была запущена, и его можно изменить через саму сессию. В отличие от бюджета сессии, бюджет развёртывания можно удалить с помощью budget=None и позже установить снова.

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

ant apply deployment.md

---
name: Weekly compliance scan
agent: agent_011CYm1BLqPXpQRk5khsSXrs
environment_id: env_01595EKxaaTTGwwY3kyXdtbs
schedule:
  type: cron
  expression: "0 20 * * 5"
  timezone: America/New_York
budget:
  type: limit
  max_list_cost:
    amount: "2000"
    currency: USD
---

Run the weekly compliance scan.

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

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

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

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

for run in client.beta.deployment_runs.list(
    deployment_id=deployment.id,
):
    print(run.created_at, run.session_id or run.error.type)

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

for run in client.beta.deployment_runs.list(
    deployment_id=deployment.id,
    has_error=True,
):
    print(run.created_at, run.error.type, run.error.message)

Неудачный запуск содержит 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"}; возобновление очищает это поле.

client.beta.deployments.pause(deployment.id)

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

client.beta.deployments.unpause(deployment.id)

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

client.beta.deployments.archive(deployment.id)

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

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

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

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

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

run = client.beta.deployments.run(deployment.id)