트러블슈팅

실습 도중 막히셨다면 아래에서 증상 문구를 먼저 찾아 주세요. 항목마다 증상 → 원인 → 해결 순서로 정리했습니다.

AccessDeniedException — invoke 시 모델 접근 오류

증상. M1의 agentcore invoke, M2 조사관 호출, 또는 M4 evaluate 응답에서 AccessDeniedException이 발생하거나 “You don’t have access to the model with the specified model ID” 문구가 로그에 남습니다.

원인. 다음 중 하나입니다.

• 호출 주체(IAM 사용자/역할)에 bedrock:InvokeModel 권한이 부족.
• SCP/IAM 정책이 global.anthropic.claude-fable-5 / openai.gpt-5.6-luna / openai.gpt-5.6-sol 중 하나를 명시적으로 deny.
• Anthropic use case form 미제출(계정당 최초 1회).
• Mantle 엔드포인트가 계정에 활성화되지 않아 GPT 계열 호출이 거부됨.
• 온디맨드로 Claude를 호출한 경우 — Claude는 global.anthropic.claude-* 형태의 cross-region/global 인퍼런스 프로파일 ID로 호출해야 합니다.

해결.

1. 워크샵 참가자 IAM 정책이 사용자/역할에 붙어 있는지 확인.
2. 회사 계정이라면 관리자에게 위 모델 ID가 deny되지 않았는지 확인 요청.
3. Claude(judge) 호출이 원인이면 Bedrock 콘솔 playground에서 아무 Claude 모델이나 호출해 use case form을 제출합니다.
4. 모델 ID가 global.anthropic.claude-fable-5 형태인지(온디맨드 형식이 아닌지) 확인.
5. Mantle 엔드포인트 준비는 M0 사전 준비 — 모델 사용 준비를 참고.

Fable 5 refusal → Opus 4.8 fallback

증상. 판정관 호출이 응답 없이 종료되거나, Strands가 stop_reason: refusal을 반환하며 판정 텍스트가 비어 있습니다.

원인. Claude Fable 5의 safety classifier가 보안 시나리오 프롬프트(공격 IP, 익스플로잇 관련 어휘)를 드물게 거절하는 경우가 있습니다.

해결. 판정 티어 모델을 global.anthropic.claude-opus-4-8로 임시 교체합니다.

JUDGE_MODEL_ID = "global.anthropic.claude-opus-4-8"

시스템 프롬프트에 “합성 데모 값” 고지를 명시하고, 공격자 지시문을 직접 인용하지 않도록 프롬프트를 다듬는 것도 완화에 도움이 됩니다. 자세한 배경은 ~/.claude/CLAUDE.md의 Fable 5 safety classifier 노트를 참고하세요.

참고 (2026-07-16 실측). global.anthropic.claude-fable-5 Converse 응답이 stopReason: content_filtered로 끝나는 경우, 프롬프트가 너무 짧거나 모호할 때 관찰됩니다. 시스템 프롬프트 + 구체적 사용자 질문(공격 유형·시각·로그 소스 명시)이 갖춰진 워크샵 기본 프롬프트에서는 end_turn으로 정상 응답합니다. content_filtered가 보이면 프롬프트를 더 구체적으로 다듬어 주세요.

AgentCore CLI 명령이 인식되지 않거나 옵션이 다름 — CLI 버전 불일치

증상. agentcore --version이 No such option: --version 오류를 내거나, agentcore add credential이 “unknown command”로 뜹니다.

원인. 같은 이름의 CLI가 두 종류 있습니다 — 이 워크샵이 쓰는 npm 배포판 신 CLI(@aws/agentcore)와, 구 Python 툴킷(bedrock-agentcore-starter-toolkit)이 설치하는 동명 명령입니다.

해결.

which -a agentcore   # npm 전역 경로가 맨 위여야 합니다
pip3 uninstall bedrock-agentcore-starter-toolkit
npm install -g @aws/agentcore@latest
agentcore --version

리전 불일치 — deploy UPDATE_FAILED, Mantle 엔드포인트 미접근

증상. agentcore deploy 화면에 Target: us-west-2:...처럼 us-east-1이 아닌 리전이 표시되고, BedrockAgentCore::Runtime UPDATE_FAILED 후 롤백되거나, Mantle 호출이 “endpoint not found”로 실패합니다.

원인. 현재 세션 또는 AgentCore 프로젝트에 기록된 리전이 us-east-1이 아닙니다. agentcore create는 생성 시점의 프로파일 리전을 agentcore/aws-targets.json에 기록합니다.

해결.

cat agentcore/aws-targets.json   # "region": "us-east-1" 인지 확인
# 다르면 파일 열어 값 수정 후 다시 deploy

export AWS_REGION=us-east-1
export AWS_DEFAULT_REGION=us-east-1

Gateway 타겟 생성 실패 — CreateGatewayTarget when gateway is in CREATING status

증상. setup_gateway.py가 [gateway] created: 직후 ValidationException: Cannot perform operation CreateGatewayTarget when gateway is in CREATING status로 실패합니다.

원인. create_gateway는 비동기 호출입니다 — 응답이 돌아와도 상태가 CREATING이고, READY가 되기까지 수십 초가 걸립니다.

해결. 최신 setup_gateway.py에는 READY 폴링(_wait_gateway_ready)이 내장되어 있습니다. 실행 로그에 [gateway] status: CREATING — READY 대기 중...이 보이면 정상입니다. 재실행은 idempotent하므로 실패했다면 그대로 한 번 더 실행해 주세요.

Web Search 커넥터 타겟 생성 실패 — Unknown parameter connector

증상. setup_gateway.py 실행 중 ParamValidationError: ... Unknown parameter in ... must be one of: openApiSchema, smithyModel, lambda, mcpServer, apiGateway (문구에 connector 포함).

원인. 설치된 boto3가 오래되어 Web Search의 connector 타겟 타입을 모릅니다 (M0 도구 버전 요건 참고).

해결.

pip3 install -U boto3   # botocore 1.43 이상
python3 setup_gateway.py

Memory 상태가 CREATING에서 넘어오지 않음

증상. setup_memory.py 로그에 [memory] status: CREATING — ACTIVE 대기 중...이 계속 반복되고 180초 안에 ACTIVE로 넘어가지 않습니다.

원인. 리소스 프로비저닝 지연(리전 상태) 또는 초기 사용자 리소스 정족수 확보 지연.

해결.

1. 몇 분 대기 후 스크립트를 다시 실행합니다 (이미 만들어진 리소스는 [memory] reuse existing:으로 재사용됩니다).
2. 콘솔에서 Memory 상태를 확인합니다: Bedrock AgentCore > Memory > 리소스명 > Status. FAILED면 콘솔의 오류 상세를 확인하세요.
3. list_memories API로 상태를 직접 조회할 수도 있습니다.

Fable 5 — temperature 파라미터 거부

증상. M1 agentcore invoke 이후 첫 응답이 500 오류로 실패하고, CloudWatch runtime 로그에 다음이 남습니다.

ValidationException: The model returned the following errors:
  `temperature` is deprecated for this model.
    Model id: global.anthropic.claude-fable-5

원인. 실측 기준일 2026-07-16, Claude Fable 5는 temperature 파라미터를 거부합니다. BedrockModel(model_id=..., temperature=0.3) 형태 초기화가 그대로 실패합니다.

해결. 판정 티어 코드에서 temperature 인자를 제거하고 모델 기본값을 사용합니다. lab-src/m1/main.py, lab-src/m2/main.py, lab-src/m3/main.py 모두 동일합니다. 이 워크샵의 최신 코드에는 이미 제거되어 있습니다.

Bedrock API key 형식 — ServiceCredentialSecret 사용

증상. agentcore add credential --type api-key에 잘못된 형식의 값을 넣으면 Runtime에서 Bedrock 호출이 401/403으로 실패합니다.

원인. Bedrock API key는 IAM 사용자에 대해 aws iam create-service-specific-credential --credential-age-days N으로 발급한 결과의 ServiceCredentialSecret(ABSK... 형태 단일 토큰)입니다. base64(alias:secret) 같은 다른 인코딩이 아닙니다.

해결. IAM 콘솔 또는 CLI에서 Bedrock 전용 서비스 자격증명을 발급해 ServiceCredentialSecret 값을 그대로 credential provider 값으로 넣습니다. 발급 후 24시간~설정한 age 만료 시 재발급해야 합니다.

AgentCore Memory — retrieve_memory_records가 0건 반환

증상. create_memory(strategy 없음) + create_event로 이벤트를 저장했는데, retrieve_memory_records(searchQuery=..., topK=...) 결과의 memoryRecordSummaries가 빈 배열로 돌아옵니다. 몇 분 대기 후에도 동일.

원인. 실측 기준일 2026-07-16, retrieve_memory_records는 semantic index를 요구합니다. memoryStrategies(예: summaryMemoryStrategy)를 지정하지 않은 short-term 메모리는 인덱싱되지 않으므로 이 API가 항상 0건을 반환합니다.

해결. 이 워크샵은 list_events(공유 recall 세션 aiops-recall-shared)로 최신 K개 요약을 회상합니다. 프로덕션에서 의미 검색이 필요하면 create_memory 시 memoryStrategies=[{summaryMemoryStrategy: {...}}]를 지정하고 다시 retrieve_memory_records로 전환하는 것이 정공법입니다.

GPT 5.6 Luna — Responses API 간헐 400 (invalid ‘input’)

증상. M2/M3 조사 루프에서 도구 호출 3~5회차 이후 openai.BadRequestError: Error code: 400 — invalid request body: Invalid 'input': value did not match any expected variant가 간헐적으로 발생합니다. 이전 tool call 자체는 성공하고, 다음 turn에 tool result를 붙일 때 실패로 보입니다.

원인. Strands OpenAIResponsesModel 요청 스키마와 Bedrock Mantle 백엔드 스키마 사이의 미묘한 mismatch로 추정되는 flake입니다. 판정 티어 single-shot 호출에서는 재현되지 않고, 조사 티어 tool loop에서만 재현됩니다.

해결.

• 프롬프트에 “짧게 조사하고 결론” 안내를 넣어 tool 회수를 낮춥니다.
• 실패 시 같은 세션 ID로 한 번 재시도하면 대개 완주합니다.
• 판정 티어 비교(M4 compare) 경로에는 해당되지 않습니다(tool loop 없음).

Logs Insights 쿼리 지연 / 결과 없음

증상. M4 run_eval.py가 “Downloaded 0 runtime-log entries” 또는 “세션 스팬이 0건입니다” 오류로 종료됩니다. M2/M3에서 query_security_logs 도구가 빈 결과를 반환합니다.

원인.

• 세션 스팬은 invoke 직후 몇 분 지연이 있습니다.
• run_eval.py의 기본 조회 윈도우가 60분이라, invoke 후 1시간 이상 지난 세션은 잡히지 않습니다.
• aws/spans 로그 그룹이 채워지려면 CloudWatch Transaction Search가 활성화되어 있어야 합니다.

해결.

# 조회 윈도우를 넉넉히 늘림
python3 run_eval.py --agent-id ... --session-id ... --minutes 180

CloudWatch 콘솔 > Application Signals > Transaction Search에서 활성화 상태를 확인하세요. query_security_logs 결과가 비어 있다면 로그 시딩 시각이 조회 윈도우 밖일 가능성이 큽니다 — data-gen/generate_logs.py의 시각 상수를 조정하거나 time_range 인자를 넓혀 주세요.

이 워크샵의 query_security_logs는 CloudWatch Logs Insights를 사용하지 않습니다

실측 기준일 2026-07-16, 갓 putLogEvents로 시딩된 이벤트를 CloudWatch Logs Insights가 인덱싱하기까지 수 분 지연이 있어 실계정에서 5분 이상 대기해도 start_query/get_query_results가 count=0을 돌려주는 현상을 확인했습니다. 이 워크샵의 aiops-log-query Lambda는 filter_log_events API를 사용하며, putLogEvents 직후에도 이벤트를 즉시 반환합니다. 이 때문에 M0 모의 스택의 IAM 정책에서도 Logs Insights 관련 액션(logs:StartQuery 등)이 빠져 있고, filter_log_events가 넓은 시간 창에서 첫 페이지가 비어 있을 수 있어 최대 10페이지 nextToken으로 순회합니다.

조사관이 로그 도구를 호출하지 않음 (로그 증거 게이트 재시도)

증상. M2/M3 응답 로그에 다음이 보입니다.

이전 응답은 로그 조회 도구를 호출하지 않았습니다. 반드시 query_security_logs 또는 get_waf_blocked_requests 를 최소 한 번 호출하여…

원인. 조사관(Luna)이 사전 지식이나 web-search만으로 결론에 도달했습니다. main.py의 _called_log_tool()이 로그 조회 도구 호출 여부를 검증해 재조사를 요청합니다.

해결. 대부분의 경우 재시도에서 정상적으로 로그 도구를 호출합니다. 두 번째 시도에도 실패하면 판정관에게 “증거 불충분” 신호가 명시됩니다 — 프롬프트나 도구 등록 상태(Gateway 타겟)를 재점검해 주세요.

agentcore dev 프롬프트 인자 호출이 “Dev server not running on port 8080”

증상. 터미널 1에서 agentcore dev를 띄우고 터미널 2에서 프롬프트 인자를 넘겼는데 위 오류가 납니다.

원인. 기본 agentcore dev는 웹 UI 모드로 떠서 8080 포트에 리슨하지 않는 경우가 있습니다. EC2 등 헤드리스 환경에서도 웹 UI 모드는 쓸 수 없습니다.

해결. 터미널 1을 --logs 모드로 다시 띄웁니다.

agentcore dev --logs

Runtime 로그 그룹이 cleanup 후에도 남음

증상. cleanup.sh 실행이 끝났는데 /aws/bedrock-agentcore/runtimes/* 등 로그 그룹이 계속 보입니다.

원인. CloudWatch 로그 그룹은 리소스를 지워도 잔존합니다. cleanup.sh 말미 안내에 따라 수동 삭제가 필요합니다.

해결. M6 cleanup 페이지의 “CloudWatch 로그 그룹을 삭제합니다” 단계를 참고해 대상을 나열하고 하나씩 delete-log-group 하세요.