Claude Code Managed Agents 입문 — 스케줄 실행과 CLI 통합 구현 가이드

2026년 6월, Anthropic이 Claude Code Managed Agents를 퍼블릭 베타(Public Beta)로 출시했습니다.

스케줄 실행(cron)・CLI tools 안전 통합・Vault 관리 환경 변수가 내장된 에이전트 자동화 기반이 등장했습니다. 본 가이드에서는 API 구현부터 실무 운영까지 완전 망라합니다.

기존의 Claude API (call-and-response) 방식에서는 매번 사용자가 트리거하여 에이전트를 기동해야 했습니다. Managed Agents는 다음을 포함합니다:

기능	설명
Schedule-based Execution	cron 표기법으로 스케줄 정의. 24시간 무인 자동 실행
Secure CLI Tool Integration	Shell commands를 에이전트로부터 안전하게 실행 (화이트리스트 제어)
Vault-stored Environment Variables	Secrets.json으로 API 키・DB 비밀번호 등을 암호화 관리
Managed Lifecycle	에이전트 실행의 state 관리・failure recovery 자동화

적합한 용도:

• 일간・주간 자동 리포트 생성
• 정기적인 데이터 수집・ETL
• 스케줄 정기 실행 모니터링 태스크
• CI/CD 파이프라인의 AI 구동 오케스트레이션 (Orchestration)

Claude Code에서는 .claude/agents/my-agent.md 형식으로 정의합니다:

---
name: daily-report-generator
description: |
...

claude-code-cloud/.secrets.json에 암호화하여 저장:

{
"SLACK_WEBHOOK_URL": "https://hooks.slack.com/services/...",
"QIITA_TOKEN": "...",
...

포인트: 리포지토리(Repository)에 commit 하지 말 것 (.gitignore로 제외).

CloudSecret 또는 GitHub Secrets 연동을 통해, 프로세스가 시작될 때 Vault로부터 inject 합니다.

Managed Agents가 실행 가능한 shell 명령어를 명시적으로 허용:

allowed_commands:
- curl # HTTP 리퀘스트
- python3 # 처리 스크립트 실행
...

┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of month (1 - 31)
...

이하는 구현 플로우의 완전한 예시입니다:

import anthropic
from datetime import datetime, timedelta
client = anthropic.Anthropic(api_key="YOUR_KEY")
...

ANALYSIS_PROMPT = f"""
다음 수집 결과로부터 "독자 임팩트 Top 5"를 추출해 주세요.
{research_text}
...
"""

import requests
import os
from datetime import datetime as dt
...

# Managed Agent의 내부 에러는 자동 재시도 (Retry)
# 단, timeout / tool_error의 경우는 아래와 같이 catch
try:
...

# Managed Agent는 execution state를 자동 저장
# 이전 실행의 context를 활용할 수 있음
STATEFUL_PROMPT = """
...

agent_config:
max_tokens_per_call: 2000 # 1회 호출(call)의 token 상한
max_tool_calls: 20 # 최대 tool call 수
...

Managed Agent의 실행 로그는 Cloud Console에서 확인할 수 있습니다:

# CLI로 로그 확인
claude logs my-agent --since 24h
# Output:
...

notifications:
  on_failure:
    slack: true
...

항목	제한 사항
최대 컨텍스트 윈도우 (Max context window)	에이전트가 사용하는 모델에 따라 다름 (Opus 4.8 = 1M)
...

✅ Cron 스케줄을 통한 에이전트 자동 실행

✅ CLI 도구의 안전한 통합 (화이트리스트 (Whitelist) 제어)

✅ Vault를 이용한 비밀 정보 (Secrets) 암호화 관리

✅ Slack / 이메일 자동 알림

✅ 복잡한 워크플로우 (검색 (search) → 분석 (analyze) → 게시 (post))의 완전 자동화

.claude/agents/my-agent.md에서 에이전트 정의

.secrets.json에서 환경 변수 설정 (gitignore 확인)

• 허용 명령어 (whitelist)를 최소 권한 원칙에 따라 정의
• 타임아웃 (Timeout) / 재시도 정책 (retry policy)을 운영 요구 사항에 맞춰 설정
• 운영 환경 적용 전 드라이 런 (dry-run)으로 24시간 모니터링
• Slack / 이메일 알림 (notification) 설정
• 실행 로그 (Execution logs) 모니터링 대시보드 구축

Sources: