M0. 사전 준비

실습을 시작하기 전에 아래 준비를 마쳐 주세요. 이 페이지의 내용은 실습 시간(약 90분)에 포함되지 않으므로, 워크샵 당일 이전에 미리 완료해 두시길 권장합니다.

계정 요건

• 본인 또는 회사의 AWS 계정을 사용합니다 (계정 vending이 없습니다).

• 사용하시는 IAM 사용자/역할에 아래 IAM 정책을 연결할 수 있어야 합니다.

• AWS CDK bootstrap이 완료된 계정이어야 합니다 (AgentCore CLI가 배포에 CDK를 사용합니다). 미완료라면 다음을 실행해 주세요.

  npx cdk bootstrap aws://<계정 ID>/us-east-1

리전은 us-east-1로 고정합니다

이 워크샵의 모든 실습은 us-east-1(버지니아 북부) 에서 진행합니다. Bedrock Mantle 엔드포인트(bedrock-mantle.us-east-1.api.aws)와 GPT 5.6 Sol/Luna 접근, AgentCore Gateway·Memory 리소스 조합이 이 리전 기준으로 검증되어 있습니다. 평소 다른 리전(예: us-west-2)을 기본값으로 쓰고 계시다면 반드시 전환해 주세요.

모델 사용 준비

이 워크샵에서 호출하는 모델은 다음 네 가지입니다.

티어	모델 ID	인증·엔드포인트
판정(Verdict)	global.anthropic.claude-fable-5	Bedrock 표준 IAM (global 인퍼런스 프로파일)
판정 fallback	global.anthropic.claude-opus-4-8	동일
조사(Investigator)	openai.gpt-5.6-luna	Bedrock Mantle 엔드포인트 + Bedrock API 키
M4 비교 대상	openai.gpt-5.6-sol	동일

두 가지 준비가 필요합니다.

• Claude inference profile — Claude 계열은 온디맨드 호출 대신 global.anthropic.claude-* 형태의 cross-region/global 인퍼런스 프로파일 ID를 사용합니다 (2026-07-16 실측으로 Converse 정상 동작 확인). Bedrock 콘솔 playground에서 Claude를 처음 호출하면 안내되는 Anthropic use case form(계정당 최초 1회)이 있다면 함께 제출해 주세요.
• Mantle onboarding (GPT 계열) — Bedrock Mantle 엔드포인트로 제공되는 GPT 계열은 계정에 Mantle 사용이 활성화되어 있어야 합니다. Bedrock Mantle 콘솔의 Account Overview에서 GPT 5.6 Luna / Sol이 카탈로그에 보이는지 확인해 주세요. 회사 계정이라면 SCP/IAM으로 openai.* 모델 호출이 deny되지 않았는지도 확인이 필요합니다.

별도의 사전 확인 명령은 필요 없으며, M1의 첫 invoke와 M2의 첫 조사관 호출이 실제 호출 검증을 겸합니다. AccessDeniedException이 나면 트러블슈팅을 참고해 주세요.

Bedrock API 키 발급

조사 티어(Luna)와 M4 비교 대상(Sol)은 Bedrock Mantle 엔드포인트를 통해 호출되며, 인증에 Bedrock API 키를 사용합니다. 공식 문서의 콘솔 절차는 다음과 같습니다.

1. Amazon Bedrock 콘솔을 엽니다: https://console.aws.amazon.com/bedrock

2. 왼쪽 탐색 창에서 API keys를 선택합니다.

3. Long-term API keys 탭에서 Generate long-term API keys를 선택합니다.

4. 만료 기간을 선택하고, 필요하면 Advanced permissions에서 권한을 추가합니다.

5. Generate를 선택합니다. API 키는 한 번만 표시되므로 복사해서 안전하게 보관해 주세요.

참고

공식 문서 기준으로 long-term key는 탐색(실습) 용도이며, 프로덕션에서는 short-term key(최대 12시간)가 권장됩니다. 실습이 끝나면 콘솔에서 키를 삭제해 주세요.

콘솔 대신 CLI로 발급할 수도 있습니다 (IAM service-specific credential). 응답의 ServiceCredentialSecret 필드가 API 키 값입니다 (한 번만 표시되므로 즉시 안전한 곳에 보관).

aws iam create-service-specific-credential \
  --user-name <본인 IAM 사용자> \
  --service-name bedrock.amazonaws.com \
  --credential-age-days 7
# 응답의 ServiceCredentialSecret 값을 BEDROCK_API_KEY 로 사용합니다.

# 실습 후 삭제:
aws iam delete-service-specific-credential \
  --user-name <본인 IAM 사용자> \
  --service-specific-credential-id <응답의 ServiceSpecificCredentialId>

로컬 도구 설치

도구	요구 버전	용도
Node.js	20 이상	AgentCore CLI(@aws/agentcore) 실행
Python	3.10 이상	에이전트 코드, 실습 스크립트
uv	최신	AgentCore CLI가 Python venv/의존성 관리에 사용
AWS CLI	v2 최신 (2.35 이상 권장)	리소스 생성·확인 명령
boto3	최신 (pip install -U boto3, botocore 1.43 이상 권장)	M2/M3/M4/M5 Python 스크립트
jq	최신	JSON 파싱

AWS CLI와 boto3는 반드시 최신으로 올려 주세요

AgentCore의 신기능 API는 최근에 추가되어 구버전 CLI/boto3에는 API 모델이 없습니다. 특히 M2의 Gateway create_gateway_target에서 Web Search 커넥터(connector 타겟 타입)를 사용하는데, 구 boto3는 Unknown parameter ... must be one of: openApiSchema, smithyModel, lambda, mcpServer, apiGateway 오류를 냅니다.

aws --version          # aws-cli/2.35 이상 권장
pip install -U boto3   # botocore 1.43 이상 권장

AWS 자격증명이 us-east-1 리전에 대해 유효한지 확인해 주세요.

aws sts get-caller-identity
aws configure get region   # us-east-1 이 아니면 --region us-east-1 을 명시적으로 사용

실습 자산 내려받기

참가자용 코드(lab-src/)와 참가자 정책·모의 보안 로그 CFN·cleanup 스크립트(setup/)는 이 사이트에서 zip 하나로 배포됩니다.

• 다운로드: /downloads/aiops-workshop-lab-assets.zip

mkdir -p ~/aiops-agentcore-workshop && cd ~/aiops-agentcore-workshop
unzip ~/Downloads/aiops-workshop-lab-assets.zip
ls   # lab-src/ 와 setup/ 두 디렉토리가 보이면 정상입니다

이후 본문의 상대 경로(setup/..., lab-src/mN/...)는 압축을 푼 디렉토리 기준입니다.

번들 생성 방식

이 zip 파일은 사이트 배포 직전에 scripts/package-lab-assets.sh가 워크샵 리포지토리의 lab-src/와 setup/ 디렉토리를 묶어 docs/public/downloads/에 생성합니다. 링크가 404를 반환하면 아직 번들이 생성되지 않은 것입니다. 대안으로, 워크샵 리포지토리를 직접 클론하고 lab-src/와 setup/ 디렉토리를 그대로 사용해도 실습에는 문제가 없습니다.

IAM 정책 적용

내려받으신 setup/iam-participant-policy.json은 이 워크샵 전 모듈을 완주하는 데 필요한 권한을 담은 참가자용 정책입니다. AgentCore API, Bedrock 모델 호출, us-east-1 한정 CloudFormation·Lambda·Logs 권한이 포함됩니다.

이미 관리자급 권한이면 이 단계는 건너뛰세요

본인 자격증명이 이미 AdministratorAccess 등 충분한 권한을 갖고 있다면 아래 정책 생성·연결은 불필요합니다.

# 1) 정책 생성 — attach 전에 반드시 먼저 실행해야 합니다
aws iam create-policy \
  --policy-name aiops-workshop-participant \
  --policy-document file://setup/iam-participant-policy.json

# 2) 본인 IAM 사용자에 연결 (역할을 쓰신다면 attach-role-policy 사용)
aws iam attach-user-policy \
  --user-name <본인 사용자 이름> \
  --policy-arn arn:aws:iam::<계정 ID>:policy/aiops-workshop-participant

실습 후 정책 분리를 권장합니다

이 정책은 90분 실습을 막힘 없이 완주하기 위한 워크샵 편의 정책입니다. IAM은 글로벌 서비스라서 리전 조건이 제한적으로만 동작한다는 점에 유의해 주세요. 실습이 끝나면 이 정책을 사용자/역할에서 분리(detach)하고 삭제하시길 권장하며, 프로덕션에서는 리소스 단위 최소권한 정책을 별도로 설계하셔야 합니다.

모의 보안 로그 배포 (aiops-workshop-security)

M2에서 Gateway 타겟으로 등록할 조회 Lambda와 5개 로그 그룹 (/fashion/waf, /fashion/alb, /fashion/app-auth, /fashion/oracle-audit, /fashion/apg-pgaudit)을 CloudFormation으로 배포합니다. 담고 있는 로그·수치는 전부 합성 데모 값입니다.

aws cloudformation deploy \
  --template-file setup/mock-fashion-security.yaml \
  --stack-name aiops-workshop-security \
  --capabilities CAPABILITY_IAM \
  --region us-east-1

배포가 끝나면 출력을 확인합니다. LogQueryLambdaArn 출력이 보이면 성공입니다.

aws cloudformation describe-stacks \
  --stack-name aiops-workshop-security \
  --region us-east-1 \
  --query "Stacks[0].Outputs"

CFN 배포와 함께 커스텀 리소스가 대표 샘플 로그를 자동 시딩합니다. 추가로 합성 로그가 더 필요하시면 data-gen/generate_logs.py로 확장하실 수 있습니다 (M4/M5의 스팬 조회 시각 범위에 걸치도록 시간을 맞춰 주세요).

예상 비용

실습 계정 기준 총 약 $2–5 수준을 예상합니다 (합성 데모 값 기준). 자세한 산정 근거는 예상 비용 페이지를 참고해 주세요.

준비 완료 체크리스트

• us-east-1 리전으로 작업할 준비가 되었습니다.
• SCP/IAM으로 global.anthropic.claude-fable-5 / openai.gpt-5.6-luna / openai.gpt-5.6-sol 호출이 차단되지 않았습니다.
• Bedrock API 키(long-term)를 발급받아 보관 중입니다.
• Node.js 20+ / Python 3.10+ / uv / AWS CLI v2.35+ / boto3 최신 / jq 가 설치되었습니다.
• 참가자 IAM 정책이 연결되었습니다 (관리자급이면 해당 없음).
• aiops-workshop-security 스택이 배포되어 LogQueryLambdaArn 출력이 확인되었습니다.

모두 확인하셨다면 M1. 에이전트 배포로 이동해 주세요.