Claude Agent SDK는 대화 상태를 유지하고 영구적인 환경에서 명령을 실행한다는 점에서 기존의 상태 비저장(stateless) LLM API와 다릅니다. 이 가이드에서는 프로덕션에서 SDK 기반 에이전트를 배포하기 위한 아키텍처, 호스팅 고려 사항 및 모범 사례를 다룹니다.

호스팅 요구 사항

컨테이너 기반 샌드박싱

보안과 격리를 위해 SDK는 샌드박스 컨테이너 환경 내에서 실행해야 합니다. 이를 통해 프로세스 격리, 리소스 제한, 네트워크 제어 및 임시 파일 시스템을 제공합니다.

SDK는 명령 실행을 위한 프로그래밍 방식의 샌드박스 구성도 지원합니다.

시스템 요구 사항

각 SDK 인스턴스에는 다음이 필요합니다:

• 런타임 종속성

  • Python 3.10+ (Python SDK용) 또는 Node.js 18+ (TypeScript SDK용)
  • Node.js (Claude Code CLI에 필요)
  • Claude Code CLI: npm install -g @anthropic-ai/claude-code

• 리소스 할당

  • 권장: 1GiB RAM, 5GiB 디스크, 1 CPU (작업에 따라 필요에 맞게 조정)

• 네트워크 접근

  • api.anthropic.com으로의 아웃바운드 HTTPS
  • 선택 사항: MCP 서버 또는 외부 도구에 대한 접근

SDK 아키텍처 이해

상태 비저장 API 호출과 달리, Claude Agent SDK는 다음과 같은 장기 실행 프로세스로 작동합니다:

• 영구적인 셸 환경에서 명령을 실행합니다
• 작업 디렉토리 내에서 파일 작업을 관리합니다
• 이전 상호작용의 컨텍스트를 활용하여 도구 실행을 처리합니다

샌드박스 제공업체 옵션

여러 제공업체가 AI 코드 실행을 위한 안전한 컨테이너 환경을 전문으로 합니다:

• Modal Sandbox - 데모 구현
• Cloudflare Sandboxes
• Daytona
• E2B
• Fly Machines
• Vercel Sandbox

자체 호스팅 옵션(Docker, gVisor, Firecracker)과 상세한 격리 구성에 대해서는 격리 기술을 참조하세요.

프로덕션 배포 패턴

패턴 1: 임시 세션

각 사용자 작업에 대해 새 컨테이너를 생성한 후, 완료되면 삭제합니다.

일회성 작업에 가장 적합하며, 작업이 완료되는 동안 사용자가 AI와 상호작용할 수 있지만, 완료되면 컨테이너가 삭제됩니다.

예시:

• 버그 조사 및 수정: 관련 컨텍스트를 활용하여 특정 이슈를 디버그하고 해결
• 송장 처리: 영수증/송장에서 데이터를 추출하고 구조화하여 회계 시스템에 전달
• 번역 작업: 문서 또는 콘텐츠 배치를 언어 간 번역
• 이미지/비디오 처리: 미디어 파일에 변환, 최적화를 적용하거나 메타데이터를 추출

패턴 2: 장기 실행 세션

장기 실행 작업을 위해 영구적인 컨테이너 인스턴스를 유지합니다. 종종 수요에 따라 컨테이너 내에서 여러 Claude Agent 프로세스를 실행합니다.

사용자 입력 없이 자율적으로 행동하는 에이전트, 콘텐츠를 제공하는 에이전트 또는 대량의 메시지를 처리하는 에이전트에 가장 적합합니다.

예시:

• 이메일 에이전트: 수신 이메일을 모니터링하고 콘텐츠에 따라 자율적으로 분류, 응답 또는 조치를 취함
• 사이트 빌더: 컨테이너 포트를 통해 제공되는 실시간 편집 기능으로 사용자별 맞춤 웹사이트를 호스팅
• 고빈도 챗봇: 빠른 응답 시간이 중요한 Slack과 같은 플랫폼에서 지속적인 메시지 스트림을 처리

패턴 3: 하이브리드 세션

데이터베이스 또는 SDK의 세션 재개 기능에서 가져온 히스토리와 상태로 하이드레이션되는 임시 컨테이너입니다.

사용자가 간헐적으로 상호작용하여 작업을 시작하고, 작업이 완료되면 종료되지만 계속할 수 있는 컨테이너에 가장 적합합니다.

예시:

• 개인 프로젝트 매니저: 간헐적인 체크인으로 진행 중인 프로젝트를 관리하고, 작업, 결정 및 진행 상황의 컨텍스트를 유지
• 심층 리서치: 여러 시간에 걸친 연구 작업을 수행하고, 발견 사항을 저장하며 사용자가 돌아오면 조사를 재개
• 고객 지원 에이전트: 여러 상호작용에 걸친 지원 티켓을 처리하고, 티켓 히스토리와 고객 컨텍스트를 로드

패턴 4: 단일 컨테이너

하나의 글로벌 컨테이너에서 여러 Claude Agent SDK 프로세스를 실행합니다.

에이전트들이 긴밀하게 협업해야 하는 경우에 가장 적합합니다. 에이전트들이 서로의 작업을 덮어쓰는 것을 방지해야 하므로 이것은 가장 인기가 적은 패턴일 가능성이 높습니다.

예시:

• 시뮬레이션: 비디오 게임과 같은 시뮬레이션에서 서로 상호작용하는 에이전트.

FAQ

샌드박스와 어떻게 통신하나요?

컨테이너에서 호스팅할 때, SDK 인스턴스와 통신하기 위해 포트를 노출합니다. 애플리케이션은 외부 클라이언트를 위한 HTTP/WebSocket 엔드포인트를 노출할 수 있으며, SDK는 컨테이너 내부에서 실행됩니다.

컨테이너 호스팅 비용은 얼마인가요?

에이전트 서비스의 주요 비용은 토큰이며, 컨테이너는 프로비저닝하는 사양에 따라 다르지만 최소 비용은 시간당 약 5센트입니다.

유휴 컨테이너를 언제 종료하고 언제 유지해야 하나요?

이는 제공업체에 따라 다를 수 있으며, 각 샌드박스 제공업체는 샌드박스가 종료될 수 있는 유휴 타임아웃에 대해 다른 기준을 설정할 수 있습니다. 사용자 응답이 얼마나 자주 있을 것으로 예상되는지에 따라 이 타임아웃을 조정해야 합니다.

Claude Code CLI는 얼마나 자주 업데이트해야 하나요?

Claude Code CLI는 semver로 버전이 관리되므로, 모든 호환성을 깨는 변경 사항은 버전이 지정됩니다.

컨테이너 상태와 에이전트 성능을 어떻게 모니터링하나요?

컨테이너는 단순히 서버이므로 백엔드에 사용하는 동일한 로깅 인프라가 컨테이너에도 작동합니다.

에이전트 세션은 타임아웃되기 전까지 얼마나 오래 실행될 수 있나요?

에이전트 세션은 타임아웃되지 않지만, Claude가 루프에 빠지는 것을 방지하기 위해 'maxTurns' 속성을 설정하는 것을 권장합니다.

다음 단계

• 보안 배포 - 네트워크 제어, 자격 증명 관리 및 격리 강화
• TypeScript SDK - 샌드박스 설정 - 프로그래밍 방식으로 샌드박스 구성
• 세션 가이드 - 세션 관리에 대해 알아보기
• 권한 - 도구 권한 구성
• 비용 추적 - API 사용량 모니터링
• MCP 통합 - 커스텀 도구로 확장