跳转到内容

可选:使用 Greengrass 掷骰子

保留您在模块 4 中部署的地牢。 在销毁它之前,为其 Story Agent 添加一个骰子设备:

“我尝试撬锁。掷一个 d20 看看我是否成功。”

代理调用 roll-dice。Greengrass 核心上的 Python 组件生成 掷骰结果,MCP 工具将该设备结果返回给代理。回复 然后可以说”d20: 17”并描述结果。

此可选路径使用带有软件骰子模拟器的 EC2 核心。您可以 稍后将其随机数函数替换为来自物理骰子托盘的输入。 独立的 Greengrass 教程 仍然是从空工作区学习组件生成的单独方式。

Diagram

云影子保存一个待处理的请求和最近的结果。 工具等待最多 12 秒;它从不生成后备掷骰。版本 检查防止并发调用者替换活动请求。设备 在发布之前存储其最后的结果,因此 MQTT 重新传递和组件 重启不会重新掷同一个请求。

此沙箱在玩家之间共享一个骰子设备。繁忙的设备返回 错误。它不添加全队列或将个人设备与 Cognito 用户关联。这些是多人产品的单独扩展。

1. 在不拆除地牢的情况下配置核心

Section titled “1. 在不拆除地牢的情况下配置核心”

使用与已部署地牢相同的 AWS 账户和区域。明确设置配置文件; 为设备资源使用新前缀:

终端窗口
export TUTORIAL_AWS_PROFILE=<your-dungeon-profile>
export TUTORIAL_AWS_REGION=<your-dungeon-region>
export TUTORIAL_PREFIX=gg-dungeon-dice

从地牢工作区遵循配置核心设备, 包括删除临时安装程序策略。该页面创建实例并写入 .greengrass-tutorial.env。 不要创建另一个 Nx 工作区或运行独立的心跳模块。 设置脚本的现有默认值保持不变。

终端窗口
source .greengrass-tutorial.env
export DICE_IOT_ENDPOINT=$(aws --profile "$TUTORIAL_AWS_PROFILE" --region "$TUTORIAL_AWS_REGION" \
iot describe-endpoint --endpoint-type iot:Data-ATS --query endpointAddress --output text)

在启用工具之前,初始化新设备的命名影子一次。不要 对具有活动骰子请求的设备运行此重置:

终端窗口
aws --profile "$TUTORIAL_AWS_PROFILE" --region "$TUTORIAL_AWS_REGION" \
iot-data update-thing-shadow --endpoint-url "https://${DICE_IOT_ENDPOINT}" \
--thing-name "$TUTORIAL_THING_NAME" --shadow-name dungeon-dice \
--cli-binary-format raw-in-base64-out \
--payload '{"state":{"desired":{"command":null},"reported":{"command":null,"result":null}}}' \
/tmp/dungeon-dice-shadow.json

EC2 演练使用 x86_64 Linux。运行 64 位 Linux 的 Raspberry Pi 使用 linux-arm64;生成的配方和本机依赖项都必须 针对该架构。请参阅硬件支持。 ESP32 可以向网关提供传感器输入,但无法运行此 Python 组件。

创建一个单独的 Python 主机,以便设备工件不携带 Story Agent 的云依赖项:

运行此生成器@aws/nx-plugin:py#project

pnpm nx g @aws/nx-plugin:py#project --name=edge --no-interactive
此步骤的选项1

必需

运行此生成器@aws/nx-plugin:greengrass#component

pnpm nx g @aws/nx-plugin:greengrass#component --project=edge --name=dice --platform=linux-amd64 --infra=component-version --iac=cdk --language=python --componentName=com.example.DungeonDice --componentVersion=NEXT_PATCH --ipc=true --no-interactive
此步骤的选项9

必需

必需

替换 packages/edge/greengrass/dice/main.py:

import argparse
import json
import logging
import os
import queue
import secrets
import time
import uuid
from pathlib import Path
from typing import TypedDict
SIDES = (4, 6, 8, 10, 12, 20)
logger = logging.getLogger("com.example.DungeonDice")
class DiceResult(TypedDict):
requestId: str
sides: int
value: int
rolledAt: int
class SavedRoll(TypedDict):
version: int
result: DiceResult
class Dice:
def __init__(self, state_path: Path):
self.state_path = state_path
self.last: SavedRoll | None = (
json.loads(state_path.read_text()) if state_path.exists() else None
)
def roll(self, command: dict, version: int, now: int) -> DiceResult | None:
try:
uuid.UUID(command["requestId"])
sides = command["sides"]
expires_at = command["expiresAt"]
if type(sides) is not int or sides not in SIDES:
return None
if type(expires_at) is not int or expires_at <= now:
return None
if type(version) is not int or version < 1:
return None
except (KeyError, TypeError, ValueError, AttributeError):
return None
if self.last:
if command["requestId"] == self.last["result"]["requestId"]:
return self.last["result"] if sides == self.last["result"]["sides"] else None
if version <= self.last["version"]:
logger.warning(
"Ignoring stale shadow version %s; last processed version was %s",
version,
self.last["version"],
)
return None
result: DiceResult = {
"requestId": command["requestId"],
"sides": sides,
"value": secrets.randbelow(sides) + 1,
"rolledAt": now,
}
saved: SavedRoll = {"version": version, "result": result}
temporary = self.state_path.with_suffix(".tmp")
with temporary.open("w") as stream:
json.dump(saved, stream)
stream.flush()
os.fsync(stream.fileno())
os.replace(temporary, self.state_path)
self.last = saved
logger.info("Rolled d%s = %s, request %s", sides, result["value"], result["requestId"])
return result
def main() -> None:
from awsiot.greengrasscoreipc.clientv2 import GreengrassCoreIPCClientV2
parser = argparse.ArgumentParser()
parser.add_argument("--thing-name", required=True)
args = parser.parse_args()
logging.basicConfig(level=logging.INFO)
client = GreengrassCoreIPCClientV2()
base = f"$aws/things/{args.thing_name}/shadow/name/dungeon-dice"
events = queue.Queue()
dice = Dice(Path("dice-result.json"))
subscriptions = []
def publish(suffix: str, payload: dict) -> None:
client.publish_to_iot_core(
topic_name=f"{base}/{suffix}",
qos="1",
payload=json.dumps(payload).encode(),
)
def on_event(event) -> None:
events.put(event.message)
for suffix in ("get/accepted", "update/delta", "update/rejected"):
_, operation = client.subscribe_to_iot_core(
topic_name=f"{base}/{suffix}", qos="1", on_stream_event=on_event
)
subscriptions.append(operation)
next_read = 0.0
try:
while True:
try:
if time.monotonic() >= next_read:
publish("get", {})
next_read = time.monotonic() + 15
message = events.get(timeout=1)
document = json.loads(message.payload)
if message.topic_name.endswith("/update/rejected"):
logger.warning("Shadow update rejected: %s", document.get("code"))
next_read = 0
continue
state = document.get("state", {})
if message.topic_name.endswith("/update/delta"):
command = state.get("command")
else:
command = state.get("desired", {}).get("command")
reported = state.get("reported", {}).get("result", {})
if command and reported.get("requestId") == command.get("requestId"):
continue
if not isinstance(command, dict):
continue
version = document.get("version")
result = dice.roll(command, version, int(time.time()))
if result:
publish("update", {
"version": version,
"state": {"reported": {"command": command, "result": result}},
})
except queue.Empty:
continue
except Exception:
logger.exception("Dice exchange failed; will read the shadow again")
next_read = time.monotonic() + 5
finally:
for operation in subscriptions:
operation.close()
client.close()
if __name__ == "__main__":
main()

替换 packages/edge/greengrass/dice/recipe.yaml:

RecipeFormatVersion: '2020-01-25'
ComponentName: com.example.DungeonDice
ComponentVersion: NEXT_PATCH
ComponentDescription: Dice rolls requested by the Dungeon Adventure Story Agent.
ComponentPublisher: dungeon-adventure
ComponentConfiguration:
DefaultConfiguration:
thingName: REPLACE_WITH_CORE_THING_NAME
accessControl:
aws.greengrass.ipc.mqttproxy:
com.example.DungeonDice:mqttproxy:1:
policyDescription: Exchange dice requests and results through the named cloud shadow.
operations:
- aws.greengrass#PublishToIoTCore
- aws.greengrass#SubscribeToIoTCore
resources:
- $aws/things/REPLACE_WITH_CORE_THING_NAME/shadow/name/dungeon-dice/get
- $aws/things/REPLACE_WITH_CORE_THING_NAME/shadow/name/dungeon-dice/get/accepted
- $aws/things/REPLACE_WITH_CORE_THING_NAME/shadow/name/dungeon-dice/update
- $aws/things/REPLACE_WITH_CORE_THING_NAME/shadow/name/dungeon-dice/update/delta
- $aws/things/REPLACE_WITH_CORE_THING_NAME/shadow/name/dungeon-dice/update/rejected
Manifests:
- Platform:
os: linux
architecture: amd64
Artifacts:
- Uri: s3://BUCKET_NAME/COMPONENT_NAME/COMPONENT_VERSION/dice.zip
Unarchive: ZIP
Lifecycle:
Run: python3.14 {artifacts:decompressedPath}/dice/main.py --thing-name "{configuration:/thingName}"

将每个 REPLACE_WITH_CORE_THING_NAME 替换为 TUTORIAL_THING_NAME 的值。配方的 IPC 权限仅命名此设备的骰子 影子主题。Python 在组件的可写 工作目录中写入 dice-result.json,在其只读工件目录之外。

替换 packages/edge/tests/greengrass/test_dice.py:

import importlib.util
import os
import tempfile
import unittest
import uuid
from importlib.machinery import SourceFileLoader
from pathlib import Path
from unittest.mock import patch
MODULE_PATH = Path(os.environ.get(
"DICE_MODULE_PATH",
Path(__file__).parents[2] / "greengrass" / "dice" / "main.py",
))
loader = SourceFileLoader("dungeon_dice", str(MODULE_PATH))
spec = importlib.util.spec_from_loader(loader.name, loader)
assert spec is not None
dice_module = importlib.util.module_from_spec(spec)
loader.exec_module(dice_module)
class TestDice(unittest.TestCase):
def setUp(self):
self.directory = tempfile.TemporaryDirectory()
self.addCleanup(self.directory.cleanup)
self.path = Path(self.directory.name) / "dice-result.json"
self.dice = dice_module.Dice(self.path)
self.command = {"requestId": str(uuid.uuid4()), "sides": 20, "expiresAt": 120}
def test_roll_uses_device_randomness_and_valid_range(self):
with patch.object(dice_module.secrets, "randbelow", return_value=16) as random:
result = self.dice.roll(self.command, 1, 100)
self.assertEqual(result["value"], 17)
self.assertEqual(result["requestId"], self.command["requestId"])
random.assert_called_once_with(20)
def test_duplicate_and_restart_reuse_the_persisted_result(self):
first = self.dice.roll(self.command, 1, 100)
with patch.object(dice_module.secrets, "randbelow", side_effect=AssertionError("rerolled")):
self.assertEqual(self.dice.roll(self.command, 1, 101), first)
self.assertEqual(dice_module.Dice(self.path).roll(self.command, 2, 102), first)
def test_expired_or_invalid_requests_do_not_roll(self):
for command in (
{**self.command, "expiresAt": 100},
{**self.command, "sides": 7},
{**self.command, "sides": True},
{**self.command, "requestId": "invalid"},
{},
):
with self.subTest(command=command):
self.assertIsNone(self.dice.roll(command, 1, 100))
self.assertFalse(self.path.exists())
def test_stale_delivery_cannot_roll_after_a_newer_request(self):
self.dice.roll(self.command, 5, 100)
stale = {**self.command, "requestId": str(uuid.uuid4())}
self.assertIsNone(self.dice.roll(stale, 4, 100))
def test_stale_shadow_version_logs_after_shadow_reset(self):
self.dice.roll(self.command, 5, 100)
reset_shadow_command = {**self.command, "requestId": str(uuid.uuid4())}
with self.assertLogs(dice_module.logger, level="WARNING") as warning:
self.assertIsNone(self.dice.roll(reset_shadow_command, 1, 100))
self.assertIn("Ignoring stale shadow version 1", warning.output[0])
def test_request_id_cannot_be_reused_with_different_sides(self):
self.dice.roll(self.command, 1, 100)
self.assertIsNone(self.dice.roll({**self.command, "sides": 6}, 2, 100))
def test_failed_persistence_does_not_publish_a_result(self):
with (
patch.object(dice_module.os, "replace", side_effect=OSError("disk full")),
self.assertRaises(OSError),
):
self.dice.roll(self.command, 1, 100)
self.assertIsNone(self.dice.last)
if __name__ == "__main__":
unittest.main()

这些测试练习有效的掷骰、重复、重启恢复、过时请求、 过期和持久性失败。默认生成器的心跳测试被 替换,因为组件现在实现了不同的行为。

将 IoT 数据平面客户端添加到 Inventory MCP 项目:

Terminal window
pnpm add @aws-sdk/client-iot-data-plane@3.1169.0 --filter inventory

创建 packages/inventory/src/mcp-server/roll-dice.ts:

import { randomUUID } from 'node:crypto';
import { setTimeout } from 'node:timers/promises';
export const diceSides = [4, 6, 8, 10, 12, 20] as const;
export interface DiceRequest {
requestId: string;
sides: number;
expiresAt: number;
}
export interface DiceResult {
requestId: string;
sides: number;
value: number;
rolledAt: number;
}
export interface DiceShadow {
version: number;
state?: {
desired?: { command?: DiceRequest | null };
reported?: { result?: DiceResult | null };
};
}
export interface ShadowUpdate {
version: number;
state: {
desired: { command: DiceRequest | null };
reported?: { command: null };
};
}
export interface DiceTransport {
read(signal: AbortSignal): Promise<DiceShadow>;
update(update: ShadowUpdate, signal: AbortSignal): Promise<void>;
}
export function createDiceRoller(
transport: DiceTransport,
clock = Date.now,
pause = (signal: AbortSignal) => setTimeout(500, undefined, { signal }),
) {
return async (sides: number): Promise<DiceResult> => {
if (!diceSides.some((allowed) => sides === allowed)) {
throw new Error('Choose d4, d6, d8, d10, d12 or d20.');
}
const signal = AbortSignal.timeout(12_000);
const deadline = clock() + 12_000;
const current = await transport.read(signal);
if (!Number.isInteger(current.version)) {
throw new Error('The dice shadow has no version. Initialize it before playing.');
}
const active = current.state?.desired?.command;
if (active && active.expiresAt * 1000 > clock()) {
throw new Error('The shared dice device is busy. Wait before trying again.');
}
const request: DiceRequest = {
requestId: randomUUID(),
sides,
expiresAt: Math.ceil(deadline / 1000) + 5,
};
// The version makes simultaneous callers compete for a single request slot.
await transport.update({
version: current.version,
state: { desired: { command: request } },
}, signal);
while (clock() < deadline) {
const shadow = await transport.read(signal);
const result = shadow.state?.reported?.result;
if (result?.requestId === request.requestId) {
if (
result.sides !== sides ||
!Number.isInteger(result.value) ||
result.value < 1 ||
result.value > sides ||
!Number.isInteger(result.rolledAt)
) {
throw new Error('The device returned an invalid dice result.');
}
// Release only this request. A late update must not clear a newer one.
if (shadow.state?.desired?.command?.requestId === request.requestId) {
try {
await transport.update({
version: shadow.version,
state: { desired: { command: null }, reported: { command: null } },
}, signal);
} catch (error) {
console.warn('Dice result received; request slot will expire:', error);
}
}
return result;
}
if (shadow.state?.desired?.command?.requestId !== request.requestId) {
throw new Error('The dice request was replaced. No roll result is available.');
}
await pause(signal);
}
throw new Error('The dice device did not respond in time. No roll was fabricated.');
};
}

创建 packages/inventory/src/mcp-server/register-dice.ts:

import {
GetThingShadowCommand,
IoTDataPlaneClient,
UpdateThingShadowCommand,
} from '@aws-sdk/client-iot-data-plane';
import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';
import { createDiceRoller, diceSides, type DiceShadow } from './roll-dice.js';
export function registerDiceTool(server: McpServer) {
server.registerTool('roll-dice', {
description: 'Ask the physical or simulated Greengrass dice device for a roll. Use its returned value; never invent a result when this tool fails.',
inputSchema: {
sides: z.number().int().refine((value) => diceSides.some((sides) => value === sides), {
message: 'Choose 4, 6, 8, 10, 12 or 20 sides.',
}),
},
}, async ({ sides }) => {
const thingName = process.env.DICE_THING_NAME;
const endpoint = process.env.DICE_IOT_ENDPOINT;
const region = process.env.DICE_AWS_REGION;
if (!thingName || !endpoint || !region) {
return {
isError: true,
content: [{ type: 'text' as const, text: 'The dice tool is not configured. Set DICE_THING_NAME, DICE_IOT_ENDPOINT and DICE_AWS_REGION before requesting a roll. Tell the player that no roll is available. Do not invent a result.' }],
};
}
try {
const client = new IoTDataPlaneClient({
region,
endpoint: `https://${endpoint}`,
maxAttempts: 2,
});
const input = { thingName, shadowName: 'dungeon-dice' };
const roll = createDiceRoller({
async read(signal) {
const response = await client.send(new GetThingShadowCommand(input), { abortSignal: signal });
if (!response.payload) throw new Error('The dice shadow returned an empty response.');
return JSON.parse(new TextDecoder().decode(response.payload)) as DiceShadow;
},
async update(update, signal) {
await client.send(new UpdateThingShadowCommand({
...input,
payload: new TextEncoder().encode(JSON.stringify(update)),
}), { abortSignal: signal });
},
});
const result = await roll(sides);
return { content: [{ type: 'text' as const, text: JSON.stringify({ ...result, device: thingName }) }] };
} catch (error) {
console.error('Greengrass dice request failed:', error);
return {
isError: true,
content: [{ type: 'text' as const, text: 'The dice device is busy or unavailable, or its result was invalid. Tell the player that no roll is available and ask them to retry. Do not invent a result.' }],
};
}
});
}

更新 packages/inventory/src/mcp-server/server.ts:

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import z from 'zod';
import { createInventoryEntity } from '@dungeon-adventure/dungeon-db';
import { registerDiceTool } from './register-dice.js';
/**
* Create the MCP Server
*/
export const createServer = async () => {
const server = new McpServer({
name: 'inventory-mcp-server',
version: '1.0.0',
});
server.registerTool(
'list-inventory-items',
{
description: "List items in the player's inventory. Leave cursor blank unless you are requesting subsequent pages",
inputSchema: {
playerName: z.string(),
cursor: z.string().optional(),
},
},
async ({ playerName }) => {
const inventory = await createInventoryEntity();
const results = await inventory.query
.primary({
playerName,
})
.go();
return {
content: [{ type: 'text' as const, text: JSON.stringify(results) }],
};
},
);
server.registerTool(
'add-to-inventory',
{
description: "Add an item to the player's inventory. Quantity defaults to 1 if omitted.",
inputSchema: {
playerName: z.string(),
itemName: z.string(),
emoji: z.string(),
quantity: z.number().optional().default(1),
},
},
async ({ playerName, itemName, emoji, quantity = 1 }) => {
const inventory = await createInventoryEntity();
await inventory
.put({
playerName,
itemName,
quantity,
emoji,
})
.go();
return {
content: [
{
type: 'text' as const,
text: `Added ${itemName} (x${quantity}) to inventory`,
},
],
};
},
);
server.registerTool(
'remove-from-inventory',
{
description: "Remove an item from the player's inventory. If quantity is omitted, all items are removed.",
inputSchema: {
playerName: z.string(),
itemName: z.string(),
quantity: z.number().optional(),
},
},
async ({ playerName, itemName, quantity }) => {
const inventory = await createInventoryEntity();
// If quantity is omitted, remove the entire item
if (quantity === undefined) {
try {
await inventory.delete({ playerName, itemName }).go();
return {
content: [
{ type: 'text' as const, text: `${itemName} removed from inventory.` },
],
};
} catch {
return {
content: [
{ type: 'text' as const, text: `${itemName} not found in inventory` },
],
};
}
}
// If quantity is specified, fetch current quantity and update
const item = await inventory.get({ playerName, itemName }).go();
if (!item.data) {
return {
content: [
{ type: 'text' as const, text: `${itemName} not found in inventory` },
],
};
}
const newQuantity = item.data.quantity - quantity;
if (newQuantity <= 0) {
await inventory.delete({ playerName, itemName }).go();
return {
content: [
{ type: 'text' as const, text: `${itemName} removed from inventory.` },
],
};
}
await inventory
.put({
playerName,
itemName,
quantity: newQuantity,
emoji: item.data.emoji,
})
.go();
return {
content: [
{
type: 'text' as const,
text: `Removed ${itemName} (x${quantity}) from inventory. ${newQuantity} remaining.`,
},
],
};
},
);
registerDiceTool(server);
return server;
};

保留所有三个库存工具。生成的 Story Agent 连接已经 从此服务器发现工具,因此它也将发现 roll-dice。 该工具仅接受骰子大小。设备标识和端点来自 服务器的配置;模型无法选择另一个设备或 MQTT 主题。 在本地开发期间,库存工具在没有 DICE_* 环境变量的情况下仍然可用。调用 roll-dice 会返回未配置设备 错误,直到设置 DICE_THING_NAME、DICE_IOT_ENDPOINT 和 DICE_AWS_REGION。

更新 packages/story/dungeon_adventure_story/agent/agent.py:

from contextlib import contextmanager
from dungeon_adventure_agent_connection import InventoryMcpServerClientStrands, log_model_errors, log_tool_errors
from strands import Agent
from strands.hooks import HookCallback, HookProvider
AGENT_HOOKS: list[HookProvider | HookCallback] = [log_model_errors, log_tool_errors]
@contextmanager
def get_agent():
inventory_mcp_server = InventoryMcpServerClientStrands.create()
with (
inventory_mcp_server,
):
yield Agent(
system_prompt="""
You are running a text adventure game for a lone adventurer. When a new story
begins, the first user message will tell you the player's name and the genre
(one of 'medieval', 'zombie', 'superhero'). Greet the player by name, set the
scene in the chosen genre, and populate their inventory with a few starting
items. On subsequent turns, advance the story in response to the player's
actions and keep item state in sync with the narrative.
Use the tools to manage the player's inventory as items are obtained or lost.
Item names in the inventory must be Title Case — match them exactly.
Only use list-inventory-items if you are unsure of the exact item name before modifying it.
For an uncertain action, explain the challenge and call roll-dice with 20 sides.
For an explicit dice request, use the requested supported die (4, 6, 8, 10, 12 or 20 sides).
Call roll-dice at most once per response turn. Use only its returned value and
state the die, result and consequence in your reply. Never invent a roll.
If roll-dice fails, tell the player that the dice device is unavailable and
ask them to retry. Do not decide the challenge or change inventory for it.
Call tools sequentially and await each result. After a successful roll you may
call an inventory tool if the outcome awards or consumes an item.
Ensure you specify a suitable emoji when adding items if available.
Items should be a key part of the narrative.
Keep responses under 100 words.
""",
tools=[*inventory_mcp_server.list_tools_sync()],
hooks=AGENT_HOOKS,
)

替换允许顺序调用,因此成功的掷骰可以跟随 库存更新。它仍然每回合只允许一次掷骰,并明确 在骰子工具失败时停止挑战。

4. 将设备资源组合到现有应用程序中

Section titled “4. 将设备资源组合到现有应用程序中”

创建 packages/infra/src/dice-resources.ts:

import {
Dice,
GreengrassArtifactBucket,
GreengrassDeployment,
} from '@dungeon-adventure/common-constructs';
import { ArnFormat, CfnOutput, CfnParameter, Stack } from 'aws-cdk-lib';
import { Grant, type IGrantable, Role } from 'aws-cdk-lib/aws-iam';
import { Construct } from 'constructs';
export class DiceResources extends Construct {
readonly environmentVariables: Record<string, string>;
readonly deployment: GreengrassDeployment;
private readonly shadowArn: string;
constructor(scope: Construct, id: string) {
super(scope, id);
const stack = Stack.of(this);
const thing = new CfnParameter(stack, 'DiceThingName', {
type: 'String',
allowedPattern: '[a-zA-Z0-9:_-]+',
});
const endpoint = new CfnParameter(stack, 'DiceEndpoint', { type: 'String' });
const tokenExchangeRole = new CfnParameter(stack, 'TokenExchangeRoleArn', { type: 'String' });
const group = new CfnParameter(stack, 'ThingGroupArn', { type: 'String' });
this.environmentVariables = {
DICE_THING_NAME: thing.valueAsString,
DICE_IOT_ENDPOINT: endpoint.valueAsString,
DICE_AWS_REGION: stack.region,
};
this.shadowArn = stack.formatArn({
service: 'iot',
resource: 'thing',
resourceName: `${thing.valueAsString}/dungeon-dice`,
arnFormat: ArnFormat.SLASH_RESOURCE_NAME,
});
const artifacts = new GreengrassArtifactBucket(this, 'Artifacts');
artifacts.grantReadTo(
Role.fromRoleArn(this, 'TokenExchangeRole', tokenExchangeRole.valueAsString),
'com.example.DungeonDice/*',
);
const component = new Dice(this, 'Component', { bucket: artifacts });
this.deployment = new GreengrassDeployment(this, 'Fleet', { targetArn: group.valueAsString });
this.deployment.addComponent(component);
new CfnOutput(stack, 'DiceArtifactBucket', { value: artifacts.bucket.bucketName });
new CfnOutput(stack, 'DiceComponentArn', { value: component.cfnComponentVersion.attrArn });
new CfnOutput(stack, 'DiceDeploymentId', { value: this.deployment.deployment.attrDeploymentId });
}
grantShadowAccess(grantee: IGrantable): Grant {
return Grant.addToPrincipal({
grantee,
actions: ['iot:GetThingShadow', 'iot:UpdateThingShadow'],
resourceArns: [this.shadowArn],
});
}
}

更新 packages/infra/src/stacks/application-stack.ts 以将设备 配置传递给 MCP 服务器并授予其运行时访问影子的权限:

import {
DungeonDb,
GameApi,
GameUI,
InventoryMcpServer,
StoryAgent,
UserIdentity,
suppressRules,
} from '@dungeon-adventure/common-constructs';
import { Stack, StackProps, CfnOutput, RemovalPolicy } from 'aws-cdk-lib';
import { TableEncryption } from 'aws-cdk-lib/aws-dynamodb';
import { Construct } from 'constructs';
import { DiceResources } from '../dice-resources.js';
export class ApplicationStack extends Stack {
constructor(scope: Construct, id: string, props?: StackProps) {
super(scope, id, props);
const userIdentity = new UserIdentity(this, 'UserIdentity');
// Sandbox-friendly: allow the table to be deleted with the stack.
const dungeonDb = new DungeonDb(this, 'DungeonDb', {
deletionProtection: false,
removalPolicy: RemovalPolicy.DESTROY,
encryption: TableEncryption.DEFAULT,
});
suppressRules(
dungeonDb.table,
['CKV_AWS_119'],
'Sandbox stack uses the AWS owned key so it can be torn down and recreated freely',
);
const gameApi = new GameApi(this, 'GameApi', {
integrations: GameApi.defaultIntegrations(this).build(),
});
dungeonDb.grantReadData(gameApi.integrations['games.query'].handler);
dungeonDb.grantReadData(gameApi.integrations['inventory.query'].handler);
dungeonDb.grantReadWriteData(gameApi.integrations['games.save'].handler);
const dice = new DiceResources(this, 'DiceResources');
const mcpServer = new InventoryMcpServer(this, 'InventoryMcpServer', {
environmentVariables: dice.environmentVariables,
});
dice.grantShadowAccess(mcpServer.agentCoreRuntime);
dungeonDb.grantReadWriteData(mcpServer.agentCoreRuntime);
// Use Cognito for user authentication with the agent
const storyAgent = new StoryAgent(this, 'StoryAgent', {
identity: userIdentity,
});
// The agent's own session bucket already persists conversation history via
// S3SessionManager; grant the Game API read access so it can replay it.
storyAgent.sessionBucket.grantRead(
gameApi.integrations['actions.query'].handler,
);
new CfnOutput(this, 'StoryAgentArn', {
value: storyAgent.agentCoreRuntime.agentRuntimeArn,
});
new CfnOutput(this, 'InventoryMcpArn', {
value: mcpServer.agentCoreRuntime.agentRuntimeArn,
});
// Grant the agent permissions to invoke our mcp server
mcpServer.grantInvokeAccess(storyAgent);
// Grant the authenticated role access to invoke the api
gameApi.grantInvokeAccess(userIdentity.identityPool.authenticatedRole);
new GameUI(this, 'GameUI');
}
}

保留现有应用程序堆栈的其余部分。DiceResources 拥有 设备参数、工件授权、组件及其 部署。

有三个权限边界:

  • 核心的现有 IoT 证书策略允许在 $aws/things/<thing-name>/shadow/* 上发布、订阅 和接收,其中已经包括 命名的 dungeon-dice 影子。不需要额外的证书策略。
  • 骰子配方通过 IPC 授予组件访问这些主题的权限。
  • Inventory MCP 运行时在 仅此物品的命名 dungeon-dice 影子上获取 GetThingShadow 和 UpdateThingShadow。

工件授权让核心的令牌交换角色仅获取 com.example.DungeonDice/*。部署依赖于组件发布。

构建,然后使用所有四个参数值进行部署:

Terminal window
pnpm nx sync
Terminal window
pnpm install
Terminal window
pnpm lint
Terminal window
pnpm nx run-many --target build --all
Terminal window
AWS_PROFILE="$TUTORIAL_AWS_PROFILE" AWS_REGION="$TUTORIAL_AWS_REGION" pnpm nx run @dungeon-adventure/infra:deploy -- "dungeon-adventure-infra-sandbox/**" --parameters dungeon-adventure-infra-sandbox-Application:DiceThingName="$TUTORIAL_THING_NAME" --parameters dungeon-adventure-infra-sandbox-Application:DiceEndpoint="$DICE_IOT_ENDPOINT" --parameters dungeon-adventure-infra-sandbox-Application:TokenExchangeRoleArn="$TUTORIAL_TOKEN_EXCHANGE_ROLE_ARN" --parameters dungeon-adventure-infra-sandbox-Application:ThingGroupArn="$TUTORIAL_THING_GROUP_ARN"

为应用程序堆栈限定参数,因为 WAF 堆栈未定义它们。

对此演练使用 deploy。组件/版本更改替换 CloudFormation 资源;部署修订 解释了 deploy-sandbox 所需的额外回滚标志。

等待组件为 RUNNING:

终端窗口
aws --profile "$TUTORIAL_AWS_PROFILE" --region "$TUTORIAL_AWS_REGION" \
greengrassv2 list-installed-components --core-device-thing-name "$TUTORIAL_THING_NAME" \
--query "installedComponents[?componentName=='com.example.DungeonDice'].[componentVersion,lifecycleState]" \
--output table

打开已部署的游戏,开始新对话或重新加载现有对话, 并询问:

“在骰子设备上掷一个 d20 来尝试撬开这把锁。”

代理应该调用 roll-dice 并描述返回的值和 后果。读取云影子以将其 reported.result 与 工具结果和代理的回复进行比较:

终端窗口
aws --profile "$TUTORIAL_AWS_PROFILE" --region "$TUTORIAL_AWS_REGION" \
iot-data get-thing-shadow --endpoint-url "https://${DICE_IOT_ENDPOINT}" \
--thing-name "$TUTORIAL_THING_NAME" --shadow-name dungeon-dice \
/tmp/dungeon-dice-shadow.json
cat /tmp/dungeon-dice-shadow.json

成功的结果包括 requestId、sides、value 和 rolledAt。 /greengrass/v2/logs/com.example.DungeonDice.log 处的设备日志记录 相同的请求 ID 和值。仅成功部署并不能证明此 往返。

要练习失败路径,请通过其 Systems Manager 终端在此一次性 核心上停止 Greengrass 服务,请求另一次掷骰,并验证 工具在其有界等待后报告错误。代理应该告诉 您设备不可用,而不是决定挑战。在继续之前重新启动 服务。过期的待处理请求在 设备重新连接时不得掷骰;新的工具调用创建新请求。

对于版本更新练习,更改组件的日志消息,重新构建并 运行相同的部署命令。NEXT_PATCH 发布新版本。确认 新的运行版本,然后请求另一次掷骰。

仅删除扩展:

  1. 从应用程序堆栈记录 DiceArtifactBucket、DiceComponentArn 和 DiceDeploymentId 输出。
  2. 从 packages/infra/src/dice-resources.ts 中删除 this.deployment.addComponent(component)。使用相同的参数重新部署。 这会发送一个空的部署修订;等待 list-installed-components 不再列出 com.example.DungeonDice。
  3. 恢复基本的 Story Agent 提示, 删除 registerDiceTool 导入和调用,并恢复 模块 2 应用程序堆栈。 重新构建并部署地牢。这将删除 MCP 权限及其 骰子配置。
  4. 使用保留资源清理过程删除保留的 Greengrass 部署记录、组件版本和 工件存储桶。 将 com.example.DungeonDice 替换为 com.example.Pulse 并使用 记录的骰子输出。包括您的更新 练习创建的每个版本/修订。
  5. 删除命名影子,然后运行设置脚本的清理并删除 所有者管理的实例配置文件和角色,如 设备清理指南中所述。
终端窗口
aws --profile "$TUTORIAL_AWS_PROFILE" --region "$TUTORIAL_AWS_REGION" \
iot-data delete-thing-shadow --endpoint-url "https://${DICE_IOT_ENDPOINT}" \
--thing-name "$TUTORIAL_THING_NAME" --shadow-name dungeon-dice \
/tmp/dungeon-dice-shadow-deleted.json

在这些步骤之后,地牢仍然保持部署。要删除整个应用程序, 继续销毁资源, 包括其保留的用户池、SMS 角色和对话历史存储桶。

  • 使用带有 64 位操作系统和物理传感器的 Raspberry Pi。保留请求 ID 和超时契约,同时替换 secrets.randbelow。
  • 使用 ESP32 读取传感器并将其结果发送到 Linux 网关。 这会添加固件和设备身份验证;它不是此 Python 组件的另一个 CPU 目标。
  • 将组件拆分为本地骰子引擎和通过 Greengrass pub/sub 连接的 MQTT 桥接。