단계 5: Runtime 생성

가상 환경 확인: 터미널에서 (.venv) 프롬프트가 보이는지 확인하세요. 보이지 않으면 다음을 실행하세요:

cd /workspace/workshop-module-1/agentcore-reference && source .venv/bin/activate

이 단계에서는 이전 단계에서 생성한 세 개의 타겟이 있는 게이트웨이와 Amazon Cognito를 통한 AgentCore Identity에 연결되는 AgentCore Runtime을 생성합니다.

AgentCore Runtime 생성

에이전트를 호스팅할 AgentCore Runtime을 생성합니다.

스크립트 수정 필요: 제공된 스크립트는 agentcore configure CLI와의 대화형(PTY) 입력 방식을 사용하여 타임아웃이 발생할 수 있습니다. 아래 패치를 먼저 실행하세요.

python3 << 'PATCH'
import re
f = 'scripts/agentcore_agent_runtime.py'
c = open(f).read()
if '--disable-memory' in c:
    print('Already patched')
else:
    c = re.sub(r",\n\s+'--authorizer-config',[^\n]+", "", c)
    c = c.replace("'--region', get_aws_region()\n        ]",
                   "'--region', get_aws_region(),\n            '--disable-memory'\n        ]")
    oauth = "f'\\n\\nyes\\n{oauth_discovery_url}\\n{oauth_client_id}\\n\\n\\n\\n' + 'no\\n' * 5"
    if 'run_with_pty' in c:
        s = c.index("        # Use pseudo-terminal")
        e = c.index("        result = run_with_pty(configure_cmd, oauth_input)") + len("        result = run_with_pty(configure_cmd, oauth_input)")
        c = c[:s] + f"        result = subprocess.run(configure_cmd, check=False, capture_output=True, text=True, timeout=600, shell=False, input={oauth})" + c[e:]
    elif "input='no\\n' * 10" in c:
        c = c.replace("input='no\\n' * 10", f"input={oauth}")
    open(f, 'w').write(c)
    print('Patched: PTY -> subprocess.run + --disable-memory')
PATCH

🔍 이 패치는 무엇을 변경하나요?

1. --disable-memory 옵션 추가 — 메모리 관련 대화형 프롬프트를 건너뜀

2. 불안정한 PTY(가상 터미널) 입력 방식을 안정적인 subprocess.run으로 교체

3. OAuth 인증 설정을 대화형 입력으로 전달 (yes → Discovery URL → Client ID 순서)

패치가 완료되면 Runtime을 생성합니다:

python3 scripts/agentcore_agent_runtime.py create \
  --name troubleshooting_agent_runtime

🔍 이 스크립트는 무엇을 하나요?

1. 에이전트 코드를 Docker 이미지로 빌드 (Dockerfile + agent.py + main.py)

2. AgentCore Runtime 리소스 생성 (Cognito Identity + Gateway 연결)

3. 에이전트가 서버리스 microVM에 배포되어 자동 스케일링

4. Runtime이 ACTIVE 상태가 될 때까지 대기

검증

콘솔 검증

AWS 콘솔에서 Amazon Bedrock AgentCore 서비스로 이동합니다. 왼쪽 패널에서 Agent Runtime을 클릭합니다. troubleshooting_agent_runtime이라는 이름의 에이전트가 생성되어 있어야 합니다. 이 런타임은 게이트웨이를 사용하여 타겟에 접근하고 Amazon Cognito를 통해 AgentCore Identity와 통합됩니다.

AgentCore Runtime

Runtime이 생성되면 에이전트 코드가 microVM 환경에 배포됩니다. 이 환경은 서버리스로 관리되며, 요청에 따라 자동으로 스케일링됩니다.

이 단계가 완료되었습니다. Next를 클릭하여 진행하세요.

코드 분석: 에이전트 런타임

TroubleshootingAgent 클래스 구조

class TroubleshootingAgent:
    def __init__(self, bearer_token, memory_hook=None,
                 bedrock_model_id="global.anthropic.claude-sonnet-4-20250514-v1:0",
                 system_prompt=None):
        # 1. BedrockModel 초기화
        self.model = BedrockModel(model_id=self.model_id)

        # 2. 시스템 프롬프트 설정 (아래 상세 분석)
        self.system_prompt = system_prompt if system_prompt else """..."""

        # 3. MCP 클라이언트로 Gateway 연결
        gateway_url = get_ssm_parameter("/app/troubleshooting/agentcore/gateway_url")
        self.gateway_client = MCPClient(
            lambda: streamablehttp_client(gateway_url, headers={"Authorization": f"Bearer {bearer_token}"})
        )
        self.gateway_client.start()
        mcp_tools = self.gateway_client.list_tools_sync()

        # 4. Strands Agent 생성
        self.agent = Agent(model=self.model, system_prompt=self.system_prompt, tools=self.tools)

시스템 프롬프트 핵심 구조

섹션	내용	목적
역할 정의	"You are a Troubleshooting Agent with DNS resolution, connectivity analysis, and CloudWatch monitoring capabilities"	에이전트 역할 범위 설정
AVAILABLE TOOLS	dns-resolve, connectivity, cloudwatch-monitoring 3개 도구 설명	LLM에게 사용 가능한 도구 안내
WORKFLOW	DNS → Connectivity → CloudWatch 순서별 워크플로우	도구 호출 순서 가이드
CRITICAL DATABASE CONNECTIVITY RULES	Source는 Instance ID, Database Destination은 IP, Port 3306	데이터베이스 연결 시 규칙
PERMISSION VALIDATION	action="fix" 전 반드시 사용자 동의 필요	안전장치
EXAMPLES	DNS+Connectivity, Database, Direct Instance 시나리오	Few-shot 예시
CRITICAL RULES	dns-resolve 선행, fix 시 동의 필수, 검증 필수	핵심 제약 조건

Dockerfile 분석

FROM ghcr.io/astral-sh/uv:python3.11-bookworm-slim  # UV 패키지 매니저 기반 이미지
ENV DOCKER_CONTAINER=1                                # 컨테이너 환경 플래그
EXPOSE 8080 8000                                      # AgentCore 런타임 포트
CMD ["opentelemetry-instrument", "python", "-m", "main"]  # OTel 계측 + 엔트리포인트

main.py 엔트리포인트

app = BedrockAgentCoreApp()

@app.entrypoint
async def invoke(payload, context):
    user_message = payload["prompt"]
    session_id = context.session_id
    # 비동기 태스크 생성 → 스트리밍 응답 반환

핵심 포인트: Agent 생성자에 model, system_prompt, tools 세 가지만 전달하면 에이전트가 완성됩니다. Strands Framework가 LLM과 도구 간의 재귀적 Event Loop를 자동으로 관리합니다.

이 시점의 아키텍처