본문으로 건너뛰기

LangGraph 에이전트의 AgentCore 단계별 이전

LangGraph 에이전트를 AgentCore Runtime·Gateway·Memory로 옮기고 Strands Agents로 계획 루프를 재구성하는 단계별 실습입니다.

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

TL;DR

노트북에서 동작하던 LangGraph 고객지원 에이전트는 실제 서비스에서 세션 격리, 상태 보존, 도구 인증, 운영체제 패치 같은 추론 외 부담을 직접 떠안습니다. 이 글은 Amazon Bedrock AgentCore Runtime, Gateway, Memory를 한 단계씩 붙여 기존 그래프와 동작을 유지한 채 10개 운영 부담 중 5개를 AWS 쪽으로 옮기는 Stage 1을 구현합니다. Stage 2에서는 Strands Agents로 라우터 기반 분기를 모델 기반 계획으로 바꾸고, AgentCore Policy의 Cedar 규칙으로 Gateway의 모든 도구 호출을 데이터 플레인에서 통제하지만 운영 부담 자체는 더 이동하지 않습니다. AgentCore harness로 코드 안의 루프까지 넘기는 Stage 3은 문서로만 다뤄졌으며, 각 단계는 같은 세 대화의 도구 실행과 최종 상태를 비교해 검증합니다.

섹션별 상세

01
노트북에서 실행되는 에이전트와 운영 환경의 에이전트 사이에는 추론 코드와 무관한 부담이 놓여 있습니다. 이 샘플은 VPC, WAF, IAM 정책, secrets rotation, OS 패치, 자동 확장, 세션 격리, checkpoint 저장, 도구 인증, dependency updates까지 10개 항목을 기준선으로 세고, LangGraph 고객지원 에이전트가 주문 조회와 반품 처리, FAQ 검색을 수행하는 흐름은 그대로 둡니다. 모델 호출은 처음부터 ChatBedrockConverse를 통해 Amazon Bedrock으로 향하므로, 이번 이전에서 바뀌는 핵심은 inference가 아니라 실행 환경과 상태·도구 운영입니다.
bash
git clone https://github.com/aws-samples/sample-migrate-agents-to-amazon-bedrock-agentcore.git
cd sample-migrate-agents-to-amazon-bedrock-agentcore
./setup.sh

마이그레이션 샘플 저장소를 복제하고 setup.sh로 가상 환경과 의존성을 설치합니다.

02
Stage 1은 기존 LangGraph 그래프를 다시 작성하지 않고 BedrockAgentCoreApp과 @app.entrypoint로 감싸 AgentCore Runtime에서 실행합니다. Runtime이 전달한 context.session_id를 graph.invoke의 thread_id로 연결하고, 소스와 vendored dependencies를 Amazon S3의 zip으로 묶어 CreateAgentRuntime에 전달하므로 container, Docker, Amazon ECR, load balancer, API Gateway가 필요하지 않습니다. OS patching, auto-scaling, session isolation이 Runtime으로 이동하고 같은 세 대화의 도구 실행과 최종 상태를 다시 비교한 결과, 10개 부담 중 5개가 AWS 쪽으로 이동하며 VPC configuration, WAF, IAM policies, secrets rotation, dependency updates는 여전히 팀의 책임입니다.
python
from bedrock_agentcore import BedrockAgentCoreApp
from langchain_core.messages import HumanMessage

app = BedrockAgentCoreApp()

@app.entrypoint
def agent_invocation(payload, context):
    state = support_graph().invoke(
        {"messages": [HumanMessage(payload.get("prompt", ""))]},
        config={"configurable": {"thread_id": context.session_id or "local-session"}},
    )
    return {"result": state["messages"][-1].text}

if __name__ == "__main__":
    app.run()

기존 LangGraph 실행 루프를 BedrockAgentCoreApp의 entrypoint로 감싸고 Runtime 세션 ID를 thread_id로 전달합니다.

python
client = boto3.client("bedrock-agentcore-control", region_name=region)
gateway = client.create_gateway(
    name="MigratedAgentGateway",
    roleArn=role_arn, # gateway execution role
    protocolType="MCP",
    authorizerType="AWS_IAM",
)
gateway_id = gateway["gatewayId"]
gateway_url = gateway["gatewayUrl"]

bedrock-agentcore-control 클라이언트로 MCP Gateway를 만들고 AWS_IAM 인증 방식을 지정합니다.

python
from langgraph_checkpoint_aws import AgentCoreMemorySaver
graph = build_graph(
    llm=llm,
    tools=tools,
    checkpointer=AgentCoreMemorySaver(memory_id, region_name=region),
)
state = graph.invoke(
    {"messages": [HumanMessage(prompt)]},
    config={"configurable": {"thread_id": session_id, "actor_id": actor_id}},
)

AgentCoreMemorySaver를 LangGraph checkpointer로 연결하고 호출별 actor_id와 thread_id를 전달합니다.

기존 에이전트에서 Runtime·Gateway·Memory를 적용하고 이후 Strands Agents로 계획 루프를 재구성하는 이전 흐름입니다.
DiagramStage 1은 기존 에이전트의 Runtime, 두 개 도구의 Gateway 이전, Memory 적용을 각각 검증하면서 10개 부담 중 5개를 AWS 쪽으로 옮깁니다. Stage 2는 운영 항목을 추가로 이동하지 않고 router 대신 모델이 계획하도록 바꾸며, 감사 가능한 분기를 잃는 비용을 함께 기록합니다.
Stage 1에서 기존 LangGraph 그래프를 AgentCore Runtime에 그대로 넣고 일부 도구와 대화 상태만 이전하는 아키텍처입니다.
Diagram배포 시에는 의존성을 포함한 zip을 Amazon S3에 올린 뒤 CreateAgentRuntime으로 Runtime을 만들고, 요청 시에는 클라이언트가 InvokeAgentRuntime을 직접 호출합니다. Runtime 내부의 LangGraph graph는 재작성하지 않으며, search_faq는 로컬에 남기고 lookup_order와 process_return은 SigV4 인증을 거쳐 AgentCore Gateway와 AWS Lambda를 통해 실행됩니다.
03
Stage 1에서는 세 도구 중 lookup_order와 process_return을 AgentCore Gateway의 MCP 도구로 게시하고 search_faq는 Runtime 내부 Python 함수로 남깁니다. Gateway는 AWS_IAM으로 서명된 호출을 받아 AWS Lambda를 자체 실행 역할로 호출하며, Memory는 MemorySaver를 AgentCoreMemorySaver로 바꿔 actor_id와 session_id를 기준으로 여러 프로세스와 날짜에 걸친 대화 상태를 보존합니다. 샘플은 다른 프로세스가 이전에 보지 못한 주문에 답하는지 확인하고, Gateway 도구 이름과 인자까지 테스트해 단순한 응답 문구 비교보다 실제 실행 경로를 검증합니다.
python
config = AgentCoreMemoryConfig(
    memory_id=memory_id,
    session_id=session_id,
    actor_id=actor_id
)
kwargs["session_manager"] = AgentCoreMemorySessionManager(
    config,
    region_name=region_name
)
return Agent(**kwargs)

Strands Agent에 AgentCoreMemorySessionManager를 주입해 기존 Memory 저장소와 세션을 재사용합니다.

04
Stage 2는 운영 인프라를 더 옮기는 단계가 아니라 누가 다음 실행을 계획하는지 바꾸는 단계입니다. classify_intent와 route_intent가 Python에서 결정하던 분기를 Strands Agent의 model-driven planning으로 대체하고, AgentCoreMemorySessionManager가 Stage 1의 Memory 저장소와 세션 ID를 재사용하므로 Gateway, Lambda target, Memory는 그대로 활용합니다. 대신 결정적이고 감사 가능한 branch를 잃으며, 같은 IAM 정책을 가진 read-only role과 support-agent role을 두 도구에 각각 적용해 Cedar의 default-deny 동작으로 lookup_order는 허용되고 process_return은 거부되는 결과를 확인합니다.
Stage 2에서 router를 Strands Agent의 모델 기반 계획으로 바꾸고 Cedar를 모든 도구 호출에 적용하는 구조입니다.
DiagramAgentCoreMemorySessionManager는 Stage 1의 Memory 저장소를 재사용하지만, loop는 route_intent와 add_conditional_edges가 없는 Strands Agent로 재구성됩니다. 표의 두 caller와 두 tool 실험에서는 IAM 정책을 동일하게 유지한 채 read-only role의 process_return 호출만 거부해, permit 부재에 따른 Cedar의 default-deny 결과를 구분합니다.
05
Stage 3은 AgentCore harness가 model, system prompt, tools, memory, limits를 설정으로 받아 Strands Agents 루프를 실행하는 최종 이전 단계입니다. 이 단계에서 dependency updates가 추가로 이동해 10개 부담 중 6개가 AgentCore 쪽으로 가지만, secrets rotation은 Identity의 token refresh와 별개이므로 계속 팀의 책임입니다. 글에서는 Stage 3을 구현하거나 측정하지 않고 문서화만 했으며, 실제 도입 시에는 Stage 1을 안정적인 중단 지점으로 삼거나 손으로 작성한 라우팅이 한계가 된 경우 Stage 2를 선택하도록 안내합니다.
LangGraph 에이전트를 AgentCore로 옮기는 Stage 0부터 Stage 3까지의 운영 부담 이동과 계획 주체를 비교한 매트릭스입니다.
DiagramStage 0에서는 10개 운영 부담이 모두 팀 소유이고, Stage 1과 Stage 2에서는 OS patching, auto-scaling rules, session isolation, checkpoint storage, tool auth 등 5개가 AgentCore로 이동합니다. Stage 2에서는 운영 부담 수가 늘지 않고 model-driven planning으로 계획 주체만 모델로 바뀌며, Stage 3에서 dependency updates가 추가로 이동해 6개가 됩니다.

용어 해설

AgentCore Runtime
AgentCore Runtime은 에이전트 코드를 AWS 관리형 실행 환경에서 구동하는 서비스입니다. 요청마다 세션별 microVM을 사용해 세션 격리를 제공하고, 운영체제 패치와 자동 확장 부담을 줄입니다. 애플리케이션의 판단 로직 자체를 대체하지는 않습니다.
AgentCore Gateway
AgentCore Gateway는 에이전트가 호출하는 외부 도구를 MCP 기반 엔드포인트로 게시하고 인증과 실행 연결을 맡는 서비스입니다. 도구 권한을 애플리케이션 코드 밖으로 옮기며, AWS Lambda 같은 대상 함수를 자체 실행 역할로 호출합니다.
AgentCore Memory
AgentCore Memory는 프로세스 내부에 머물던 대화 상태를 여러 실행 인스턴스와 시간에 걸쳐 보존하는 저장소입니다. actor_id와 session_id를 기준으로 상태를 조회하므로 프로세스 재시작이나 복제 환경에서도 이전 대화를 이어갈 수 있습니다.
모델 기반 계획(Model-Driven Planning)
모델 기반 계획은 Python 코드에 고정한 분기 대신 모델이 다음 도구와 실행 단계를 선택하는 오케스트레이션 방식입니다. 새 의도마다 라우터와 노드를 추가하는 부담을 줄이지만, 결정 과정의 결정성과 감사 가능성을 낮추는 대가가 있습니다.
Cedar Policy
Cedar Policy는 AgentCore Gateway의 데이터 플레인에서 도구 호출마다 허용 여부를 판단하는 정책 체계입니다. 기본 거부 방식이므로 금지 규칙 없이도 일치하는 permit이 없으면 호출을 거부하며, IAM 권한과 별도로 도구별 접근 통제를 수행합니다.
Signature Version 4
Signature Version 4는 AWS API 요청을 자격 증명으로 서명하는 인증 방식입니다. 이 글의 에이전트는 IAM 자격 증명으로 Gateway 호출을 서명하고, Gateway는 별도의 실행 역할로 Lambda 도구를 호출해 외부 토큰 없이 요청 경로를 구성합니다.

기술

  • Amazon Bedrock AgentCore Runtime
  • AgentCore Gateway
  • AgentCore Memory
  • LangGraph
  • Strands Agents
  • ChatBedrockConverse
  • AWS Lambda
  • Amazon S3
  • Amazon ECR
  • Amazon CloudWatch
  • AWS Distro for OpenTelemetry
  • MCP
  • Signature Version 4
  • AWS_IAM
  • Cedar
  • AgentCore Identity
  • AgentCore Evaluations
  • Python 3.12

활용 사례

  • LangGraph 기반 고객지원 에이전트의 운영 환경 이전
  • 주문 상태 조회와 반품 처리를 수행하는 Stateful support agent
  • 여러 에이전트가 공유하는 MCP 도구 Gateway 구축
  • 대화 상태를 여러 프로세스와 날짜에 걸쳐 보존하는 에이전트
  • 도구별 호출 권한을 Cedar로 통제하는 에이전트
AI 분석 전체 내용 보기

AI 요약 · 북마크 · 개인 피드 설정 — 무료

출처 · 인용 안내

원문 발행 2026. 09. 04.수집 2026. 09. 04.출처 타입 RSS

인용 시 "요약 출처: AI Trends (aitrends.kr)"를 표기하고, 사실 확인은 원문 보기 기준으로 진행해 주세요. 자세한 기준은 운영 정책을 참고해 주세요.