Juego de Mazmorra de IA Agéntica

Módulo 3: Implementación del Agente de Historia

Precaución

Asegúrate de que tu cuenta de AWS haya habilitado acceso al modelo predeterminado de Strands dentro de Bedrock para tu región objetivo siguiendo los pasos descritos en esta guía. Al momento de escribir esto, el modelo es Anthropic Claude Sonnet 4.

El Agente de Historia es un agente de Strands que, dado un Game y una lista de Actions como contexto, avanzará una historia. Configuraremos el agente para interactuar con nuestro Inventory MCP Server y gestionar los objetos disponibles del jugador.

Nota

Para simplificar este tutorial, implementamos el Agente de forma “sin estado” donde cada invocación es una sesión independiente que incluye todo el historial de mensajes. Para entornos de producción, considera integrar con Bedrock AgentCore Memory. Más documentación sobre el uso de AgentCore Memory con Strands está disponible aquí.

Implementación del Agente

Implementemos nuestro agente. Actualiza los siguientes archivos en 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)

+-

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"""
    prompt = payload.get(
        "prompt", "No prompt found in input, please guide the user "
        "to create a json payload with prompt key"
    )
    player_name = payload.get("playerName")
    genre = payload.get("genre")
    actions = payload.get("actions")

    with get_agent(session_id=context.session_id) as agent:
        stream = agent.stream_async(prompt)
    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()
    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()],
        )

+-

import os
from contextlib import contextmanager

from strands import Agent, tool
from strands_tools import current_time
import boto3
from strands import Agent

from .agentcore_mcp_client import AgentCoreMCPClient

# Define a custom tool
@tool
def add(a: int, b: int) -> int:
    return a + b
# 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(session_id: str):
    yield Agent(
        system_prompt="""
You are an addition wizard.
Use the 'add' tool for addition tasks.
Refer to tools as your 'spellbook'.
""",
        tools=[add, current_time],
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()],
        )

Esto configura:

• Extracción del jugador, género y acciones del payload del agente
• Construcción de un cliente que el Agente puede usar para invocar nuestro servidor MCP con Autenticación SigV4
• Construcción del agente con un prompt del sistema y las herramientas del servidor MCP

Despliegue y pruebas

Primero, compilemos el código base:

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

Consejo

Si encuentras errores de linting, puedes ejecutar el siguiente comando para corregirlos automáticamente.

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

Ahora puedes desplegar la aplicación ejecutando:

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/*

Este despliegue tomará aproximadamente 2 minutos en completarse.

Una vez completado el despliegue, verás salidas similares a las siguientes (algunos valores han sido omitidos):

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

 ✅  dungeon-adventure-infra-sandbox-Application

✨  Tiempo de despliegue: 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

Podemos probar nuestra API de dos formas:

• Iniciando una instancia local del servidor del Agente e invocándola con curl.
• Llamando a la API desplegada usando curl con un token JWT.

Local

Inicia el servidor local del Agente ejecutando:

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

Precaución

Usa el output InventoryMcpArn del despliegue CDK arriba, además de especificar tu AWS_REGION objetivo.

Una vez que el servidor del Agente esté en ejecución (¡no verás ninguna salida!), invócalo con:

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"

Desplegado

Para probar el agente desplegado, necesitarás autenticarte con Cognito y obtener un token JWT. Primero configura tus variables de entorno:

# Establece tu User Pool ID y Client ID de Cognito desde los outputs de CDK
export POOL_ID="<UserPoolId from CDK outputs>"
export CLIENT_ID="<UserPoolClientId from CDK outputs>"
export REGION="<your-region>"

Crea un usuario de prueba y obtén un token de autenticación:

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

# Establecer contraseña permanente (¡reemplaza con algo más seguro!)
aws cognito-idp admin-set-user-password \
  --user-pool-id $POOL_ID \
  --username "testuser" \
  --password "PermanentPass123!" \
  --region $REGION \
  --permanent > /dev/null

# Autenticar usuario y capturar token
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')

Precaución

Usa el output UserIdentityUserIdentityUserPoolIdXXX para POOL_ID y asegúrate de tener el Client ID correspondiente en tus outputs de despliegue CDK.

Ahora invoca el agente desplegado usando la URL de Bedrock AgentCore Runtime:

# Establece el ARN del Agente de Historia desde los outputs de CDK
export AGENT_ARN="<StoryAgentArn from CDK outputs>"

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

# Construye la URL de invocación
export MCP_URL="https://bedrock-agentcore.$REGION.amazonaws.com/runtimes/$ENCODED_ARN/invocations?qualifier=DEFAULT"

# Invoca el agente
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"}'

Nota

La codificación URL es necesaria para formatear correctamente el ARN en el endpoint de API de Bedrock AgentCore.

Si el comando se ejecuta correctamente, verás eventos transmitidos similares a:

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}}}

...

¡Felicidades! Has construido y desplegado tu primer Agente de Strands en Bedrock AgentCore Runtime. 🎉🎉🎉