안녕하세요, 토무입니다.

이번에는 2026년 6월 10일 Code with Claude Tokyo 이벤트에서 public beta로 발표된, Managed Agents의 "scheduled deployment" 기능을 사용해 보았습니다!

저도 Managed Agents를 사용하는 것은 처음이기 때문에, 그 부분도 차근차근 설명하며 본론으로 들어가겠습니다!

0. Claude Managed Agents란

Claude Managed Agents는 Claude를 **자율 에이전트 (Autonomous Agent)**로 실행하기 위한 하네스(Harness)와 인프라스트럭처를 제공하는 메커니즘입니다.

Claude Managed Agents는 4가지 개념을 중심으로 구축되어 있습니다.

개념	설명
에이전트 (Agent)	모델, 시스템 프롬프트 (System Prompt), 도구 (Tool), MCP 서버, 및 스킬
...

Claude Code와는 무엇이 다른가?

이 부분은 필자가 입문했을 때 자주 헷갈렸던 부분이라 일단 정리해 두겠습니다!

Claude Managed Agents가 클라우드 상에서 자율적으로 태스크를 완료하는 풀 매니지드형 (Full-managed) 서비스인 것에 반해, Claude Code는 실시간으로 대화하며 작업하는 도구입니다.

적용 시나리오의 차이는 다음과 같습니다.

용도	Claude Code	Claude Managed Agents
단발 작업 · 대화형 개발	〇	△
...

1. 도입: scheduled deployment란

• 에이전트에 cron 스케줄을 연결하여, 실행될 때마다 새로운 세션을 시작하여 태스크를 완료하는 메커니즘. - 포인트는 "자체적으로 스케줄러를 구축·호스트할 필요가 없다"는 것. - 용도 예시: 야간 데이터 동기화 / 주간 컴플라이언스 스캔 / 일간 다이제스트.
• 채택 사례로 신뢰성 보강 (Actively AI는 자체 제작한 스케줄링 인프라를 대체하여 스택을 간소화).

2. 전제

• Console 계정 및 API 키.
• ant CLI (Managed Agents CLI). - 모든 요청에 managed-agents-2026-04-01 beta 헤더가 필요 (CLI / SDK는 자동 부여).

3. 만들기 (agent → environment → deployment)

• deployment는 기존의 agent와 environment를 ID로 참조하는 구조. - 따라서 순서는 "agent 생성 → environment 생성 → deployment.yaml에 두 ID를 작성 → create"입니다.
• create의 응답으로 status: active와 upcoming_runs_at (다음 실행 예정 시간)이 반환됩니다.

4. 검증

• run (수동 실행)을 통해 스케줄을 기다리지 않고 즉시 세션을 생성 → 운영 투입 전 테스트로 사용할 수 있습니다. - deployment-runs list로 각 실행의 성패를 추적. --has-error로 에러만 추출. - deployment run은 세션의 라이프사이클 (Lifecycle)과는 독립된 기록이라는 설계를 강조하면 기술 기사로서 마무리하기 좋습니다.

5. cron / timezone / DST 동작

• 최대 단위는 분 단위입니다. - cron은 리터럴한 wall-clock 매칭입니다. America/New_York의 0 20 * * *은 EST/EDT와 관계없이 현지 시간 20시에 실행됩니다. - 엣지 케이스: 봄의 존재하지 않는 시간(새벽 2시 등)은 실행되지 않으며, 가을의 중복된 시간은 2번 실행됩니다.
• 누락이나 중복이 허용되지 않는다면, 현지 시간 새벽 1~3시를 피하거나 UTC를 사용하십시오.
• upcoming_runs_at은 UTC로 표시되지만, 실행 판정 자체는 wall-clock 기반이라는 정리가 정확합니다. - 부하 분산을 위해 최대 10초의 jitter가 적용될 수 있습니다 (정확히 일치하는 시간에 실행되지 않을 수 있음).

(그렇다고는 해도, 아마 다른 요인으로 인해 몇 분 뒤에 실행되는 일은 흔히 있는 일이라고 생각합니다.)

6. 라이프사이클 관리

• pause (가역적): 이후의 트리거를 억제합니다. 단, 이미 실행 중인 이전 run 세션은 계속 유지됩니다. pause 중에도 수동 run은 가능합니다.
• unpause: 다음 예정된 회차부터 재개합니다. 누락된 회차에 대한 백필(backfill)은 이루어지지 않습니다.
• archive (비가역적 / terminal): 스케줄을 종료하며, 이후 변경이 불가능합니다. - 자동 동작: agent가 아카이브/삭제되면 deployment도 자동으로 아카이브됩니다. 서브 에이전트가 아카이브되면 다음 트리거 시 실패한 run을 기록하고 자동 pause (업데이트 후 재개할 수 있도록) 합니다.

7. 주의 사항

• 과금: 이것은 Claude Platform (API) 측의 기능으로, Pro/Max와 같은 월정액 구독과는 별개의 체계입니다. scheduled deployment 자체에 추가 요금이 붙지는 않지만, 트리거될 때마다 세션이 실행되므로 해당 토큰 소비와 샌드박스(sandbox) 실행이 API 종량제로 과금됩니다. 예: 매일 아침 1회 × 30일 = 세션 30회분 사용량. 정확한 단가는 claude.com/pricing#api 또는 Console의 사용량 화면에서 확인이 필요합니다.
• ZDR / HIPAA 미지원: Managed Agents는 대화 이력, 샌드박스 상태, 출력을 서버 측에 유지하는 상태 유지(stateful) 설계이므로, Zero Data Retention (ZDR) 및 HIPAA BAA 대상에서 제외됩니다.
• public beta: 사양은 변경될 수 있습니다.
• 상한: 조직당 최대 1,000개의 scheduled deployment.

작업 가이드 (복사하여 실행용)

전제 조건:
ant CLI가 설치되어 있고, ANTHROPIC_API_KEY가 설정되어 있어야 합니다. CLI는 beta 헤더를 자동으로 부여합니다.

Step 0. API 키를 환경 변수에 설정

export ANTHROPIC_API_KEY="your-api-key-here"

Step 1. 에이전트를 생성하고 agent.id를 기록

ant beta:agents create \
--name "News Digest Agent" \
--model '{id: claude-opus-4-8}' \
...

• agent_toolset_20260401을 통해 bash, 파일 조작, web search 등의 프리빌트(prebuilt) 도구 세트가 활성화됩니다.

응답 예시:

• 반환된 agent.id를 기록합니다 (이후 $AGENT_ID로 사용).

export AGENT_ID="agent_xxxxxxxxxxxx"

Step 2. 환경을 생성하고 environment.id를 기록

ant beta:environments create \
--name "cron-env" \
--config '{type: cloud, networking: {type: unrestricted}}'

응답 예시:

• 반환된 environment.id를 기록합니다.

export ENVIRONMENT_ID="env_xxxxxxxxxxxx"

Step 3. deployment.yaml 작성

이번에는 WSL 상에서 직접 VS Code를 호출하여, 거기서 다음 yaml 파일을 작성합니다.

code ~/deployment.yaml

# deployment.yaml
name: Weekday morning digest
agent: $AGENT_ID
...

• expression은 표준 POSIX cron (분 시 일 월 요일)입니다.
• timezone은 IANA 타임존 식별자입니다.

Step 4. scheduled deployment 생성

파일로부터 주입하는 방식 (공식 이미지 형태):

ant beta:deployments create < deployment.yaml

heredoc + ID 획득까지 한 번에 수행하는 방식 (공식 문서 형태):

DEPLOYMENT_ID=$(ant beta:deployments create <<YAML | jq -er '.id'
name: Weekday morning digest
agent: $AGENT_ID
...

응답 예시:

upcoming_runs_at

은 UTC 기준 표시입니다 (JST 9:00 = 00:00Z). 이를 통해 설정이 올바른지 확인할 수 있습니다. -
반환된

id

를 기록해 둡니다.

export DEPLOYMENT_ID="depl_xxxxxxxxxxxx"

Step 5. 수동 실행으로 테스트 (스케줄을 기다리지 않음)

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

• 즉시 세션을 생성하고,
  trigger_context.type: "manual"

인 deployment run을 생성합니다. -
실제 스케줄에 올리기 전 동작 확인용으로 사용합니다.

응답 예시:

출력 확인

Claude Platform 콘솔에서 확인할 수 있습니다!

Step 6. 실행 이력 확인

# 모든 run 목록
ant beta:deployment-runs list --deployment-id "$DEPLOYMENT_ID"
# 에러만 확인
...

응답 예시:

• 실패한 run에는
  error.type

(예: environment_archived_error / agent_archived_error / session_rate_limited_error)

이 포함됩니다.

Step 7. 라이프사이클 (Lifecycle) 조작

# 일시 정지 (가역적): 이후의 트리거를 억제합니다. 실행 중인 세션은 계속 유지됩니다. pause 중에도 수동 run은 가능합니다.
ant beta:deployments pause --deployment-id "$DEPLOYMENT_ID"
# 재개: 다음 예정된 회차부터 적용됩니다. 누락된 회차에 대한 백필 (Backfill)은 없습니다.
...

Step 8. 실시 결과

실시 시간도 지정한 오전 9:00 근처에 실행되고 있는 것을 확인할 수 있습니다!

Step 9. 정리

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

응답 예시:

여담

Claude에는 정기 실행 수단이 단계별로 마련되어 있습니다!

Claude Code 내에서 동작하는 /loop (세션을 열어두는 동안만), PC를 닫아도 Anthropic의 클라우드에서 동작하는 /schedule (Cloud Routine), 그리고 본 기사에서 다루는 Managed Agents의 scheduled deployment까지 총 3단계로 구성되어 있습니다.

개인 작업 보조부터 실제 운영까지 용도에 따라 선택할 수 있다는 것이 특징입니다!

각 수단의 세부적인 차이점은 【Claude loop 완전 가이드】 세무사·경리·인사 등 비엔지니어가 "정기 확인"을 노코드(No-code)로 자동화하는 방법의 마지막 부분에 정리되어 있으니, 그쪽을 확인해 주세요!

참조 (1차 소스)

Discussion