Strands 에이전트 + Agent Core AWS

발행: 1시간 전 (2025년 12월 6일 오후 12:44 GMT+9)

8 min read

원문: Dev.to

Source: Dev.to

사전 요구 사항

시작하기 전에 다음을 확인하세요:

AWS 권한
- AdministratorAccess 권한이 있는 루트 사용자 또는 프리빌리지 역할은 이 단계를 건너뛸 수 있습니다.
- 다른 사용자는 starter toolkit 정책과 관리형 정책 AmazonBedrockAgentCoreFullAccess를 연결해야 합니다.
AWS CLI
- 버전 2.0 이상.
- aws configure 로 설정합니다.
Amazon Bedrock 모델 접근
- 원하는 리전에서 Claude 3.7 Sonnet을 활성화합니다:
  AWS Management Console → Amazon Bedrock → Model access.
Python
- Python 3.10 이상.
AWS 리전 일관성
⚠️ 중요: 다음 항목에 동일한 리전을 사용하세요:
- aws configure 에 설정된 기본 리전.
- Amazon Bedrock 모델 접근을 활성화한 리전.

Toolkit 설치

단계 1: 가상 환경 만들기

# 가상 환경 생성
python -m venv .venv

# 가상 환경 활성화
# macOS/Linux:
source .venv/bin/activate

# Windows:
# .venv\Scripts\activate

단계 2: 필수 패키지 설치

# 패키지 설치 (버전 0.1.21 이상)
pip install "bedrock-agentcore-starter-toolkit>=0.1.21" strands-agents boto3

에이전트 생성

단계 1: 에이전트 파일 만들기

agentcore_starter_strands.py 라는 파일을 만들고 에이전트 코드를 넣습니다.
에이전트 특징:

AgentCore Memory (단기·장기)와 통합.
Code Interpreter를 이용한 계산 도구.
세션 관리.
사용자 정의 프롬프트 시스템.

단계 2: 요구 사항 파일 만들기

# requirements.txt
strands-agents
bedrock-agentcore

구성 및 배포

단계 1: 에이전트 구성

agentcore configure -e agentcore_starter_strands.py

대화형 프롬프트에 답합니다:

Execution Role: 필요한 권한이 포함된 역할을 자동으로 만들려면 Enter 를 누릅니다.
ECR Repository: 새 리포지토리를 만들려면 Enter 를 누르거나 기존 URI를 입력합니다.
Requirements File: requirements.txt 파일을 확인합니다.
OAuth Configuration: no 라고 입력합니다.
Request Header Allowlist: no 라고 입력합니다.
Memory Configuration:
- 기존 메모리가 있으면 선택하거나 Enter 로 새 메모리를 만듭니다.
- 새 메모리를 만들 경우 장기 메모리 추출을 활성화하려면 yes 라고 입력합니다.
- 단기 메모리는 기본적으로 항상 활성화됩니다.

단계 2: AgentCore에 배포

agentcore launch

이 명령은 다음을 수행합니다:

메모리 리소스 (STM + LTM) 프로비저닝.
종속성을 포함한 Docker 이미지 빌드.
ECR 리포지토리로 푸시.
X‑Ray가 활성화된 AgentCore 런타임 배포.
CloudWatch Transaction Search 자동 설정.
트레이스 수집이 가능한 엔드포인트 활성화.

예상 출력:

✅ Memory created: bedrock_agentcore_memory_ci_agent_memory-abc123
Observability is enabled, configuring Transaction Search...
✅ Transaction Search configured: resource_policy, trace_destination, indexing_rule
🔍 GenAI Observability Dashboard:
   https://console.aws.amazon.com/cloudwatch/home?region=us-west-2#gen-ai-observability/agent-core
✅ Container deployed to Bedrock AgentCore
Agent ARN: arn:aws:bedrock-agentcore:us-west-2:123456789:runtime/starter_agent-xyz

단계 3: 구성 확인 (오류 발생 시)

# 배포된 구성 확인
cat .bedrock_agentcore.yaml

# 리소스 프로비저닝 상태 확인
agentcore status

배포 모니터링

에이전트 상태 확인

agentcore status

표시되는 정보: Memory ID, 상태 (CREATING → ACTIVE), 유형 (STM+LTM), 에이전트 ARN, 관측 대시보드 URL, 런타임 로그 경로 등.

메모리가 활성화될 때까지 대기

⏱️ 프로비저닝은 보통 2‑3 분 정도 소요됩니다.

# 상태가 ACTIVE가 될 때까지 30초 간격으로 반복
agentcore status

메모리 및 Code Interpreter 테스트

단기 메모리 (STM)

# 첫 번째 호출 – 정보 저장
agentcore invoke '{"prompt": "내 이름은 Juan입니다"}'

# 같은 세션에서 두 번째 호출 – 정보 조회
agentcore invoke '{"prompt": "내 이름이 뭐였지?"}'

예상 응답: “당신의 이름은 Juan입니다.”

장기 메모리 (LTM)

⏱️ AgentCore는 백그라운드에서 추출 작업을 수행합니다. 사실을 저장한 후 10‑30 초 정도 기다리세요.

# 세션 1: 사실 저장
agentcore invoke '{"prompt": "내 이메일은 usuario@ejemplo.com이고 나는 AgentCore 사용자입니다"}'

# 추출이 끝날 때까지 대기
sleep 20

# 세션 2: 다른 세션에서 추출된 사실 조회
SESSION_ID=$(python -c "import uuid; print(uuid.uuid4())")
agentcore invoke '{"prompt": "내가 뭘 알고 있나요?"}' --session-id $SESSION_ID

예상 응답:

“당신의 이메일 주소는 usuario@ejemplo.com입니다.”
“당신은 AgentCore 사용자로 보입니다.”

Code Interpreter

# 데이터 저장
agentcore invoke '{"prompt": "내 데이터셋 값은: 23, 45, 67, 89, 12, 34, 56."}'

# 시각화 생성
agentcore invoke '{"prompt": "텍스트 기반 막대 그래프를 만들어 내 데이터셋 값의 분포를 적절한 라벨과 함께 표시해 주세요"}'

예상 결과: 에이전트가 matplotlib 코드를 생성하고 막대 그래프를 출력합니다.

트레이스 및 로그 보기

Amazon CloudWatch 대시보드 접근

GenAI Observability 대시보드에는 다음이 표시됩니다:

요청의 엔드‑투‑엔드 트레이스.
에이전트 실행 흐름.
메모리 검색 작업.
Code Interpreter 실행.
에이전트 추론 단계.
구성 요소별 지연 시간 분석.

agentcore status 에서 대시보드 URL을 확인하거나 직접 접근합니다:

https://console.aws.amazon.com/cloudwatch/home

리소스 정리

에이전트를 더 이상 사용하지 않을 경우 비용 발생을 방지하기 위해 생성된 리소스를 삭제합니다:

# 메모리와 런타임 전체 삭제
agentcore delete --all

# 선택 사항: ECR 리포지토리 삭제
aws ecr delete-repository --repository-name  --force

문제 해결

권한 오류: 사용자에게 AmazonBedrockAgentCoreFullAccess 정책이 부여되어 있는지, 실행 역할에 필요한 권한이 있는지 확인합니다.
메모리가 활성화되지 않음: agentcore logs 로 로그를 확인하고, 설정된 리전이 모델 리전과 일치하는지 검증합니다.
컨테이너 실행 실패: Docker가 설치되어 있는지, 계정에 ECR 할당량이 충분한지 확인합니다.
Code Interpreter가 코드 생성 안 함: 실행 역할에 AWSLambdaBasicExecutionRole(또는 동등한) 정책이 연결되어 있는지 확인합니다.

가이드 끝.