Claude Code로 검증한 데이터 분석 에이전트를 Amazon Bedrock AgentCore의 관리형 서비스로 이전하는 과정을 단계별로 다룬다. 핵심 전략은 로컬 구성 요소(stdio MCP, 에이전트 실행, 외부 검색)를 각각 AgentCore Gateway, Runtime, Web Search로 1:1 대응시키는 것이며, 코드 로직 변경을 최소화한 채 서버리스 자동 확장·관리형 인증·관측성을 갖춘 프로덕션 서비스를 만든다.
핵심 포인트- Claude Code의 3요소(stdio MCP / 에이전트 실행 / 외부 검색)는 AgentCore Gateway / Runtime / Web Search에 각각 1:1로 대응된다.
- AgentCore Gateway는 Lambda 함수를 관리형 원격 MCP 서버로 노출하고 Amazon Cognito JWT 인증과 CloudWatch 관측성을 자동 제공한다.
- AgentCore Runtime은 BedrockAgentCoreApp 진입점으로 에이전트 코드를 감싸기만 하면 서버리스 컨테이너, 세션 격리, 자동 확장을 얻는다.
- AgentCore Web Search는 별도 검색 API 키 없이 IAM SigV4 인증만으로 동작해 키 관리 부담이 없다.
- Claude Agent SDK가 내부적으로 claude CLI subprocess를 실행하므로 Dockerfile에 Node.js와 @anthropic-ai/claude-code 패키지 설치가 필수이며, 컨테이너 파일시스템이 읽기 전용이라 HOME=/tmp 설정이 필요하다.
상세 정리- 배경: SQLite에 상품 20개·주문 4,512건(총매출 622,961,950원)을 담은 로컬 ecommerce 에이전트를 다중 사용자 프로덕션 환경으로 확장하는 시나리오.
- 로컬 구성: stdio MCP 서버로 ecommerce 도구 제공, Claude Agent SDK(ClaudeAgentOptions + bypassPermissions)로 에이전트 실행, web-search 도구로 외부 트렌드 검색하는 3계층 구조.
- Step 1 - 로컬 에이전트: us.anthropic.claude-sonnet-4-6 모델과 setting_sources=["project"]로 Skill을 주입해 카테고리별 매출 조회·베스트셀러·외부 트렌드를 종합한 리포트 생성 확인.
- Step 2 - Gateway 배포: deploy_gateway.py 실행 한 번으로 Lambda 함수·IAM 역할·Cognito 인증·MCP Gateway·CloudWatch 로그·Gateway 타깃 등록이 자동 생성되고 결과는 gateway.json에 저장됨.
- Gateway 검증: verify_gateway.py로 원격 경로(Gateway → Lambda → SQLite)가 로컬 stdio MCP와 동일한 총매출 622,961,950원을 반환하는지 확인.
- Step 3 - Runtime 배포: 에이전트 코드를 BedrockAgentCoreApp으로 감싸고 도구 출처를 type:"http" Gateway URL + Bearer 토큰으로 변경. deploy 명령 한 번으로 CodeBuild ARM64 빌드 및 배포.
- Runtime 함정 1 - Claude CLI 의존: Claude Agent SDK가 내부적으로 claude CLI subprocess를 실행하므로 Dockerfile에 Node.js 20 이상 및 @anthropic-ai/claude-code 패키지 설치 필수. 빠뜨리면 Runtime 컨테이너 기동 실패.
- Runtime 함정 2 - 읽기 전용 파일시스템: AgentCore Runtime 컨테이너는 /tmp 제외 읽기 전용이라 HOME=/tmp 환경변수를 반드시 설정해야 한다.
- Step 4 - Web Search: 로컬에서 mcp-proxy-for-aws가 SigV4 서명하던 구성이 Runtime 컨테이너의 IAM 자격 증명으로 자동 대체되어 코드 변경 없이 동작.
- 관측성 제약: Claude Agent SDK의 LLM 호출이 subprocess 안에서 발생하므로 gen_ai 스팬(토큰·비용)은 자동 계측에 잡히지 않음. ResultMessage를 활용해 CloudWatch 커스텀 메트릭을 수동 기록해야 정확한 비용 추적이 가능.
- 보안: Cognito 클라이언트 시크릿이 gateway.json에 포함되므로 git commit 금지. 프로덕션에서는 AWS Secrets Manager에 저장하고 런타임에서 조회하는 방식을 권장.
- 정리 주의: ECR 리포지토리, CodeBuild 프로젝트, Cognito 사용자 풀, IAM 역할, CloudWatch 로그 그룹은 자동 삭제 스크립트에 포함되지 않아 콘솔에서 수동 삭제 필요.
왜 읽나Claude Code로 프로토타이핑한 AI 에이전트를 코드 변경 최소화로 AWS 프로덕션에 배포하려는 백엔드·MLOps 엔지니어에게 단계별 배포 절차와 실전 함정을 제공한다.
AWS Korea Tech·
AWS Architecture·
데보션 (SK)·