AWS AgentCore를 사용한 AI 에이전트 구축 방법

서론

100줄 미만의 Python 코드로 스스로 도구를 선택하고 Amazon Bedrock에서 Amazon Nova Pro와 추론하며, Amazon Bedrock AgentCore Runtime의 서버리스 HTTP 엔드포인트로 실행되는 AI 에이전트를 구축할 수 있습니다. 이 글에서는 빈 폴더에서 시작하여 AWS Lambda에서 호출할 수 있는 배포된 에이전트까지 그 빌드 과정을 단계별로 안내합니다.

저는 EduCloud Academy의 'AWS AgentCore를 사용한 첫 번째 AI 에이전트 구축' 워크숍을 따라가며 이 내용을 작성했습니다. 저는 해당 세션을 완전하고 재현 가능한 가이드로 확장하고, 현재 SDK 릴리스와 코드를 검토했으며, 과정에서 제가 겪었던 문제점들까지 추가했습니다.

에이전트가 서버리스 환경을 필요로 하는 이유. 에이전트의 리소스 사용량은 예측하기 어렵습니다. 한 요청은 즉시 답변할 수 있지만, 다음 요청은 다섯 개의 도구 호출과 여러 모델 호출을 연결(chain)할 수 있습니다. 이러한 패턴에는 유휴 상태인 서버에 비용을 지불하는 것이 의미가 적습니다. AgentCore Runtime은 각 세션을 격리된 마이크로 VM에서 실행하고, 0까지 확장하며, 활성 사용량에 대해서만 청구합니다.

AgentCore가 호스팅 외에 추가하는 것. AgentCore는 프로덕션 환경에서 에이전트를 실행하기 위한 일련의 서비스입니다. Runtime(호스팅), Gateway(API 및 MCP 서버를 에이전트 도구로 변환), Identity(사용자를 대신하여 외부 서비스에 안전하게 접근), Memory, Observability 등이 있습니다. 이 가이드에서는 Runtime을 사용하며, 다른 기능들은 나중에 동일한 에이전트에 플러그인할 수 있습니다.

무엇을 구축하게 될까요?

1. 두 개의 커뮤니티 도구(calculator, current_time)와 하나의 사용자 정의 도구(letter_counter)를 가진 Strands 에이전트.
2. 모든 모델 호출과 도구 선택을 보여주는 디버그 로깅.
3. Bedrock에서 명시적으로 지정된 Amazon Nova Pro 모델.
4. curl로 로컬 테스트가 가능한 AgentCore 호환 HTTP 서비스.
5. CLI와 Lambda 모두에서 호출할 수 있는 AgentCore Runtime 클라우드 배포.

테스트에 사용된 버전: Python 3.10 이상, strands-agents 1.57, strands-agents-tools 0.8, bedrock-agentcore 1.24 및 bedrock-agentcore-starter-toolkit 0.3.13 (2026년 10월). 이 SDK들은 변화가 빠르므로, 명령어가 다를 경우 버전을 확인해 주세요.

아키텍처

모든 요청은 동일한 경로를 거칩니다. 즉, 호출자(caller)가 AgentCore 엔드포인트로 JSON을 전송하면, Strands 에이전트가 Nova Pro와 그 도구들 사이에서 루프를 돌고, 최종적으로 단순한 JSON 형태의 답변이 돌아옵니다.

상단 절반은 요청 경로(request path)이고, 하단 절반은 agent.py를 컨테이너로 패키징하여 AgentCore가 실행할 수 있도록 하는 일회성 배포 경로(one-time deployment path)입니다.

전제 조건 및 프로젝트 설정

AWS 계정, 로컬에 구성된 자격 증명(credentials), Python 3.10 이상 버전, 그리고 사용 중인 리전(Region)에서 Amazon Nova Pro 접근 권한이 필요합니다.

mkdir first-agent && cd first-agent
python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate

requirements.txt 파일을 생성합니다:

strands-agents
strands-agents-tools
bedrock-agentcore

의존성(dependencies)과 배포에 사용되는 agentcore CLI를 제공하는 스타터 툴킷(starter toolkit)을 설치합니다:

pip install -r requirements.txt
pip install bedrock-agentcore-starter-toolkit

이 툴킷은 개발 도구이기 때문에 requirements.txt에는 포함되지 않습니다. 런타임 컨테이너는 위에 언급된 세 가지 패키지만 필요합니다. 모든 것을 활성화된 가상 환경 내부에 설치해야 합니다. 워크샵에서 가장 흔하게 발생한 실수는 전역적으로(globally) 패키지를 설치하여 런타임에 누락되는 경우였습니다.

최종 프로젝트 구조는 의도적으로 작게 설계되었습니다:

first-agent/
├── agent.py           # 에이전트, 도구, 모델 및 AgentCore 진입점(entrypoint)
├── requirements.txt   # 런타임 의존성
...

단계 1: 도구를 갖춘 Strands 에이전트

단계 1: 도구를 갖춘 Strands 에이전트

Strands 에이전트는 모델(model), 도구 목록(list of tools), 그리고 프롬프트(prompt)로 구성됩니다. 이 프레임워크는 모델이 어떤 도구를 호출할지 결정하도록 하는 루프를 실행합니다. 커뮤니티에서 제공하는 두 가지 도구와 사용자 정의 도구 하나로 시작해 봅시다.

사용자 정의 도구는 단어의 글자 수를 계산합니다. 이는 언어 모델(language models)이 문자 개수를 세는 데 신뢰성이 떨어지는 반면, 5줄짜리 함수는 정확하다는 점에서 고전적인 예시입니다. @tool 데코레이터는 함수의 시그니처와 문서화된 문자열(docstring)을 모델이 읽는 도구 사양으로 변환하므로, 명확한 문서화된 문자열이 중요합니다.

# agent.py (Step 1)
from strands import Agent, tool
from strands_tools import calculator, current_time
...

실행해 보세요:

python agent.py

만약 ModuleNotFoundError: No module named 'strands_tools' 오류가 발생하면, 도구 패키지가 다른 환경으로 이동한 것입니다. .venv를 활성화하고 pip install -r requirements.txt를 다시 실행하세요.

예상 출력(에이전트가 터미널로 답변을 스트리밍합니다. 실행할 때마다 문구가 다릅니다):

Tool #1: current_time
The current time in UTC is 2026-10-04T14:32:07+00:00.

...

각 프롬프트는 다른 도구로 라우팅되었습니다. 이 라우팅이 핵심 에이전트 루프입니다. 모델은 도구 사양을 읽고, 하나를 선택하며, Strands가 이를 실행하고, 그 결과가 다시 모델로 돌아가 최종 답변을 작성하는 데 사용됩니다.

모델에 대한 참고 사항. 이 코드 스니펫에서는 모델이 구성되어 있지 않지만, 에이전트는 여전히 모델을 호출합니다. model을 생략하면 Strands는 Amazon Bedrock의 Claude 모델(global.anthropic.claude-sonnet-4-6, 버전 1.57 기준)로 기본 설정됩니다. 이 기본값은 해당 모델에 대한 Bedrock 액세스가 필요하므로, Step 2에서 하듯이 모델을 명시적으로 설정하는 것이 좋은 이유가 됩니다.

Step 2: 디버그 로깅 및 명시적 Bedrock 모델

두 가지 변경 사항이 에이전트를 본질적으로 프로덕션 준비 상태로 만듭니다. 바로 의사 결정을 보여주는 로그와, 사용자가 의도적으로 선택한 모델입니다.

로깅(Logging). strands 로거를 DEBUG로 설정하면 모델 구성, 도구 등록 및 이벤트 루프의 각 단계가 출력됩니다. 이러한 가시성은 특히 다중 에이전트 시스템에서 큰 도움이 되는데, 추적 기록을 통해 어떤 에이전트나 도구가 오작동했는지 정확히 알 수 있습니다.

모델(Model). BedrockModel은 Bedrock Converse API를 래핑합니다. 여기서는 Amazon Nova Pro를 미국 교차 리전 추론 프로파일인 us.amazon.nova-pro-v1:0을 통해 대상으로 하며, 이는 더 나은 가용성을 위해 요청을 미국 리전 전반에 걸쳐 라우팅합니다. 낮은 온도(temperature)는 도구 사용이 많은 답변의 일관성을 유지하게 합니다.

# agent.py (Step 2): additions shown at the top of the file
import logging
import os
...

리전과 모델 ID를 환경 변수에서 읽어오기 때문에 코드를 수정하지 않고도 Claude나 Nova Lite와 같은 다른 모델로 전환할 수 있습니다.

예상 출력(Expected output). 아래 첫 줄들은 Strands 1.57이 시작 시 출력하는 내용이며, 이벤트 루프 라인은 간략화되었고 버전에 따라 다릅니다.

DEBUG | strands.models.bedrock | config=<{'model_id': 'us.amazon.nova-pro-v1:0', 'include_tool_result_status': 'auto', 'temperature': 0.3}> | initializing
DEBUG | strands.models.bedrock | region=<us-east-1> | bedrock client created
DEBUG | strands.tools.registry | tool_name=<calculator>, tool_type=<function>, is_dynamic=<False> | registering tool
...

추적 기록을 켜면 요청의 전체 경로를 볼 수 있습니다: 모델 구성, 도구 등록, 모델 질의, 도구 선택 및 실행, 답변 생성. 나중에 무언가 문제가 생겼을 때 가장 먼저 봐야 할 곳이 바로 이곳입니다.

Step 3: AgentCore Runtime용 에이전트 래핑 및 로컬 테스트

AgentCore Runtime은 포트 8080에서 요청을 위한 POST /invocations와 상태 확인을 위한 GET /ping 두 개의 경로를 가진 HTTP 서비스를 기대합니다. bedrock-agentcore SDK는 이 네 줄의 코드를 통해 모두 제공합니다: 앱 가져오기, 초기화하기, 엔트리포인트 데코레이션(decorate)하기, 그리고 실행하기.

다음은 완성된 agent.py입니다:

테스트는 두 개의 터미널에서 로컬로 진행합니다. 첫 번째 터미널에서는 서비스를 시작합니다:

python agent.py

두 번째 터미널에서는 상태를 확인한 다음, 프롬프트를 전송합니다:

curl http://localhost:8080/ping

curl -X POST http://localhost:8080/invocations \
...

예상 출력:

{"status":"Healthy","time_of_last_update":1791145026}

{"result": "The letter 's' appears 4 times in 'Mississippi'."}

함정: 원시 결과를 반환하는 것. 워크숍 데모는 바로 이 지점에서 런타임 오류를 일으켰는데, 핸들러가 에이전트의 응답 객체를 그대로 반환했기 때문입니다. agent(prompt)는 메시지 외에도 메트릭, 트레이스 및 이벤트 루프 상태를 담고 있는 AgentResult를 반환합니다. SDK 버전에 따라 그리고 그 상태에 무엇이 포함되어 있는지에 따라, 이를 직접 반환하면 직렬화(serialise)에 실패하거나 호출자에게 크고 내부적인 객체를 누설시킬 수 있습니다. 제가 bedrock-agentcore 1.24로 테스트했을 때, 원시 반환은 성공했지만 응답에는 모든 메트릭 및 트레이스 필드가 포함되어 있었습니다. {"result": str(result)}를 반환하면 호출자에게 작고 안정적인 계약(contract)을 제공하며, AgentResult에 대한 str()은 최종 텍스트를 산출합니다.

4단계: AgentCore Runtime에 배포하고 호출하기

스타터 툴킷은 agent.py를 두 개의 명령어인 configure와 deploy로 실행되는 클라우드 엔드포인트로 만듭니다. 기본적으로 AWS CodeBuild에서 ARM64 컨테이너를 빌드하므로, 로컬 머신에 Docker가 필요하지 않습니다.

구성(Configure). 툴킷을 진입점(entrypoint)으로 지정합니다. 이는 requirements.txt를 감지하고 IAM 실행 역할 및 ECR 레지스트리를 생성할 것인지 제안하며, 기본값(defaults)을 수락하는 것은 첫 번째 배포에는 괜찮습니다.

agentcore configure --entrypoint agent.py --name first_agent

이 명령어는 에이전트의 설정을 담고 있는 .bedrock_agentcore.yaml 파일을 작성합니다. 버전 관리를 하되, 자격 증명(credentials)은 절대 커밋하지 마십시오.

배포(Deploy). toolkit 0.3 버전에서는 이 명령어가 이전의 agentcore launch를 대체했으며, 많은 튜토리얼에서 여전히 해당 명령어를 보여주고 있습니다.

agentcore deploy

배포가 완료되면, toolkit이 에이전트 런타임 ARN을 출력합니다. 언제든지 상태를 확인할 수 있습니다:

agentcore status

예상 출력값(요약됨; 계정 ID와 ARN 접미사는 자리 표시자입니다):

Deployment completed successfully
Agent ARN: arn:aws:bedrock-agentcore:us-east-1:123456789012:runtime/first_agent-AbCdEf1234

CLI에서 호출하기:

agentcore invoke '{"prompt": "What is 15% of 2,480?"}'

Response:
{"result": "15% of 2,480 is 372."}

AWS Lambda에서 호출하기. API를 호출할 수 있는 모든 AWS 서비스(Lambda 및 Amazon ECS 포함)가 이 에이전트를 사용할 수 있습니다. bedrock-agentcore 클라이언트의 invoke_agent_runtime 작업은 런타임 ARN, JSON 페이로드, 그리고 최소 33자 길이의 세션 ID를 필요로 합니다. 동일한 세션 ID를 공유하는 요청들은 같은 격리된 세션에 도달하여 대화 컨텍스트를 유지합니다.

# invoke_lambda.py: 배포된 에이전트를 호출하는 Lambda 핸들러
import json
import logging
...

Lambda 실행 역할은 런타임 ARN에 대해 bedrock-agentcore:InvokeAgentRuntime 권한을 필요로 합니다. 만약 사용자의 Lambda 런타임 번들에 포함된 boto3가 AgentCore보다 오래되었다면, 최신 boto3를 함수와 함께 패키징해야 합니다.

테스트 이벤트 {"prompt": "How many vowels are in 'Cameroon'?"}에 대한 예상 출력값:

{
  "statusCode": 200,
  "session_id": "session-3f6c1a9e-2b7d-4c1e-9a55-0d8e7f4b2c11",
...

문제 해결, 비용 및 정리

대부분의 첫 실행 실패는 에이전트 코드 자체가 아닌 환경, 권한 또는 모델 액세스에서 발생합니다.

문제 해결, 비용 및 정리

대부분의 첫 실행 실패는 에이전트 코드 자체가 아닌 환경, 권한 또는 모델 액세스에서 발생합니다.

**작업 완료 후 정리 (Clean up)**하여 비용이 계속 청구되지 않도록 하세요:

agentcore destroy