AWS 기술 블로그
Amazon Bedrock AgentCore Runtime을 쉽고 빠르게 시작하기
1. 개요
1.1. AgentCore Runtime이란?
AI 에이전트 개발은 PoC/MVP/프로토타입 단계에서는 놀라울 정도로 빠르게 진행됩니다. 며칠 안에 Strands Agents, LangGraph, CrewAI와 같은 에이전트 프레임워크로 인상적인 PoC를 구축할 수 있고, 노트북에서 실행되는 에이전트가 복잡한 질문에 답하고 도구를 호출하는 모습을 볼 수 있습니다. 로컬 개발 환경에서 AI 에이전트를 실험할 때는 모든 것이 순조롭게 보입니다. 단일 사용자가 노트북에서 에이전트를 실행하고, 메모리 제약이 없으며, 보안 경계가 명확하지 않아도 괜찮습니다. 그러나 경영진에게 PoC/프로토타입 결과를 보여주고 프로덕션 환경으로 전환하려는 순간, 보안, 성능, 가용성, 확장성에 대한 일반적인 프로덕션 요구사항을 충족해야 하는 난제가 기다리고 있습니다. 이것이 업계에서 “프로토타입 트랩(Prototype Trap)“이라고 부르는 현상으로, 인상적인 데모와 실제 엔터프라이즈 수요를 처리할 수 있는 시스템 사이의 간극을 말합니다. 개발팀은 에이전트의 핵심 기능에 집중하는 대신, 세션 관리, 신원 제어, 메모리 시스템, 관찰성을 위한 기반 인프라를 구축하는 데 몇 달을 소비하게 됩니다. Amazon Bedrock AgentCore(이하 AgentCore)는 바로 이 간극을 해소하기 위해 설계된 관리형 서비스입니다. AgentCore에는 AgentCore Identity나 AgentCore Gateway 등 다양한 서비스가 있지만, 중심을 담당하는 서비스가 AgentCore Runtime입니다.
AgentCore Runtime은 로컬 개발에서 프로덕션 배포로의 여정을 근본적으로 단순화합니다. 파이썬 SDK의 @app.entrypoint 데코레이터로 로컬 함수를 HTTP 서비스로 변환할 수 있어, 최소한의 코드 변경으로 프로토타입에서 본격 운영 환경으로 전환할 수 있습니다. 에이전트가 배포되면 AWS의 관리형 인프라가 스케일링, 보안, 가용성을 처리하므로, 팀은 차별화된 에이전트 기능에 집중할 수 있습니다.
AgentCore Runtime의 진정한 가치는 실제 프로덕션 시나리오에서 드러납니다. 고객 지원 에이전트를 고려해보세요. 프로토타입 단계에서는 노트북에서 실행되고 질문에 답변할 수 있는 기본 에이전트가 있을 수 있습니다. 그러나 프로덕션으로 이동하면서, 이 에이전트는 고객 정보를 CRM에서 조회하고, 주문 상태를 확인하며, 지식 베이스에서 제품 정보를 가져오고, 필요한 경우 티켓을 생성해야 합니다.
AgentCore를 사용하면 먼저 AgentCore Runtime에 에이전트를 배포하여 완전한 세션 격리와 확장성을 얻습니다. 그런 다음 AgentCore Memory를 추가하여 에이전트가 고객과의 이전 상호작용을 기억하고 컨텍스트를 유지할 수 있도록 합니다. AgentCore Gateway를 사용하여 CRM, 주문 관리, 티켓팅 시스템을 MCP 호환 도구로 노출하면, 에이전트가 표준화된 인터페이스를 통해 이러한 시스템에 액세스할 수 있습니다. AgentCore Identity는 인증을 처리하여 에이전트가 적절한 권한으로 이러한 시스템에 액세스하도록 합니다. AgentCore Observability는 각 단계의 에이전트 동작에 대한 가시성을 제공하여 문제를 디버그하고 성능을 최적화할 수 있습니다.
1.2. AgentCore Runtime의 주요 특징
AgentCore Runtime는 프레임워크 및 에이전트 코드는 그대로 두고, 운영 필수 역량만 런타임이 제공하는 모델을 취함으로써 이식성과 운영 민첩성을 동시에 확보하는 서버리스 런타임입니다. 전통적인 서버리스 플랫폼과 달리, AgentCore는 에이전트 워크로드를 위해 특별히 구축되었으며, 아래의 대표적인 특징이 있습니다.
- 프레임워크 독립성 (Framework agnostic) 및 모델 유연성 (Model flexibility): LangGraph, CrewAI, Strands Agents, LlamaIndex 등 어떤 에이전트 프레임워크를 사용하든, 몇 줄의 코드 수정만으로 에이전트를 빠르게 AgentCore에 배포할 수 있습니다. 이 프레임워크 독립성은 모델 유연성으로도 확장됩니다. Amazon Bedrock의 모델이든, Anthropic Claude, OpenAI, Google Gemini 등 외부 모델이든 모두 작동합니다. 특정 에이전트 프레임워크나 모델 제공자에 종속되지 않으므로, 기술이 발전함에 따라 유연성을 유지할 수 있습니다.
- 세션 격리 (Session isolation): AgentCore의 가장 중요한 기능 중 하나입니다. 각 사용자 세션은 전용 CPU, 메모리, 파일 시스템 리소스를 가진 격리된 Firecracker 기반 microVM에서 실행됩니다. 이는 세션 간 완전한 분리를 보장하여, 상태를 유지하는 에이전트 추론 프로세스를 보호하고 세션 간 데이터 오염을 방지합니다. 이 수준의 격리는 엔터프라이즈 보안에 매우 중요하며, 특히 AI 프로세스의 비결정적(non-deterministic) 특성을 고려할 때 더욱 그렇습니다.
- 확장된 실행 시간 (Extended execution time): 전통적인 서버리스 플랫폼은 짧은 실행 시간을 위해 최적화되었지만, AgentCore는 실시간 상호 시간은 물론 최대 8시간까지의 장기 실행 워크로드를 지원합니다. 이는 업계 최고 수준의 비동기 워크로드 지원으로, 복잡한 에이전트 추론, 멀티 에이전트 협업, 장기간 문제 해결 세션을 가능하게 합니다. 8시간 윈도우는 실시간 상호작용과 백그라운드 처리를 모두 지원하여, 개발자가 에이전트 아키텍처에서 워크로드 특성에 대해 타협할 필요가 없습니다.
- 향상된 페이로드 처리: 100MB 페이로드를 처리할 수 있어 텍스트, 이미지, 오디오, 비디오와 같은 여러 모달리티의 원활한 처리가 가능하며, 이는 문서 분석, 이미지 처리, 비디오 이해 등의 에이전트 애플리케이션에 매우 중요합니다. 대규모 페이로드 지원은 별도의 스토리지 시스템을 관리하지 않고도 풍부하고 멀티모달한 에이전트 경험을 구축할 수 있음을 의미하기 때문입니다.
- 내장 인증 (Built-in authentication): AgentCore Runtime은 AgentCore Identity와 통합되어 AI 에이전트에 고유한 ID를 할당하고 Okta, Microsoft Entra ID, Amazon Cognito와 같은 엔터프라이즈 신원 제공자와 원활하게 통합됩니다. 이는 사용자가 액세스 권한이 있는 에이전트에만 인증할 수 있고, 에이전트가 적절한 권한으로 외부 서비스에 액세스할 수 있도록 합니다. 이 내장된 신원 지원은 처음부터 복잡한 인증 시스템을 구축하는 데 몇 주를 절약합니다.
- 빠른 콜드 스타트: AgentCore는 200밀리초의 시작 시간을 제공하여, 에이전트가 빠르게 응답하고 사용자가 인프라 초기화를 기다리지 않도록 합니다. 세션이 5분 동안 유휴 상태이면 일시 중단되지만 애플리케이션 상태, 파일 시스템, 환경 변수는 유지됩니다. 이를 통해 리소스 효율성과 빠른 재개 시간 사이의 균형을 맞춥니다. 15분의 세션 타임아웃과 8시간의 최대 세션 지속 시간은 다양한 사용 패턴을 수용합니다.
- 소비 기반 가격 책정: 미리 리소스를 선택해야 하는 할당 기반 모델과 달리, AgentCore는 필요한 것을 동적으로 프로비저닝하고 실제로 소비된 리소스에 대해서만 과금합니다. 이는 용량 계획의 부담을 제거하고 예측할 수 없는 에이전트 워크로드에 대한 비용 효율성을 보장합니다. 초기 트래픽이 낮은 신규 에이전트 애플리케이션의 경우, 과도하게 프로비저닝된 인프라에 대해 비용을 지불하지 않습니다.
- 프로토콜 지원 (Protocol support): 에이전트가 MCP(Model Context Protocol) 나 A2A(Agent-to-Agent)를 통해 다른 에이전트 및 도구와 통신할 수 있습니다. 이에 대해서 다음 절에서 자세히 알아봅니다.
1.3. AgentCore Runtime이 지원하는 프로토콜: HTTP, MCP, A2A
AgentCore Runtime의 진정한 강점 중 하나는 여러 통신 프로토콜을 지원하여, 개발자가 자신의 사용 사례에 가장 적합한 프로토콜을 선택할 수 있다는 것입니다. 각 프로토콜은 서로 다른 목적을 제공하며, AgentCore는 이를 모두 동일한 통합 플랫폼을 통해 지원합니다.
HTTP 프로토콜
HTTP 프로토콜은 전통적인 요청-응답 패턴을 위한 직접적인 REST API 엔드포인트를 제공합니다. AgentCore Runtime에서 HTTP 프로토콜을 사용하는 에이전트는 포트 8080의 0.0.0.0 호스트에서 실행되며 /invocations 과 /ping의 두 가지 주요 엔드포인트를 구현해야 합니다.
/ping: 에이전트가 작동하고 요청을 처리할 준비가 되었는지 확인합니다. 서비스 모니터링, AWS의 관리형 인프라를 통한 자동 복구에 사용되며, HTTP 상태 코드 200으로 상태를 반환합니다. 에이전트가 백그라운드 작업을 처리해야 하는 경우,HealthyBusy상태로 표시하여 런타임 세션이 활성 상태로 간주되도록 할 수 있습니다./invocations: 주요 에이전트 상호작용 지점으로, JSON 입력을 받고 JSON 또는 Server-Sent Events(SSE) 출력을 반환합니다. 이 엔드포인트는 사용자나 애플리케이션에서 들어오는 요청을 받아 에이전트의 비즈니스 로직을 통해 처리합니다. 직접적인 사용자 상호작용과 대화, 외부 시스템과의 API 통합, 여러 요청의 배치 처리, 장기 실행 작업을 위한 실시간 스트리밍 응답에 이상적입니다.
MCP 프로토콜: 도구와의 표준화된 통합
MCP(Model Context Protocol)은 AI 모델이 외부 도구 및 데이터 소스와 상호작용하는 방식을 표준화하기 위해 앤쓰로픽(Anthropic)이 개발한 오픈 프로토콜입니다. AgentCore Runtime의 MCP 지원은 에이전트가 파일 시스템, 데이터베이스, API 등 외부 리소스에 접근할 수 있게 합니다. 이는 단일 에이전트가 여러 도구를 호출하는 중앙집중형 아키텍처를 따릅니다.
MCP 서버는 포트 8000의 /mcp 경로에서 실행되며, AgentCore는 이를 투명한 프록시로 처리합니다. InvokeAgentRuntime API의 페이로드는 수정 없이 직접 전달되므로, 표준 MCP RPC 메시지가 원활하게 작동합니다. 이 투명성은 MCP 서버가 표준 MCP SDK 및 도구와 호환되도록 유지하면서도 AgentCore의 엔터프라이즈 기능을 활용할 수 있음을 의미합니다.
멀티 스텝 에이전트 워크플로우는 MCP의 이점을 잘 활용할 수 있는 유스케이스입니다. 에이전트가 복잡한 작업을 수행할 때 종종 여러 도구를 순서대로 호출해야 합니다. MCP의 세션 관리 기능은 이러한 멀티 스텝 워크플로우를 지원하여, 에이전트가 여러 도구 호출에 걸쳐 컨텍스트를 유지할 수 있도록 합니다. AgentCore는 플랫폼이 세션 격리를 위해 자동으로 Mcp-Session-Id 헤더를 추가하여 각 에이전트 세션이 독립적으로 유지되도록 합니다. AgentCore의 MCP는 stateless streamable-HTTP로 AWS의 세션 관리 및 로드 밸런싱과의 호환성을 보장합니다. 서버는 플랫폼에서 생성한 Mcp-Session-Id 헤더를 거부하지 않아야 하며, 이를 통해 AgentCore가 여러 MCP 서버 인스턴스에 걸쳐 세션을 관리할 수 있습니다. 이 stateless 설계는 확장성에 매우 중요하며, 추가 조정 없이 수천 개의 동시 세션을 처리할 수 있도록 합니다.
A2A 프로토콜: 에이전트 간 협업
A2A(Agent-to-Agent)는 여러 AI 에이전트가 서로 통신하고 협업할 수 있도록 하는 오픈 표준입니다. HTTP가 전통적인 통합을 위한 것이고 MCP가 도구 액세스를 위한 것이라면, A2A는 특별히 에이전트 간 상호작용을 위해 설계되었습니다. 이는 에이전트를 단순히 도구가 아닌 협업하는 동료로 취급하는 것을 나타내며, AI 시스템 아키텍처의 근본적인 변화입니다.
AgentCore Runtime의 A2A 서버는 포트 9000의 루트 경로(/)에서 실행되며, InvokeAgentRuntime API의 JSON-RPC 페이로드가 수정 없이 A2A 컨테이너로 직접 전달됩니다. 이 아키텍처는 표준 A2A 프로토콜 기능을 보존하면서 엔터프라이즈 인증(SigV4/OAuth 2.0)과 확장성을 추가합니다.
AgentCore의 A2A 지원에는 엔터프라이즈급 보안 강화가 포함됩니다. 표준 A2A 프로토콜을 보존하면서도, AgentCore는 OAuth 2.0 및 SigV4를 통한 인증, 완전한 세션 격리, 포괄적인 로깅 및 관찰성을 추가합니다. 이는 조직이 오픈 표준의 상호운용성을 활용하면서도 엔터프라이즈 배포에 필요한 보안 및 거버넌스 제어를 유지할 수 있음을 의미합니다.
[표 1.] AgentCore Runtime 프로토콜 비교
중요한 것은 이러한 프로토콜이 상호 배타적이지 않다는 것입니다. AgentCore Runtime상에서의 에이전트 아키텍처는 여러 프로토콜을 사용할 수 있습니다. 예를 들어, HTTP를 통해 사용자 요청을 받는 에이전트는 MCP를 통해 도구에 액세스하고 A2A를 통해 다른 에이전트와 협업할 수 있습니다. 이 유연성을 통해 각 상호작용 유형에 가장 적합한 프로토콜을 사용하는 정교한 시스템을 구축할 수 있습니다.
2. 개발 단계
Amazon Bedrock AgentCore Runtime에 AI 에이전트를 배포하는 과정은 크게 3단계로 구성됩니다. 첫 번째 단계에서는 AgentCore SDK를 사용하여 에이전트를 서비스화하고, 두 번째 단계에서는 런타임 배포에 필요한 설정 파일을 생성하고, 세 번째 단계에서는 생성된 설정 파일을 사용하여 AWS 클라우드 환경에 배포합니다. 이 과정은 최소한의 코드 변경으로 로컬 개발 환경에서 개발한 프로토타입을 엔터프라이즈급 프로덕션 서비스로 전환할 수 있도록 설계되었습니다.
AgentCore Runtime의 가장 큰 장점은 프레임워크 독립성입니다. Strands Agents, LangGraph, CrewAI, LlamaIndex 등 어떤 에이전트 프레임워크를 사용하든, 동일한 배포 프로세스를 따를 수 있습니다. 또한 Amazon Bedrock 모델뿐만 아니라 Anthropic Claude, OpenAI, Google Gemini 등 외부 모델도 자유롭게 선택할 수 있습니다. 이러한 유연성은 개발자가 기술 스택에 종속되지 않고 비즈니스 요구사항에 가장 적합한 도구를 선택할 수 있게 합니다.
배포 프로세스는 AgentCore Starter Toolkit CLI 도구를 통해 단순화됩니다. 이 도구는 도메인 특화 Infrastructure-as-Code (IaC) 솔루션처럼 작동하며, 복잡한 AWS 인프라 설정을 자동화하여 개발자가 에이전트 로직에 집중할 수 있게 합니다. 도커 컨테이너 빌드, ECR 저장소 관리, IAM 역할 구성, CloudWatch 로깅 설정 등 수많은 인프라 작업이 몇 가지 간단한 명령어로 처리됩니다.
[그림 1.] AgentCore 개발 단계
2.1. Define – 에이전트 정의 및 서비스화
기존 에이전트 프레임워크(예: Strands Agents, LangGraph 등)로 개발한 로컬 에이전트가 안정적으로 작동하는 것을 확인한 후, 다음 단계는 AgentCore Runtime에 배포할 수 있도록 설정하는 것입니다. 이 과정은 AgentCore Python SDK를 사용하여 매우 간단하게 수행할 수 있으며, 기존 에이전트 코드를 거의 수정하지 않고도 HTTP 서비스로 변환할 수 있습니다. AgentCore SDK는 HTTP 서버 설정, 엔드포인트 라우팅, 요청 처리, 세션 관리 등의 복잡한 작업을 자동으로 처리합니다.
app = BedrockAgentCoreApp(): 이 애플리케이션 인스턴스는 에이전트의 컨테이너 애플리케이션을 나타내며, 모든 구성, 실행, 통합을 관리합니다. 애플리케이션 생성 시 디버그 모드를 활성화하려면BedrockAgentCoreApp(debug=True)와 같이 옵션을 전달할 수 있습니다. 디버그 모드는 개발 중에 더 상세한 로깅 정보를 제공하여 문제를 빠르게 파악할 수 있게 합니다.@app.entrypoint데코레이터 적용: 에이전트의 호출 함수에 이 데코레이터를 적용하면 해당 함수가 AgentCore Runtime의 진입점으로 지정되며, 들어오는 모든 요청이 이 함수를 통해 처리됩니다. 진입점 함수는 payload 파라미터를 받으며, 이는 사용자의 요청 데이터를 포함하는 JSON 객체입니다. 함수 내에서는 이 payload에서 필요한 정보를 추출하여 에이전트를 호출하고, 결과를 JSON 직렬화 가능한 형태로 반환해야 합니다.run(): AgentCore Runtime이 에이전트 실행을 제어하도록 합니다. 이 메서드는 에이전트를 HTTP 서버로 시작하며, Docker 환경에서 실행 중인지 로컬 환경에서 실행 중인지 자동으로 감지합니다. 로컬에서 실행하면 http://localhost:8080에서 서버가 시작되어, curl이나 Postman과 같은 도구로 테스트할 수 있습니다./invocations엔드포인트로 POST 요청을 보내면 에이전트가 처리한 응답을 받을 수 있고,/ping엔드포인트로 GET 요청을 보내면 에이전트의 상태를 확인할 수 있습니다.
2.2. Configure – 런타임 배포에 필요한 설정 파일 생성
에이전트 코드 완성 후, AWS 클라우드 환경에 배포하기 위한 설정 및 런칭 단계로 넘어갑니다. AgentCore Starter Toolkit CLI를 사용하여 복잡한 인프라 설정을 자동화하여 몇 가지 간단한 명령어로 쉽고 빠르게 배포를 수행할 수 있습니다.
AgentCore Configure를 통해 Runtime에 배포하기 위한 Dockerfile과 .bedrock_agentcore.yml 설정 파일을 생성합니다. 필수 인자는 아래와 같으며, 이 인자값들은 CLI로 인터랙티브하게 입력하거나 파이썬 API로 입력 가능합니다.
- AgentCore의 실행 롤 ARN: 지정하지 않으면 자동 생성됩니다.
- ECR의 ARN: 지정하지 않으면 자동 생성됩니다.
- txt (에이전트에서 사용할 라이브러리, AgentCore 관련 패키지)
- OAuth 인증 여부 설정
- No인 경우 IAM role 기반 권한으로만 접근합니다. (기본값)
- Yes인 경우 AWS CLI로 구성 시
--authorizer-config플래그를 통해 인증 정보를 제공하거나, 아래 코드 스니펫과 같이 파이썬 코드에서authorizer_configuration파라미터를 설정해야 합니다. 코드 스니펫은 아래와 같습니다.
from bedrock_agentcore_starter_toolkit import Runtime
from boto3.session import Session
boto_session = Session()
region = boto_session.region_name
agentcore_runtime = Runtime()
response = agentcore_runtime.configure(
entrypoint="strands_claude.py",
execution_role=agentcore_iam_role['Role']['Arn'],
auto_create_ecr=True,
requirements_file="requirements.txt",
region=region,
agent_name=agent_name,
# OAuth 인증
authorizer_configuration={
"customJWTAuthorizer": {
"discoveryUrl": discovery_url,
"allowedClients": [client_id]
}
}
)[코드 1.] AgentCore Configure 파이썬 API 호출 예시
Dockerfile은 에이전트 코드를 컨테이너화하는 방법을 정의하며, AgentCore Runtime의 요구사항에 맞게 최적화되어 있습니다.
FROM public.ecr.aws/docker/library/python:3.12-slim
WORKDIR /app
COPY requirements.txt requirements.txt
# Install from requirements file
RUN pip install -r requirements.txt
RUN pip install aws-opentelemetry-distro>=0.10.0
# Set AWS region environment variable
ENV AWS_REGION=us-east-1
ENV AWS_DEFAULT_REGION=us-east-1
# Signal that this is running in Docker for host binding logic
ENV DOCKER_CONTAINER=1
# Create non-root user
RUN useradd -m -u 1000 bedrock_agentcore
USER bedrock_agentcore
EXPOSE 8080
EXPOSE 8000
# Copy entire project (respecting .dockerignore)
COPY . .
# Use the full module path
# CMD ["opentelemetry-instrument", "python", "-m", "hello"]
# --disable-otel 옵션 활성화 시 (로컬 모드 테스트 시 권장)
CMD ["python", "-m", "hello"] [코드 2.] Dockerfile 예시
.bedrock_agentcore.yaml 파일은 AgentCore Runtime에 에이전트를 배포하기 위한 모든 구성 정보를 담고 있는 파일로, 배포 작업의 청사진 역할을 합니다. 이 파일에는 에이전트 이름, 진입점 파일 경로, 타겟 플랫폼 아키텍처(linux/arm64), AWS 리전, 네트워크 구성 모드(PUBLIC/VPC), 실행 역할(execution_role) ARN, ECR 저장소 정보, 메모리 설정(단기/장기), 옵저버빌리티 활성화 여부, 프로토콜 선택(HTTP/MCP/A2A) 등 배포에 필요한 모든 파라미터가 YAML 형식으로 저장됩니다. *_auto_create: true 플래그가 설정된 리소스(실행 역할, ECR 저장소)은 배포 시 자동으로 생성되며, null 값으로 표시된 리소스는 배포 과정에서 자동 프로비저닝됩니다.
default_agent: strands_claude_getting_started
agents:
strands_claude_getting_started:
name: strands_claude_getting_started
entrypoint: strands_claude.py
platform: linux/arm64
container_runtime: docker
aws:
execution_role: [YOUR-ROLE[
execution_role_auto_create: false
account: [YOUR-AWS-ACCOUNT]
region: [YOUR-REGION]
ecr_repository: [YOUR-ECR-REPO]
ecr_auto_create: false
network_configuration:
network_mode: PUBLIC
protocol_configuration:
server_protocol: HTTP
observability:
enabled: true
bedrock_agentcore:
agent_id: strands_claude_getting_started-1CDrNa9UK0
agent_arn: xxxxx
agent_session_id: 0963884c-f046-4246-b2eb-e2b05c65f096
codebuild:
project_name: bedrock-agentcore-strands_claude_getting_started-builder
execution_role: [YOUR-ROLE]
source_bucket: bedrock-agentcore-codebuild-sources-xxxxxxxxxxxx-[YOUR-REGION]
authorizer_configuration: null
oauth_configuration: null[코드 3.] .bedrock_agentcore.yaml 예시
2.3. Launch
모든 설정이 완료되면, agentcore launch 명령어를 사용하여 에이전트를 AWS에 배포합니다. 이 명령어는 여러 단계를 자동으로 수행합니다.
첫째, 에이전트 코드로 도커 이미지를 빌드합니다. 이 과정은 기본적으로 AWS CodeBuild에서 실행되므로, 로컬에 도커를 설치할 필요가 없습니다. --code-build 플래그를 명시적으로 사용하면 CodeBuild를 통한 빌드를 강제하고, --local-build 플래그를 사용하면 로컬 Docker로 빌드합니다. CodeBuild를 사용하는 것이 권장되는데, 이는 일관된 빌드 환경을 보장하고 ARM64 아키텍처 이미지를 올바르게 생성하기 때문입니다. 둘째, 빌드된 이미지를 Amazon ECR에 푸시합니다. ECR은 AWS의 완전 관리형 도커 컨테이너 레지스트리로, 이미지의 안전한 저장과 버전 관리를 제공합니다. 각 배포마다 새로운 이미지 태그가 생성되어, 필요시 이전 버전으로 쉽게 롤백할 수 있습니다. 셋째, Bedrock AgentCore 런타임을 생성합니다. 이는 에이전트를 호스팅할 서버리스 환경을 프로비저닝하며, 완전한 세션 격리, 자동 스케일링, 로드 밸런싱을 제공합니다. 넷째, 클라우드에 에이전트를 배포합니다. AgentCore Runtime은 ECR에서 이미지를 가져와서 실행 가능한 컨테이너를 시작합니다. 이 과정에서 구성된 IAM 역할, 네트워크 설정, 인증 구성이 모두 적용됩니다. 다섯째, CloudWatch Log 그룹이 자동으로 구성되어, 에이전트의 로그를 즉시 모니터링할 수 있습니다. 로그는 디버깅, 성능 분석, 감사에 필수적이며, AgentCore Observability와 통합되어 상세한 추적 및 메트릭을 제공합니다.
배포가 완료되면 두 가지 중요한 정보가 출력됩니다. 첫째, 에이전트의 ARN(Amazon Resource Name)이 제공되며, 이는 InvokeAgentRuntime API로 에이전트를 호출할 때 필요합니다. ARN은 에이전트의 고유 식별자이며, AWS SDK를 통한 프로그래매틱 액세스에 사용됩니다. 둘째, CloudWatch Logs의 로그 위치가 제공되어, AWS 콘솔이나 CLI를 통해 에이전트의 실행 로그를 확인할 수 있습니다.
로컬 테스트 옵션
프로덕션 배포 전에 로컬에서 에이전트를 테스트하고 싶다면, agentcore launch --local 명령어를 사용할 수 있습니다. 이 옵션은 Docker, Finch, 또는 Podman과 같은 컨테이너 엔진이 로컬에 설치되어 있어야 합니다. 로컬 배포는 Docker 이미지를 빌드하고, 로컬에서 컨테이너를 실행하며, http://localhost:8080에서 서버를 시작합니다. 이를 통해 클라우드 리소스를 사용하지 않고도 배포 구성이 올바른지 확인할 수 있습니다.
로컬 테스트는 반복적인 개발 과정에서 매우 유용합니다. 코드를 수정할 때마다 클라우드에 배포하는 것은 시간이 오래 걸리고 비용이 발생할 수 있습니다. 로컬 테스트를 통해 빠르게 변경사항을 검증하고, 문제를 조기에 발견하며, 프로덕션 환경과 동일한 컨테이너 환경에서 테스트할 수 있습니다. 로컬 테스트가 성공적으로 완료되면, agentcore launch 명령어로 동일한 이미지를 클라우드에 배포하여 일관성을 보장할 수 있습니다.
버전 관리 및 롤백
AgentCore Runtime은 버전 관리 시스템을 제공합니다. 런타임을 처음 생성하면 버전 1이 자동으로 생성됩니다. 이후 컨테이너 이미지, 프로토콜 설정, 네트워크 설정 등 구성이 업데이트될 때마다 새로운 버전이 생성됩니다. 각 버전은 해당 시점의 완전한 구성 스냅샷을 포함하므로, 필요시 이전 버전으로 쉽게 롤백할 수 있습니다. 이는 배포 히스토리를 제공하고 안전한 배포 전략을 가능하게 합니다.
버전 관리는 카나리 배포나 블루-그린 배포와 같은 고급 배포 전략을 구현하는 데도 유용합니다. 새 버전을 일부 트래픽에만 노출하여 테스트하고, 문제가 없으면 점진적으로 트래픽을 전환할 수 있습니다. 만약 새 버전에 문제가 발견되면, 이전 안정 버전으로 즉시 롤백하여 서비스 중단을 최소화할 수 있습니다. 이러한 운영 유연성은 프로덕션 환경에서 에이전트를 안정적으로 운영하는 데 필수적입니다.
[그림 2.] AgentCore Runtime 엔드포인트 버전 관리 예시
2.4. Invoke
에이전트가 성공적으로 배포되면, invoke 메서드로 에이전트를 쉽게 호출할 수 있습니다. AgentCore Starter Toolkit은 간단한 테스트를 위한 CLI 명령어(agentcore invoke)를 제공하며, 배포 직후에는 agentcore status 명령어로 모든 리소스(특히 메모리가 구성된 경우)가 프로비저닝되고 준비되었는지 확인하는 것이 좋습니다.
invoke_response = agentcore_runtime.invoke({"prompt": "How is the weather now?"})
또한 Cognito 등으로 인증을 수행하도록 설정된 경우에는, --bearer-token으로 액세스 토큰을 설정할 수도 있습니다.
AgentCore Runtime의 MicroVM 격리 환경
AgentCore Runtime은 각 사용자 세션마다 전용 MicroVM(마이크로 가상 머신)을 제공하여 완전한 실행 환경 격리를 구현합니다. 각 MicroVM은 독립된 CPU, 메모리, 파일시스템 리소스를 가지며, 한 사용자의 에이전트가 다른 사용자의 데이터에 절대 접근할 수 없도록 보장합니다. 세션이 완료되면 전체 MicroVM이 종료되고 메모리가 완전히 정화(sanitized)되어 모든 세션 데이터가 제거되므로, 세션 간 데이터 오염 위험이 완전히 제거됩니다.
AgentCore Runtime의 세션은 애플리케이션에서 제공하는 고유한 runtimeSessionId로 첫 호출 시 생성되며, AgentCore Runtime은 각 세션에 대해 전용 실행 환경(MicroVM)을 프로비저닝합니다. 세션은 동일한 runtimeSessionId에 대한 호출 간에 컨텍스트를 보존하며, 대화 히스토리, 사용자 선호도, 중간 계산 결과 등 에이전트가 유지하는 모든 상태 정보가 세션 기간 동안 저장됩니다. 세션 상태는 Active(동기 요청 처리 중 또는 백그라운드 작업 수행 중), Idle(요청 처리 완료 후 대기 중), Terminated(15분 비활성 시간, 8시간 최대 지속 시간 도달, 또는 헬스 체크 실패로 인한 종료)의 세 가지로 구분됩니다.
세션이 종료된 후 동일한 runtimeSessionId로 후속 요청이 들어오면 새로운 실행 환경이 생성되며, 세션 격리는 세션 간 데이터 오염을 방지하고 보안을 보장합니다. 하지만 세션 기간을 넘어 보존되어야 하는 데이터(대화 히스토리, 학습된 선호도, 중요한 인사이트)는 AgentCore Memory를 사용해야 합니다. AgentCore Memory는 에이전트 워크로드를 위해 특별히 설계된 지속적인 저장소를 제공하며, 단기 및 장기 메모리 기능을 모두 제공합니다. 보다 자세한 내용은 AgentCore Memory 블로그를 참조하기 바랍니다.
세션 기반 테스트를 위해서는 --session-id 플래그를 사용할 수 있습니다. 예를 들어, agentcore invoke '{"prompt": "Remember this"}' --session-id "test"는 특정 세션 ID로 요청을 보냅니다. 같은 세션 ID로 후속 요청을 보내면 에이전트가 이전 컨텍스트를 기억하는지 확인할 수 있습니다.
[그림 3.] AgentCore Runtime 호출 플로우 및 MicroVM 세션 격리
배포 후 운영 및 모니터링
에이전트가 프로덕션에 배포되면 지속적인 모니터링과 운영이 필요합니다. AgentCore Observability는 CloudWatch와 통합되어 에이전트의 실행 상태, 성능 메트릭, 에러 로그를 실시간으로 제공합니다. CloudWatch 대시보드에서 요청 수, 응답 시간, 에러율, 도구 호출 빈도 등을 추적할 수 있습니다. OpenTelemetry 호환성을 통해 LangSmith, Langfuse와 같은 외부 옵저버빌리티 플랫폼과도 통합할 수 있습니다.
에이전트의 추적(tracing)은 복잡한 워크플로우를 이해하는 데 필수적입니다. AgentCore는 각 요청의 전체 수명 주기를 추적하여, 에이전트가 어떤 도구를 호출했는지, 각 단계에 얼마나 시간이 걸렸는지, 어디서 에러가 발생했는지 보여줍니다. 이러한 상세한 가시성은 성능 병목 현상을 식별하고, 에이전트 동작을 디버그하며, 사용자 경험을 최적화하는 데 도움이 됩니다.
3. AWS CLI with Starter Toolkit로 빠르게 시작하기
3.1. 준비
uv나 pip로 AgentCore 패키지를 설치합니다.
uv add bedrock-agentcore bedrock-agentcore-starter-toolkit
# pip install bedrock-agentcore bedrock-agentcore-starter-toolkit
다음 구조로 프로젝트 폴더를 생성하는 것이 베이스라인입니다.
## 프로젝트 폴더 구조
your_project_directory/
├─ hello.py # 주요 에이전트 코드
├─ requirements.txt
└─ __init__.py # 디렉토리를 Python 패키지로 만듬hello.py 예시: 이제 실제 AI 에이전트를 구현합니다. 아래 예시에서는 Strands Agent로 구현하였지만, LangGraph/CrewAI 등 여러분이 선호하는 에이전트 프레임워크를 자유롭게 사용하시면 됩니다. 간단한 예제부터 시작하여 점진적으로 기능을 추가해 보세요.
# BedrockAgentCoreApp: AgentCore Runtime과의 통합을 처리하는 핵심 래퍼 클래스로
# HTTP 서버 설정, 엔드포인트 라우팅, 요청 처리, 세션 관리를 자동으로 처리합니다.
from bedrock_agentcore.runtime import BedrockAgentCoreApp
from strands import Agent
agent = Agent()
app = BedrockAgentCoreApp()
# 엔트리포인트 데코레이터 추가
@app.entrypoint
def invoke(payload):
"""Process user input and return a response"""
user_message = payload.get("prompt", "Hello")
response = agent(user_message)
return str(response)
if __name__ == "__main__":
app.run()requirements.txt: 프로젝트의 의존성을 명시하는 requirements.txt 파일을 생성합니다.
AgentCore Configure로 에이전트 배포를 준비합니다.
agentcore configure --entrypoint agent_example.py -er <YOUR_IAM_ROLE_ARN> --region us-east-1
Agent name: strands_claude
🔐 Execution Role
Press Enter to auto-create execution role, or provide execution role ARN/name to use existing
Previously configured: arn:aws:iam::xxxxxxxxxxxx:role/AmazonBedrockAgentCoreSDKRuntime-us-east-1-xxxxxxxxx
Execution role ARN/name (or press Enter to auto-create):
✓ Will auto-create execution role
🏗️ ECR Repository
Press Enter to auto-create ECR repository, or provide ECR Repository URI to use existing
Previously configured: xxxxxxxxxxxx.dkr.ecr.us-east-1.amazonaws.com/bedrock-agentcore-strands_claude_getting_started
ECR Repository URI (or press Enter to auto-create):
✓ Will auto-create ECR repository
🔍 Detected dependency file: requirements.txt
Press Enter to use this file, or type a different path (use Tab for autocomplete):
Path or Press Enter to use detected dependency file:
✓ Using detected file: requirements.txt
🔐 Authorization Configuration
By default, Bedrock AgentCore uses IAM authorization.
Configure OAuth authorizer instead? (yes/no) [no]:
[그림 4.] AgentCore Configure 결과 화면 예시
3.2. 에이전트 테스트 및 배포
로컬 모드 배포 (uv run agentcore launch -l)
-l 옵션을 붙이면 컨테이너를 로컬에서 실행하여 테스트할 수 있으며, 로컬 모드 배포는 아래의 과정을 수행합니다.
- Docker 이미지 빌드
- 로컬에서 컨테이너 실행
- http://localhost:8080 에서 서버 시작
AgentCore 런타임 배포 (uv run agentcore launch)
AgentCore 런타임 배포는 아래의 과정을 수행합니다.
- 에이전트 코드로 Docker 이미지 빌드
- Amazon ECR에 이미지 푸시
- Bedrock AgentCore 런타임 생성
- 클라우드에 에이전트 배포
[그림 5.] AgentCore Runtime 배포 예시
3.3. 에이전트 테스트
# 로컬 배포 이후
agentcore invoke -l '{"prompt": "Hello"}'
# 클라우드 배포 이후
agentcore invoke '{"prompt": "Hello"}'
[그림 6.] AgentCore Runtime 로컬 환경 배포 후 invoke 결과
[그림 7.] AgentCore Runtime 엔드포인트 배포 후 invoke 결과
AWS 공식 예제를 통해 보다 많은 핸즈온을 수행해보실 수 있습니다.
4. Starter Toolkit 없이 FastAPI 기반으로 구현하여 배포하기
AgentCore Starter Toolkit 없이도 AgentCore Runtime 에이전트를 생성하고 배포할 수 있습니다. AWS의 공식 가이드는 FastAPI 기반의 /invocations POST 엔드포인트와 /ping GET 엔드포인트를 구현하는 방법을 소개하고 있습니다.
FastAPI 코드 예시
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import Dict, Any
from datetime import datetime
from strands import Agent
app = FastAPI(title="Strands Agent Server", version="1.0.0")
# Strands agent 초기화
strands_agent = Agent()
class InvocationRequest(BaseModel):
input: Dict[str, Any]
class InvocationResponse(BaseModel):
output: Dict[str, Any]
@app.post("/invocations", response_model=InvocationResponse)
async def invoke_agent(request: InvocationRequest):
try:
user_message = request.input.get("prompt", "")
if not user_message:
raise HTTPException(
status_code=400,
detail="No prompt found in input. Please provide a 'prompt' key in the input."
)
result = strands_agent(user_message)
response = {
"message": result.message,
"timestamp": datetime.utcnow().isoformat(),
"model": "strands-agent",
}
return InvocationResponse(output=response)
except Exception as e:
raise HTTPException(status_code=500, detail=f"Agent processing failed: {str(e)}")
@app.get("/ping")
async def ping():
return {"status": "healthy"}
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=8080)FastAPI 구동
uv run uvicorn agent:app --host 0.0.0.0 --port 8080
/ping 엔드포인트 및 /invocations 엔드포인트 테스트
curl http://localhost:8080/ping && \
curl -X POST <http://localhost:8080/invocations> \\
-H "Content-Type: application/json" \\
-d '{
"input": {"prompt": "What is artificial intelligence?"}
}'
[그림 8]. 로컬 개발 환경의 엔드포인트 테스트
테스트를 완료하였으면 Dockerfile을 생성합니다. 베이스 이미지가 ARM64 기반이어야 합니다.
도커 빌드
docker buildx build --platform linux/arm64 -t my-agent:arm64 --load .
로컬 환경에서 도커 테스트
docker run --platform linux/arm64 -p 8080:8080 \\
-e AWS_ACCESS_KEY_ID="$AWS_ACCESS_KEY_ID" \\
-e AWS_SECRET_ACCESS_KEY="$AWS_SECRET_ACCESS_KEY" \\
-e AWS_SESSION_TOKEN="$AWS_SESSION_TOKEN" \\
-e AWS_REGION="$AWS_REGION" \\
my-agent:arm64이후에는 3절과 동일한 과정으로 ECR에 push하고 AgentCore에 배포하면 됩니다.
5. 결론
본 가이드를 통해 Amazon Bedrock AgentCore Rutime을 사용하여 AI 에이전트를 성공적으로 배포하는 방법을 배웠습니다. AgentCore Runtime과 Starter Toolkit의 조합은 프로토타입에서 프로덕션까지의 여정을 크게 단순화하여, 조직이 AI 에이전트를 실제 비즈니스 가치를 창출하는 시스템으로 빠르게 전환할 수 있도록 합니다. 보다 자세한 내용을 원하면 저자가 직접 준비한 강연 영상을 통해 파악하시는 것을 권장드립니다. 이제 여러분의 혁신적인 AI 에이전트를 구축하고 배포할 준비가 되었습니다. 행운을 빕니다!