예약된 배포

예약된 배포(scheduled deployment)를 사용하면 에이전트가 자율적으로 세션을 시작할 수 있어, 예측 가능한 주기로 작업을 완료할 수 있습니다. 배포는 Claude API의 일부인 Deployments 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"
    ]
  }
}

예정된 실행 타임스탬프는 구성된 정확한 일정을 기준으로 합니다. 다만 부하를 분산하기 위해 배포는 최대 10초의 지터(jitter)를 적용할 수 있습니다.

조직당 최대 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 일정은 문자 그대로의 벽시계 시간 매칭을 사용하므로, America/New_York에서 "0 20 * * *"은 EST 또는 EDT 적용 여부와 관계없이 현지 시간 오후 8시에 실행됩니다.



배포 실행

배포는 다양한 이유로 트리거에 실패할 수 있습니다. 예를 들어 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)은 일시 중지와 달리 최종 상태입니다. 일정이 종료되고 배포를 수정할 수 없습니다.

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"