예약된 배포

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)가 최소 하나 이상 필요합니다. 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"
    ]
  }
}

예정된 실행 타임스탬프는 구성된 일정을 정확히 반영합니다. 그러나 부하를 분산하기 위해 실제 실행에는 실행 간격의 최대 15%에 해당하는 "jitter"(지터)가 적용되며, 최소 5초에서 최대 9분입니다.

조직당 최대 1,000개의 예약된 배포가 지원됩니다. 더 필요한 경우 Anthropic 지원팀에 문의하세요.

전체 매개변수와 응답 스키마는 Create Deployment 레퍼런스를 참조하세요.

Cron 및 시간대 의미 체계

• Expression: 표준 POSIX cron(minute hour day-of-month month day-of-week)입니다. Claude Console에서 이러한 cron 표현식을 생성하고 검증할 수 있습니다.
• Timezone: IANA 시간대 식별자입니다(예: "America/Los_Angeles").
• DST: Cron 일정은 문자 그대로의 벽시계 시간 일치를 사용하므로, America/New_York의 "0 20 * * *"는 EST 또는 EDT 적용 여부와 관계없이 현지 시간 오후 8시에 실행됩니다.

각 실행에 예산 설정하기

배포를 생성하거나 업데이트할 때 선택적 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 리소스가 보관되었거나 세션 생성이 속도 제한에 걸린 경우입니다. 배포를 실행하려는 각 시도는 deployment run(배포 실행) 레코드를 생성하므로, 세션 수명 주기와 독립적으로 성공과 실패를 추적할 수 있습니다.

성공한 배포는 활성 세션을 생성하며, 성공한 배포 실행에는 연결된 session_id가 포함됩니다. 세션의 수명 주기를 따라가려면 이벤트 스트림 또는 webhook을 통해 세션 이벤트를 추적하세요. 배포 수명 주기 변경과 각 예약된 실행의 결과도 webhook 이벤트로 전달되며, 이는 지원되는 이벤트 유형의 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)

실패한 실행에는 세션 생성이 거부된 이유를 설명하는 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 webhook 이벤트는 실행 ID를 data.id로 전달합니다.

배포 수명 주기 관리하기

각 수명 주기 변경은 webhook 이벤트를 발생시키므로, 폴링 없이 일시 중지, 일시 중지 해제 또는 보관된 배포에 대응할 수 있습니다. 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"와 함께 실패한 실행을 기록하고 배포는 자동으로 일시 중지되므로, 에이전트를 업데이트한 후 재개할 수 있습니다. 보관된 환경이나 vault와 같은 기타 복구 불가능한 세션 생성 오류도 동일하게 동작합니다. 트리거가 실패한 실행을 기록하고 배포가 자동으로 일시 중지됩니다. 배포의 paused_reason.error.type은 실패한 실행의 error.type을 그대로 반영합니다.

수동 실행 트리거하기

일정과 관계없이 배포를 실행하려면 run 엔드포인트를 호출하세요. 이렇게 하면 즉시 세션이 생성되고 trigger_context.type: "manual"이 포함된 배포 실행이 기록됩니다. 이를 통해 일정을 확정하기 전에 배포를 테스트할 수 있습니다.

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