AgentCore Runtime

AgentCore Runtime

AI 에이전트 코드를 프로덕션에서 실행하는 관리형 환경

왜 에이전트 전용 실행 환경인가

챗봇은 요청 1회로 끝, 에이전트는 수 분에서 수 시간의 멀티스텝 루프

세션 1개 = MicroVM 1개

User → Endpoint → MicroVM 격리 세션 → Tools·Bedrock 연동 — 세션마다 VM 하나씩, 대화가 섞일 수 없는 구조

확장의 단위는 세션 수

세션이 생기면 MicroVM이 늘고, 세션이 끝나면 0으로 — 쿼터도 세션 단위

콜드 스타트와 웜 — 세션 재사용

콜드의 대부분은 VM이 아니라 코드·이미지 로드에서 발생

배포 경로

로컬에서 검증한 코드가 그대로 프로덕션으로

에이전트 코드의 배포 계약

Strands든 LangGraph든 — 진입점 하나만 지키면 Runtime에 배포 가능

핵심 포인트

BedrockAgentCoreApp

HTTP 엔드포인트를 자동 관리하는 런타임 래퍼 — 서버 코드 불필요

@app.entrypoint

사용자 요청이 라우팅되는 진입점 함수 — payload를 받아 결과 반환

payload["prompt"]

호출 측이 보낸 JSON — invoke 시 넘긴 프롬프트가 담김

requirements.txt

의존성 목록 — 배포 시 자동 설치, 인프라 코드는 0줄

코드

from bedrock_agentcore import BedrockAgentCoreApp
from strands import Agent, tool

# 런타임 래퍼 — HTTP 엔드포인트를 자동 관리
app = BedrockAgentCoreApp()

@tool
def search_menu(query: str) -> str:
    """식당 메뉴를 검색합니다."""
    return f"'{query}' 검색 결과: 파스타 35,000원"

# 사용자 요청이 이 함수로 라우팅되는 진입점
@app.entrypoint
def my_agent(payload):
    agent = Agent(tools=[search_menu])
    result = agent(payload.get("prompt"))
    return {"result": result.message}

CLI 파이프라인 — create · dev · deploy · invoke

네 명령으로 이어지는 로컬 개발부터 프로덕션 호출까지

IaC로 굳히기 — CDK L2 Constructs

CLI도 결국 CDK로 스택 생성 — 팀 파이프라인이라면 처음부터 CDK L2

선언적 대안 — Managed Harness

코드를 배포하는 Runtime, 구성을 선언하는 Harness — 갈림길은 커스텀 로직의 유무

호출 인터페이스

배포된 에이전트를 부르는 데이터 플레인 API

프로토콜 3종 — create 시점의 선언

에이전트 로직은 그대로 — 바뀌는 것은 노출 방식뿐

InvokeAgentRuntime — boto3로 호출

이미 배포된 에이전트를 다른 서비스에서 호출할 때 — Lambda·Step Functions의 한 스텝으로도

핵심 포인트

agentRuntimeArn

배포된 에이전트의 ARN — 어느 에이전트를 부를지

runtimeSessionId

세션 식별자 (33자 이상, UUID 권장) — 같은 ID면 같은 MicroVM

qualifier

호출할 버전 — DEFAULT는 최신 배포를 가리킴

response

청크 단위 스트리밍 — 모아서 디코딩

코드

import boto3, json, uuid

# 데이터 플레인 클라이언트 — 호출 전용 (리소스 관리는 -control)
client = boto3.client("bedrock-agentcore", region_name="us-east-1")

# 에이전트 호출 — 세션 ID가 곧 MicroVM 격리 단위
response = client.invoke_agent_runtime(
    agentRuntimeArn="arn:aws:bedrock-agentcore:us-east-1:123456789012:runtime/MyAgent",
    runtimeSessionId=str(uuid.uuid4()),
    payload=json.dumps({"prompt": "최근 주문 상태 확인해줘"}).encode(),
    qualifier="DEFAULT",
)

# 스트리밍 응답 — 청크를 모아 디코딩
content = [chunk.decode("utf-8") for chunk in response.get("response", [])]
print(json.loads("".join(content)))

호출 모드와 시간 한도

에이전트가 오래 달릴수록 UX를 결정하는 스트리밍

양방향 스트리밍 — WebSocket

듣는 동시에 말하는 에이전트 — 음성·실시간 UI가 요구하는 진짜 양방향

InvokeAgentRuntimeWithWebsocketStream

전용 데이터 플레인 API — wss://bedrock-agentcore.{region}.amazonaws.com/runtimes/{arn}/ws

컨테이너 계약

8080 포트 /ws 경로 + /ping 헬스체크 — 같은 컨테이너가 InvokeAgentRuntime과 WebSocket을 동시 서빙

인증 3종

SigV4 헤더 · SigV4 pre-signed URL(브라우저 직결용) · OAuth 2.0

용도

음성 에이전트·인터럽트 처리 — 대화 중간에 끼어들어도 컨텍스트 유지

운영 축

배포가 끝난 뒤 남는 세 가지 관리 축

버전과 엔드포인트

배포의 기록과 호출의 진입점 — 분리되어 있어 가능한 운영

네트워크 — PUBLIC과 VPC

에이전트가 사내 DB·내부 API에 닿아야 하는 순간, 갈림길이 되는 네트워크 모드

세션을 넘는 파일 — BYO File System

세션이 끝나면 사라지는 MicroVM — 남길 파일은 외부 파일시스템을 세션 경로에 마운트

관측 연결 — 계측 코드 0줄

트레이스·메트릭·로그 자동 수집 — CloudWatch AI Operations에서 바로 조회

AWS/Bedrock-AgentCore

CloudWatch 메트릭 네임스페이스 — Invocations · Latency · Throttles · SystemErrors/UserErrors

ActiveSessionCount

활성 세션 수 (신규 메트릭) — 분당 1회, Service 차원 필터. 세션 쿼터 감시에 직결

GenAI Observability

콘솔 Assess > Observability → CloudWatch AI Operations — 세션·트레이스·토큰·에러율 대시보드

Unified span destination

스팬을 에이전트 자체 로그 그룹의 spans 스트림으로 수신 — UNIFIED_TRACES_DESTINATION_ENABLED, 2026-07-20부터 신규 에이전트 기본

agentcore logs

에이전트 로그를 CLI에서 바로 조회 — traces 명령으로 트레이스도 확인