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

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

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

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

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

• Развёртывания требуют конфигурации агента и конфигурации окружения, а также опционально принимают файлы, GitHub, хранилища памяти и хранилища секретов (vaults). Развёртывание, нацеленное на самостоятельно размещённое окружение, может подключать хранилища памяти; ресурсы file и github_repository требуют облачного окружения. Форма развёртывания в Claude Console в настоящее время не предлагает хранилища памяти для самостоятельно размещённых окружений; вместо этого подключайте их через API или SDK.
• Развёртывания также требуют как минимум одного начального события, 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 и часовых поясов

• Выражение: стандартный 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": null и установить снова позже.

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

curl --fail-with-body -sS "https://api.anthropic.com/v1/deployments/$DEPLOYMENT_ID?beta=true" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<'EOF'
{
  "budget": {
    "type": "limit",
    "max_list_cost": {"amount": "2000", "currency": "USD"}
  }
}
EOF

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

Развёртывания могут не сработать по разным причинам: например, если ресурс 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"