예약 배포

**"scheduled deployment"(예약 배포)**를 사용하면 에이전트가 세션을 자율적으로 시작할 수 있어, 예측 가능한 주기로 작업을 완료할 수 있습니다. 배포는 Claude API의 일부인 Deployments API로 생성하고 관리합니다.

출시 배경과 팀들이 일정에 따라 실행하는 작업의 예시는 블로그의 Claude Managed Agents의 예약 배포 및 vault를 참조하세요.

예약 배포 생성

배포를 생성할 때는 schedule과 함께 실행에 필요한 세션 구성을 전달합니다.

• 배포에는 에이전트 구성과 환경 구성이 필요하며, 선택적으로 파일, GitHub, 메모리 저장소, vault를 받을 수 있습니다. 자체 호스팅 환경을 대상으로 하는 배포는 메모리 저장소를 연결할 수 있으며, 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%에 해당하는 지터(jitter)가 적용되며, 최소 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 일정은 문자 그대로의 벽시계 시각 매칭을 사용하므로, America/New_York의 "0 20 * * *"은 EST 또는 EDT 적용 여부와 관계없이 현지 시각 오후 8:00에 실행됩니다.

각 실행에 예산 설정

배포를 생성하거나 업데이트할 때 선택적 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

실패한 실행에는 세션 생성이 거부된 이유를 설명하는 type이 있는 error가 포함됩니다(예: 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"로 실패한 실행을 기록하고 배포는 자동으로 일시 중지되어 에이전트를 업데이트한 후 재개할 수 있습니다. 보관 처리된 환경이나 vault와 같은 기타 복구 불가능한 세션 생성 오류도 동일하게 동작합니다. 트리거는 실패한 실행을 기록하고 배포는 자동으로 일시 중지됩니다. 배포의 paused_reason.error.type은 실패한 실행의 error.type을 그대로 반영합니다.

수동 실행 트리거

일정 외에 배포를 실행하려면 run 엔드포인트를 호출하세요. 이는 즉시 세션을 생성하고 trigger_context.type: "manual"로 배포 실행을 기록합니다. 이를 통해 일정을 확정하기 전에 배포를 테스트할 수 있습니다.

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