예약된 배포

예약된 배포(scheduled deployment)는 에이전트가 자율적으로 세션을 시작할 수 있게 하여, 예측 가능한 주기로 작업을 완료할 수 있도록 합니다.

예약된 배포 생성

배포를 생성할 때, 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 지원팀에 문의하세요.

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시에 실행됩니다.

배포 실행

배포는 다양한 이유로 트리거에 실패할 수 있습니다. 예를 들어, environment 리소스가 아카이브되었거나 세션 생성이 속도 제한에 걸린 경우입니다. 배포 실행의 각 시도는 배포 실행(deployment run) 레코드를 생성하여, 세션 수명 주기와 독립적으로 성공과 실패를 추적할 수 있게 합니다.

성공한 배포는 활성 세션을 생성하며, 성공한 배포 실행에는 연결된 session_id가 포함됩니다. 세션의 수명 주기를 따라가려면 이벤트 스트림 또는 웹훅을 통해 세션 이벤트를 추적하세요.

다음과 같이 배포의 모든 배포 실행을 나열합니다:

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).

{
  "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"
}

배포 수명 주기 관리

일시 중지(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"와 함께 실패한 실행을 기록하고 배포가 자동으로 일시 중지되어 에이전트를 업데이트하고 재개할 수 있습니다.

수동 실행 트리거

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

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