에이전트형 AI 던전 게임

모듈 3: 스토리 에이전트 구현

주의

대상 리전에서 Strands 기본 모델에 대한 액세스가 활성화된 AWS 계정을 사용하세요. 이 가이드에 설명된 단계에 따라 Anthropic Claude Sonnet 4 모델을 설정하세요(작성 시점 기준).

스토리 에이전트는 Strands 에이전트로, Game과 컨텍스트용 Action 목록을 입력받아 스토리를 진행합니다. 인벤토리 MCP 서버와 상호작용하여 플레이어의 보유 아이템을 관리하도록 에이전트를 구성할 것입니다.

참고

이 튜토리얼에서는 간소화를 위해 각 호출이 전체 메시지 기록을 포함하는 독립적인 세션으로 처리되는 “상태 비저장” 방식으로 에이전트를 구현합니다. 프로덕션 환경에서는 Bedrock AgentCore 메모리 통합을 고려하세요. Strands와 AgentCore 메모리 사용에 대한 추가 문서는 여기에서 확인할 수 있습니다.

에이전트 구현

에이전트를 구현해 보겠습니다. packages/story/dungeon_adventure_story/agent 경로의 다음 파일들을 업데이트하세요:

main.py

import os
from bedrock_agentcore.runtime import BedrockAgentCoreApp

from .agent import get_agent

app = BedrockAgentCoreApp()

PORT = int(os.environ.get("PORT", "8080"))

@app.entrypoint
async def invoke(payload, context):
    """Handler for agent invocation"""
    player_name = payload.get("playerName")
    genre = payload.get("genre")
    actions = payload.get("actions")

    messages = [{"role": "user", "content": [{"text": "Continue or create a new story..."}]}]
    for action in actions:
        messages.append({"role": action["role"], "content": [{"text": action["content"]}]})

    with get_agent(player_name, genre, session_id=context.session_id) as agent:
        stream = agent.stream_async(messages)
        async for event in stream:
            print(event)
            yield (event)


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

agent.py

import os
from contextlib import contextmanager

import boto3
from strands import Agent

from .agentcore_mcp_client import AgentCoreMCPClient

# Obtain the region and credentials
region = os.environ["AWS_REGION"]
boto_session = boto3.Session(region_name=region)
credentials = boto_session.get_credentials()


@contextmanager
def get_agent(player_name: str, genre: str, session_id: str):
    mcp_client = AgentCoreMCPClient.with_iam_auth(
        agent_runtime_arn=os.environ["INVENTORY_MCP_ARN"],
        credentials=credentials,
        region=region,
        session_id=session_id,
    )
    with mcp_client:
        yield Agent(
            system_prompt=f"""
You are running a text adventure game in the genre <genre>{genre}</genre> for player <player>{player_name}</player>.
Construct a scenario and give the player decisions to make.
Use the tools to manage the player's inventory as items are obtained or lost.
When adding, removing or updating items in the inventory, always list items to check the current state,
and be careful to match item names exactly. Item names in the inventory must be Title Case.
Ensure you specify a suitable emoji when adding items if available.
When starting a game, populate the inventory with a few initial items. Items should be a key part of the narrative.
Keep responses under 100 words.
""",
            tools=[*mcp_client.list_tools_sync()],
        )

이 구성은 다음을 설정합니다:

• 에이전트 페이로드에서 플레이어, 장르, 액션 추출
• SigV4 인증으로 MCP 서버를 호출할 수 있는 클라이언트 구성
• 시스템 프롬프트와 MCP 서버 도구를 가진 에이전트 생성

배포 및 테스트

먼저 코드베이스를 빌드합니다:

pnpm

pnpm nx run-many --target build --all

yarn

yarn nx run-many --target build --all

npm

npx nx run-many --target build --all

bun

bunx nx run-many --target build --all

팁

린트 오류가 발생하면 다음 명령어로 자동 수정할 수 있습니다.

pnpm

pnpm nx run-many --target lint --configuration=fix --all

yarn

yarn nx run-many --target lint --configuration=fix --all

npm

npx nx run-many --target lint --configuration=fix --all

bun

bunx nx run-many --target lint --configuration=fix --all

이제 다음 명령어로 애플리케이션을 배포할 수 있습니다:

pnpm

pnpm nx deploy infra dungeon-adventure-infra-sandbox/*

yarn

yarn nx deploy infra dungeon-adventure-infra-sandbox/*

npm

npx nx deploy infra dungeon-adventure-infra-sandbox/*

bun

bunx nx deploy infra dungeon-adventure-infra-sandbox/*

배포는 약 2분 정도 소요됩니다.

배포가 완료되면 다음과 유사한 출력을 확인할 수 있습니다(일부 값은 편집됨):

dungeon-adventure-infra-sandbox-Application
dungeon-adventure-infra-sandbox-Application: deploying... [2/2]

 ✅  dungeon-adventure-infra-sandbox-Application

✨  Deployment time: 354s

Outputs:
dungeon-adventure-infra-sandbox-Application.ElectroDbTableTableNameXXX = dungeon-adventure-infra-sandbox-Application-ElectroDbTableXXX-YYY
dungeon-adventure-infra-sandbox-Application.GameApiEndpointXXX = https://xxx.execute-api.region.amazonaws.com/prod/
dungeon-adventure-infra-sandbox-Application.GameUIDistributionDomainNameXXX = xxx.cloudfront.net
dungeon-adventure-infra-sandbox-Application.InventoryMcpArn = arn:aws:bedrock-agentcore:region:xxxxxxx:runtime/dungeonadventureventoryMcpServerXXXX-YYYY
dungeon-adventure-infra-sandbox-Application.StoryAgentArn = arn:aws:bedrock-agentcore:region:xxxxxxx:runtime/dungeonadventurecationStoryAgentXXXX-YYYY
dungeon-adventure-infra-sandbox-Application.UserIdentityUserIdentityIdentityPoolIdXXX = region:xxx
dungeon-adventure-infra-sandbox-Application.UserIdentityUserIdentityUserPoolIdXXX = region_xxx

다음 방법으로 API를 테스트할 수 있습니다:

• 에이전트 서버 로컬 인스턴스를 시작하고 curl로 호출
• JWT 토큰을 사용하여 배포된 API를 curl로 호출

Local

다음 명령어로 로컬 에이전트 서버를 시작하세요:

pnpm

PORT=9999 INVENTORY_MCP_ARN=arn:aws:bedrock-agentcore:region:xxxxxxx:runtime/dungeonadventureventoryMcpServerXXXX-YYYY AWS_REGION=<region> pnpm nx run dungeon_adventure.story:agent-serve

yarn

PORT=9999 INVENTORY_MCP_ARN=arn:aws:bedrock-agentcore:region:xxxxxxx:runtime/dungeonadventureventoryMcpServerXXXX-YYYY AWS_REGION=<region> yarn nx run dungeon_adventure.story:agent-serve

npm

PORT=9999 INVENTORY_MCP_ARN=arn:aws:bedrock-agentcore:region:xxxxxxx:runtime/dungeonadventureventoryMcpServerXXXX-YYYY AWS_REGION=<region> npx nx run dungeon_adventure.story:agent-serve

bun

PORT=9999 INVENTORY_MCP_ARN=arn:aws:bedrock-agentcore:region:xxxxxxx:runtime/dungeonadventureventoryMcpServerXXXX-YYYY AWS_REGION=<region> bunx nx run dungeon_adventure.story:agent-serve

주의

CDK 배포 출력에서 InventoryMcpArn을 사용하고 대상 AWS_REGION을 지정하세요.

에이전트 서버가 실행되면(콘솔 출력 없음) 다음 명령어로 호출하세요:

curl -N -X POST http://127.0.0.1:9999/invocations \
  -d '{"genre":"superhero", "actions":[], "playerName":"UnnamedHero"}' \
  -H "Content-Type: application/json" \
  -H "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: abcdefghijklmnopqrstuvwxyz-123456789"

Deployed

배포된 에이전트를 테스트하려면 Cognito 인증 후 JWT 토큰을 획득해야 합니다. 먼저 환경 변수를 설정하세요:

# CDK 출력에서 Cognito 사용자 풀 ID와 클라이언트 ID 설정
export POOL_ID="<UserPoolId from CDK outputs>"
export CLIENT_ID="<UserPoolClientId from CDK outputs>"
export REGION="<your-region>"

테스트 사용자를 생성하고 인증 토큰을 획득하세요:

# 사용자 생성
aws cognito-idp admin-create-user \
  --user-pool-id $POOL_ID \
  --username "testuser" \
  --temporary-password "TempPass123!" \
  --region $REGION \
  --message-action SUPPRESS > /dev/null

# 영구 비밀번호 설정(더 안전한 비밀번호로 교체 권장)
aws cognito-idp admin-set-user-password \
  --user-pool-id $POOL_ID \
  --username "testuser" \
  --password "PermanentPass123!" \
  --region $REGION \
  --permanent > /dev/null

# 사용자 인증 및 ID 토큰 추출
export BEARER_TOKEN=$(aws cognito-idp initiate-auth \
  --client-id "$CLIENT_ID" \
  --auth-flow USER_PASSWORD_AUTH \
  --auth-parameters USERNAME='testuser',PASSWORD='PermanentPass123!' \
  --region $REGION | jq -r '.AuthenticationResult.IdToken')

주의

CDK 배포 출력에서 UserIdentityUserIdentityUserPoolIdXXX를 POOL_ID로 사용하고 해당 클라이언트 ID를 확인하세요.

이제 Bedrock AgentCore 런타임 URL을 사용하여 배포된 에이전트를 호출하세요:

# CDK 출력에서 스토리 에이전트 ARN 설정
export AGENT_ARN="<StoryAgentArn from CDK outputs>"

# ARN URL 인코딩
export ENCODED_ARN=$(echo $AGENT_ARN | sed 's/:/%3A/g' | sed 's/\//%2F/g')

# 호출 URL 구성
export MCP_URL="https://bedrock-agentcore.$REGION.amazonaws.com/runtimes/$ENCODED_ARN/invocations?qualifier=DEFAULT"

# 에이전트 호출
curl -N -X POST "$MCP_URL" \
  -H "authorization: Bearer $BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: abcdefghijklmnopqrstuvwxyz-123456789" \
  -d '{"genre":"superhero", "actions":[], "playerName":"UnnamedHero"}'

참고

Bedrock AgentCore API 엔드포인트에 ARN을 올바르게 포맷하려면 URL 인코딩이 필요합니다.

명령어가 성공적으로 실행되면 다음과 유사한 스트리밍 이벤트를 볼 수 있습니다:

data: {"init_event_loop": true}

data: {"start": true}

data: {"start_event_loop": true}

data: {"event": {"messageStart": {"role": "assistant"}}}

data: {"event": {"contentBlockDelta": {"delta": {"text": "Welcome"}, "contentBlockIndex": 0}}}

...

축하합니다. Bedrock AgentCore 런타임에 첫 번째 Strands 에이전트를 구축하고 배포했습니다! 🎉🎉🎉