代理式AI地牢游戏

模块 3：故事代理实现

警告

请确保您的 AWS 账户已按照本指南所述步骤，在目标区域启用了对 Bedrock 中Strands 默认模型的访问。本文撰写时使用的模型是 Anthropic Claude Sonnet 4。

故事代理是一个 Strands 代理，它基于给定的 Game 和 Action 列表作为上下文来推进故事情节。我们将配置该代理与库存管理服务器（MCP Server）交互，管理玩家可用物品。

注意

为简化教程，我们以”无状态”方式实现代理，每次调用都是包含完整消息历史的独立会话。生产环境中建议集成 Bedrock AgentCore Memory。关于在 Strands 中使用 AgentCore Memory 的更多文档可在此处获取。

代理实现

让我们实现代理。更新 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

提示

若遇到 lint 错误，可运行以下命令自动修复：

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

✨  部署时间: 354s

输出:
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 令牌的 curl 调用已部署 API

本地测试

运行以下命令启动本地代理服务器：

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"

云端测试

测试已部署代理需通过 Cognito 认证获取 JWT 令牌。首先设置环境变量：

# 从 CDK 输出获取 Cognito 用户池 ID 和客户端 ID
export POOL_ID="<CDK 输出的 UserPoolId>"
export CLIENT_ID="<CDK 输出的 UserPoolClientId>"
export 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。

调用已部署代理：

# 设置 CDK 输出的 Story Agent ARN
export AGENT_ARN="<CDK 输出的 StoryAgentArn>"

# URL 编码 ARN
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"}'

注意

URL 编码是正确格式化 Bedrock AgentCore API 端点 ARN 的必要步骤。

成功执行命令后，将看到类似事件流：

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 Runtime 上构建并部署首个 Strands 代理！🎉🎉🎉