Claude Code로 만든 데이터 분석 에이전트, Amazon Bedrock AgentCore로 프로덕션 배포하기

많은 팀이 Claude Code로 자체 에이전트를 만들어 사용하고 있습니다. 예를 들어 데이터 분석 팀에서는 Skill로 리포트 형식을 표준화하고, MCP(Model Context Protocol) 서버로 사내 데이터베이스를 연결하고, 웹 검색으로 시장 동향까지 반영해 매출 리포트 작성을 자동화합니다. 이렇게 만든 에이전트는 개인 도구를 넘어 팀 전체가 활용할 수 있는 자산이 됩니다.

그러나 로컬에서 검증한 에이전트를 조직의 서비스로 확장하는 일은 간단하지 않습니다. 노트북에서 실행되던 stdio 방식의 MCP 서버는 다른 사용자가 접근할 수 없고, 인증과 권한 관리, 확장성, 모니터링은 별도로 구축해야 합니다. 이 때문에 검증이 끝난 에이전트를 프로덕션용으로 처음부터 다시 작성하는 경우가 많습니다.

이 글에서는 Claude Code에서 만든 이커머스 분석 에이전트를 코드 로직의 변경을 최소화하면서 Amazon Bedrock AgentCore의 관리형 서비스로 이전하는 전체 과정을 다룹니다. AWS 계정 준비부터 배포, 검증, 리소스 정리까지 순서대로 따라 할 수 있도록 구성했습니다.

솔루션 개요

핵심은 Claude Code를 구성하는 세 요소를 AgentCore의 관리형 서비스로 각각 대응시키는 것입니다.

Claude Code (로컬)	AgentCore (프로덕션)	얻는 것
stdio MCP 서버	AgentCore Gateway	관리형 원격 MCP 엔드포인트, JWT 인증
로컬 에이전트 실행	AgentCore Runtime	서버리스 컨테이너, 세션 격리, 자동 확장
외부 검색	AgentCore Web Search	별도 API 키가 필요 없는 관리형 웹 검색

Skill은 별도 서비스 없이 Runtime 컨테이너에 그대로 포함되어 동일한 리포트 형식을 유지합니다. 로컬과 프로덕션을 잇는 다리는 Claude Agent SDK입니다. SDK는 Claude Code의 프로젝트 설정을 그대로 읽어 비대화형으로 실행할 수 있고, stdio MCP와 원격 MCP를 동일한 방식으로 다루기 때문에 전환 과정에서 에이전트 로직을 다시 작성할 필요가 없습니다. <그림 1. 로컬 Claude Code 환경(좌)과 AgentCore 프로덕션 환경(우)의 구성 대응>

예제 시나리오는 다음과 같습니다. 가상의 온라인 쇼핑몰 AnyCompany는 6개월치 주문 데이터(주문 4,512건, 매출 약 6.2억 원)를 보유하고 있고, 분석가는 Claude Code로 매출 리포트를 자동 작성해 왔습니다. 이 에이전트를 네 단계에 걸쳐 프로덕션으로 이전합니다.

단계 1: 출발점이 되는 로컬 에이전트를 구성하고 실행합니다.
단계 2: 사내 데이터 조회 도구를 AgentCore Gateway로 전환합니다.
단계 3: 에이전트 본체를 AgentCore Runtime으로 배포합니다.
단계 4: AgentCore Web Search로 외부 검색을 연동하고 전체 경로를 검증합니다.

전체 예제 코드는 GitHub 리포지토리에서 받을 수 있습니다.

사전 준비 사항

이 예제를 실행하려면 다음이 필요합니다.

AWS 계정과 관리자 수준 권한(Amazon Bedrock, AgentCore, AWS Lambda, AWS IAM, Amazon Cognito, Amazon ECR, AWS CodeBuild)
AWS CLI v2
Python 3.11 이상과 패키지 관리자 uv
Node.js 20 이상(Claude Code CLI 실행에 필요)
Amazon Bedrock에서 Anthropic Claude Sonnet 4.6 모델 액세스 활성화

모든 예제는 미국 동부(버지니아 북부, us-east-1) 리전을 기준으로 합니다. AgentCore Web Search가 현재 us-east-1에서 제공되기 때문입니다. 실습 단계에서는 편의상 관리자 권한으로 진행하되, 프로덕션 환경에서는 필요한 리소스로 범위를 한정한 최소 권한 정책을 별도로 구성하시기 바랍니다.

AWS CLI 구성

AWS CLI를 설치한 뒤 자격 증명을 구성합니다. IAM Identity Center를 사용하는 경우 aws configure sso로, 액세스 키를 사용하는 경우 aws configure로 설정합니다. 구성이 완료되었는지 확인합니다.

aws sts get-caller-identity

계정 번호와 사용자 정보가 출력되면 정상입니다.

Amazon Bedrock 모델 액세스 활성화

Amazon Bedrock 콘솔에서 리전을 버지니아 북부(us-east-1)로 변경한 뒤, 좌측 메뉴의 Model access에서 Anthropic Claude Sonnet 4.6에 대한 액세스를 요청합니다. 일반적으로 즉시 활성화됩니다. CLI로도 확인할 수 있습니다.

aws bedrock list-foundation-models --region us-east-1 \
  --query "modelSummaries[?contains(modelId,'claude-sonnet-4')].modelId" --output text

개발 도구 설치

# uv 설치 (macOS/Linux)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Node.js 20 이상 (macOS 예시)
brew install node

# Claude Code CLI
npm install -g @anthropic-ai/claude-code
claude --version

프로젝트 준비

예제 코드를 받고 가상 환경을 구성합니다.

git clone https://github.com/aws-samples/sample-agentic-ai-acceleration-kr.git
cd sample-agentic-ai-acceleration-kr/projects/claude-code-to-agentcore
uv venv
uv pip install "claude-agent-sdk>=0.1.19" "mcp>=1.2.0" \
  "bedrock-agentcore>=1.1.4" "bedrock-agentcore-starter-toolkit" "boto3>=1.35"

마지막으로 공통 환경 변수를 설정합니다. Claude Code와 Claude Agent SDK가 Anthropic API 대신 Amazon Bedrock을 통해 모델을 호출하도록 하는 설정입니다.

export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1

단계 1: 출발점이 되는 로컬 에이전트 구성

분석가가 Claude Code에서 사용하던 구성은 세 가지입니다.

구성 요소	역할	형태
Skill (sales-report)	경영진 리포트 표준 4단 형식 정의	`.claude/skills/sales-report/SKILL.md`
MCP (ecommerce)	사내 DB 조회 도구 3종	stdio MCP 서버
MCP (web-search)	외부 시장 트렌드 검색	AgentCore Web Search 프록시

먼저 실습용 데이터를 생성합니다. 시드가 고정되어 있어 누가 실행해도 같은 데이터가 만들어집니다.

uv run python local_agent/data/generate_data.py
# products=20  orders=4512  총매출=622,961,950원

이 구성을 비대화형으로 재현하기 위해 Claude Agent SDK를 사용합니다. setting_sources=["project"] 옵션을 지정하면 SDK가 .claude/settings.json, .mcp.json, .claude/skills/ 디렉토리를 Claude Code와 동일하게 읽어들입니다. 별도의 재작성 없이 Claude Code에서 사용하던 세션을 코드로 실행하는 셈입니다.

options = ClaudeAgentOptions(
    model="us.anthropic.claude-sonnet-4-6",
    setting_sources=["project"],   # .claude/settings.json, .mcp.json, skills/ 로드
    permission_mode="bypassPermissions",
)

에이전트를 실행해 봅니다.

uv run python local_agent/agent.py "2026 상반기 매출 리포트를 작성해줘"

에이전트는 ecommerce MCP 도구로 카테고리별 매출과 베스트셀러를 조회하고, web-search 도구로 최신 이커머스 트렌드를 찾은 뒤, sales-report Skill의 형식에 맞춰 리포트를 작성합니다. 여기까지가 로컬에서 검증된 출발점입니다.

<그림 2. Local Skills 검증 결과>

단계 2: 사내 MCP 도구를 AgentCore Gateway로 전환

가장 먼저 이전할 대상은 사내 데이터 조회 도구입니다. 로컬 stdio MCP 서버는 실행한 프로세스 안에서만 동작하므로, 여러 사용자와 에이전트가 인증을 거쳐 동시에 호출하려면 관리형 원격 MCP 서버가 필요합니다. AgentCore Gateway는 Lambda 함수나 API 같은 백엔드를 단일 MCP 엔드포인트로 노출하고, 인증과 프로토콜 변환, 도구 검색을 대신 처리합니다.

전환 작업은 기계적입니다. 로컬 MCP 서버의 도구 함수를 그대로 Lambda 핸들러로 옮기고, @mcp.tool() 데코레이터가 담고 있던 입력 스키마를 Gateway 타깃의 toolSchema로 선언합니다. SQL 쿼리를 포함한 도구 로직은 변경되지 않습니다.

로컬 stdio MCP	AgentCore Gateway
FastMCP가 stdin/stdout으로 JSON-RPC 수신	Gateway가 도구 호출을 Lambda 이벤트로 변환
`@mcp.tool()` 데코레이터와 docstring	타깃의 inline `toolSchema`
`.mcp.json`의 stdio 등록	MCP HTTPS 엔드포인트와 JWT 인증

배포 스크립트를 실행합니다.

uv run python gateway/deploy_gateway.py

이 스크립트는 다음 작업을 수행합니다.

Lambda 실행 역할과 함수를 생성합니다. SQLite 데이터베이스 파일을 함수 패키지에 포함합니다.
Amazon Cognito 기반 JWT 인증과 함께 MCP Gateway를 생성합니다. CloudWatch 로그와 트레이스 같은 관측성 설정도 자동으로 활성화됩니다.
Gateway 서비스가 Lambda를 호출할 수 있도록 리소스 기반 정책을 부여합니다. 이때 SourceAccount와 SourceArn 조건을 지정해 이 계정의 해당 Gateway만 호출할 수 있도록 범위를 한정합니다.
Lambda를 Gateway 타깃으로 등록하고, 배포 결과를 gateway.json 파일에 저장합니다.

스크립트는 다시 실행해도 안전합니다. 같은 이름의 Gateway가 이미 있으면 재사용하고 Lambda 코드만 갱신합니다. 한 가지 주의할 점은 gateway.json에 JWT 발급용 Cognito 클라이언트 시크릿이 포함된다는 것입니다. 이 파일은 버전 관리에 커밋하지 않아야 하며, 예제 리포지토리에서는 .gitignore로 제외되어 있습니다.

배포가 끝나면 JWT 토큰으로 Gateway를 직접 호출해 검증합니다.

uv run python gateway/verify_gateway.py

로컬 stdio MCP와 동일한 값(총매출 622,961,950원)을 원격 경로(Gateway, Lambda, SQLite)로 반환하는 것을 확인할 수 있습니다.

<그림 3. AgentCore Gateway가 도구 3종을 노출하고 로컬과 동일한 매출 값을 반환>

도구 목록에 x_amz_bedrock_agentcore_search가 자동으로 추가된 점도 확인할 수 있습니다. Gateway는 등록된 도구가 많아져도 에이전트가 의미 기반 검색으로 적절한 도구를 찾을 수 있도록 검색 도구를 기본 제공합니다. 배포가 완료되면 Amazon Bedrock AgentCore console의 Gateways 탭에서 anycompany-ecommerce-gw가 생성된 것을 확인할수 있습니다. 웹 검색 게이트웨이는 Part 1(Claude Code)에서 만든 것을 그대로 재사용하므로 새로 생성되지 않습니다.

단계 3: 에이전트를 AgentCore Runtime으로 배포

다음은 에이전트 실행 환경입니다. AgentCore Runtime은 에이전트를 위한 서버리스 컨테이너 실행 환경으로, 세션 격리와 자동 확장, 관측성을 기본 제공합니다.

이 단계에서 배포하는 소스는 runtime/ecommerce_runtime.py 하나이며, 아래에서 설명하는 변경 사항이 모두 이 파일에 들어 있습니다. 코드 변경은 크지 않습니다. 로컬 agent.py의 에이전트 로직은 그대로 두고, 진입점을 BedrockAgentCoreApp으로 감쌉니다.

app = BedrockAgentCoreApp()

@app.entrypoint
async def invoke(payload: dict):
    async with ClaudeSDKClient(options=build_options()) as client:
        await client.query(payload["prompt"])
        async for msg in client.receive_response():
            ...   # 응답 스트리밍

달라지는 것은 도구의 출처뿐입니다. 이커머스 도구는 stdio MCP 대신 단계 2에서 만든 Gateway를 가리키도록 변경합니다. Claude Agent SDK는 stdio와 원격 HTTP MCP 서버를 동일하게 다루므로, 등록 방식만 바뀔 뿐 에이전트가 도구를 사용하는 방식은 그대로입니다.

mcp_servers["ecommerce"] = {           # 로컬 stdio 대신 원격 MCP
    "type": "http", "url": ECOMMERCE_GW_URL,
    "headers": {"Authorization": f"Bearer {token}"}
}

배포는 agentcore CLI가 담당합니다. configure로 컨테이너 설정을 만들고 deploy를 실행하면 CodeBuild가 클라우드에서 ARM64 이미지를 빌드해 Runtime을 생성합니다. 로컬에 Docker가 없어도 됩니다.

uv run python runtime/ecommerce_runtime.py deploy
# >> configure (container) ... >> deploy (CodeBuild ARM64)
# deployed runtime 'anycompany_ecommerce'

컨테이너 이미지 구성 시 두 가지를 유의해야 합니다. 첫째, Claude Agent SDK는 내부적으로 claude CLI를 실행하므로 Dockerfile에 Node.js와 @anthropic-ai/claude-code 패키지를 설치해야 합니다. 둘째, AgentCore Runtime의 파일 시스템은 /tmp를 제외하면 읽기 전용이므로 HOME=/tmp를 설정해야 합니다. 예제의 배포 스크립트는 이 구성이 반영된 Dockerfile을 자동으로 적용합니다.

Gateway 접속 정보는 배포 시 환경 변수로 Runtime에 전달됩니다. 실습에서는 Cognito 클라이언트 정보를 환경 변수로 주입하지만, 프로덕션 환경에서는 클라이언트 시크릿을 AWS Secrets Manager에 저장하고 런타임에서 조회하는 방식을 권장합니다. 배포가 완료되면 Amazon Bedrock AgentCore console의 Runtime에서 anycompany_ecommerce생성이 되는것을 확인할수 있습니다.

단계 4: AgentCore Web Search로 외부 검색 연동

마지막 조각은 시장 트렌드 검색입니다. AgentCore Web Search는 Amazon의 검색 인덱스를 기반으로 한 관리형 웹 검색 기능으로, 별도의 검색 API 키나 외부 계정 없이 SigV4(IAM) 인증만으로 사용할 수 있습니다.

이 기능은 로컬 환경에서 이미 사용하던 구성을 그대로 재사용합니다. 로컬에서는 mcp-proxy-for-aws가 stdio 요청을 SigV4 서명 요청으로 변환했는데, Runtime 컨테이너 안에서도 같은 프록시가 컨테이너의 IAM 자격 증명으로 서명을 수행합니다. 로컬에서 검증한 웹 검색 경로가 프로덕션에서 동일하게 동작합니다.

이제 세 요소가 모두 준비되었습니다. 배포된 Runtime을 호출하면 Skill, Gateway, Web Search를 모두 사용한 매출 리포트가 프로덕션 환경에서 생성됩니다.

uv run python runtime/ecommerce_runtime.py invoke \
  "2026 상반기 매출 리포트. web-search로 트렌드를 반영해줘"

<그림 4. 배포된 Runtime이 사내 데이터, 외부 트렌드, 리포트 형식을 종합해 생성한 결과>

요청이 처리되는 전체 경로는 다음과 같습니다. 사용자는 InvokeAgentRuntime API를 한 번 호출하면 되고, 인증과 도구 호출, 확장, 로깅은 AgentCore가 처리합니다.

<그림 5. Runtime이 Gateway(사내 데이터)와 Web Search(외부 트렌드)를 호출하고 Amazon Bedrock이 종합>

배포된 에이전트는 별도 설정 없이 AgentCore Observability(CloudWatch 콘솔의 GenAI Observability → Agent Core 화면)에서 관찰할 수 있습니다. 호출 한 건이 하나의 트레이스로 기록되어 세션 단위로 따라갈 수 있고, Gateway 쪽에는 도구 호출이 도구 이름 단위 스팬으로 남아 어느 도구가 병목인지 스팬 폭만으로 진단할 수 있습니다.

한 가지 유의할 점은 Claude Agent SDK의 구조입니다. 모델 호출이 claude CLI 서브프로세스 안에서 일어나므로, 토큰과 비용이 담긴 LLM 스팬(gen_ai.*)은 자동 계측에 잡히지 않습니다. 대신 SDK가 스트림 마지막에 반환하는 ResultMessage(토큰·비용·레이턴시)를 활용해 호출마다 gen_ai 스팬과 CloudWatch 커스텀 메트릭을 직접 기록하면, 콘솔에서 입출력 프롬프트 확인부터 토큰·비용 추이, 이상탐지 알람까지 갖출 수 있습니다. 프롬프트 원문 수집은 PII를 고려해 옵트인으로 설정하는 것을 권장합니다. 전체 구현은 예제 리포지토리의 runtime/observability.py와 observability/ 가이드에 포함되어 있습니다.

배포 이후의 품질 관리도 함께 고려할 수 있습니다. 예제 리포지토리의 evaluation 디렉토리에는 배포된 Runtime을 대상으로 한 회귀 테스트 러너(run_eval.py)와 CloudWatch 트레이스를 기반으로 응답 품질을 채점하는 AgentCore Evaluations 연동 예제가 포함되어 있습니다.

리소스 정리

실습을 마쳤다면 불필요한 과금이 발생하지 않도록 생성한 리소스를 삭제합니다.

# 1) Runtime 삭제
cd runtime/.build/anycompany_ecommerce
agentcore destroy

# 2) Gateway 타깃과 Gateway 삭제 (gateway.json의 gateway_id 사용)
aws bedrock-agentcore-control delete-gateway-target \
  --gateway-identifier <GATEWAY_ID> --target-id <TARGET_ID> --region us-east-1
aws bedrock-agentcore-control delete-gateway \
  --gateway-identifier <GATEWAY_ID> --region us-east-1

# 3) Lambda 삭제
aws lambda delete-function --function-name anycompany-ecommerce-tools --region us-east-1

이 예제의 주요 과금 요소는 Amazon Bedrock의 모델 호출(토큰 사용량 기반), AgentCore Runtime 실행 시간, Lambda 호출, ECR 이미지 저장입니다. 실습 규모에서는 모두 소액이지만, 사용하지 않는 리소스는 위와 같이 정리하는 것을 권장합니다.

위 명령은 Runtime, Gateway, Lambda를 삭제합니다. 이 외에 배포 과정에서 생성된 Cognito 사용자 풀, ECR 리포지토리(bedrock-agentcore-anycompany_ecommerce), CodeBuild 프로젝트, IAM 역할, CloudWatch 로그 그룹은 남아 있으므로, 과금을 완전히 없애려면 콘솔에서 함께 삭제하세요. 관측성 이상탐지 알람을 구성했다면 python observability/setup_anomaly_alarms.py –delete 로 삭제할 수 있습니다.

마무리

이 글에서는 Claude Code에서 검증한 데이터 분석 에이전트를 Amazon Bedrock AgentCore로 이전하는 과정을 살펴보았습니다. 핵심은 처음부터 다시 만드는 것이 아니라 구성 요소를 관리형 서비스로 대응시키는 것입니다. Skill은 컨테이너에 그대로 포함되고, 로컬 stdio MCP는 AgentCore Gateway로 전환되어 인증과 관측성을 얻고, 에이전트 실행은 AgentCore Runtime으로 옮겨져 서버리스 자동 확장을 얻고, 외부 검색은 AgentCore Web Search로 키 관리 없이 동작합니다.

그 결과 분석가의 노트북에서 동작하던 에이전트가 코드 로직의 변경을 최소화한 채 다중 사용자, 관리형 인증, 자동 확장, 관측성을 갖춘 프로덕션 서비스가 되었습니다. 검증과 실험은 Claude Code에서 빠르게 진행하고 운영은 AgentCore에 맡기는 것이 두 도구를 함께 사용할 때 얻는 가장 큰 가치입니다.

전체 예제 코드는 GitHub 리포지토리에서 확인할 수 있습니다. Amazon Bedrock AgentCore 제품 페이지와 개발자 안내서에서 더 자세한 내용을 확인하시기 바랍니다.

AWS 기술 블로그