Optional: roll dice with Greengrass
Keep the dungeon you deployed in Module 4. Before destroying it, give its Story Agent a dice device:
“I try to pick the lock. Roll a d20 to see whether I succeed.”
The agent calls roll-dice. A Python component on a Greengrass core produces
the roll, and the MCP tool returns that device result to the agent. The reply
can then say “d20: 17” and describe the outcome.
This optional route uses an EC2 core with a software dice simulator. You can later replace its random-number function with input from a physical dice tray. The standalone Greengrass tutorial remains a separate way to learn component generation from an empty workspace.
What you will add
Section titled “What you will add”The cloud shadow holds one pending request and the most recent result. The tool waits up to 12 seconds; it never generates a fallback roll. A version check prevents concurrent callers from replacing an active request. The device stores its last result before publishing, so MQTT redelivery and a component restart do not reroll the same request.
This sandbox shares one dice device among players. A busy device returns an error. It does not add a fleet-wide queue or associate personal devices with Cognito users. Those are separate extensions for a multi-player product.
1. Provision a core without tearing down the dungeon
Section titled “1. Provision a core without tearing down the dungeon”Use the same AWS account and Region as the deployed dungeon. Set the profile explicitly; use a new prefix for the device resources:
export TUTORIAL_AWS_PROFILE=<your-dungeon-profile>export TUTORIAL_AWS_REGION=<your-dungeon-region>export TUTORIAL_PREFIX=gg-dungeon-diceFollow Provision the core device
from the dungeon workspace, including removal of the temporary installer
policy. That page creates the instance and writes .greengrass-tutorial.env.
Do not create another Nx workspace or run the standalone heartbeat modules.
The setup script’s existing defaults stay unchanged.
source .greengrass-tutorial.envexport DICE_IOT_ENDPOINT=$(aws --profile "$TUTORIAL_AWS_PROFILE" --region "$TUTORIAL_AWS_REGION" \ iot describe-endpoint --endpoint-type iot:Data-ATS --query endpointAddress --output text)Initialize the new device’s named shadow once, before enabling the tool. Do not run this reset against a device with an active dice request:
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.jsonThe EC2 walkthrough uses x86_64 Linux. A Raspberry Pi running 64-bit Linux uses
linux-arm64 instead; both the generated recipe and native dependencies must
target that architecture. See hardware support.
An ESP32 can supply sensor input to a gateway, but cannot run this Python component.
2. Generate the dice component
Section titled “2. Generate the dice component”Create a separate Python host so the device artifact does not carry the Story Agent’s cloud dependencies:
Run this generator@aws/nx-plugin:py#project
pnpm nx g @aws/nx-plugin:py#project --name=edge --no-interactive yarn nx g @aws/nx-plugin:py#project --name=edge --no-interactive npx nx g @aws/nx-plugin:py#project --name=edge --no-interactive bunx nx g @aws/nx-plugin:py#project --name=edge --no-interactive- Install the Nx Console VSCode Plugin if you haven't already
- Open the Nx Console in VSCode
- Click
Generate (UI)in the "Common Nx Commands" section - Search for
@aws/nx-plugin - py#project - Fill in the required parameters
- name: edge
- Click
Generate
Options for this step1
Required
Run this generator@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 yarn 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 npx 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 bunx 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- Install the Nx Console VSCode Plugin if you haven't already
- Open the Nx Console in VSCode
- Click
Generate (UI)in the "Common Nx Commands" section - Search for
@aws/nx-plugin - greengrass#component - Fill in the required parameters
- project: edge
- name: dice
- language: python
- componentName: com.example.DungeonDice
- componentVersion: NEXT_PATCH
- platform: linux-amd64
- ipc: true
- infra: component-version
- iac: cdk
- Click
Generate
Options for this step9
Required
Required
Replace packages/edge/greengrass/dice/main.py:
import argparseimport jsonimport loggingimport osimport queueimport secretsimport timeimport uuidfrom pathlib import Pathfrom 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()Replace packages/edge/greengrass/dice/recipe.yaml:
RecipeFormatVersion: '2020-01-25'ComponentName: com.example.DungeonDiceComponentVersion: NEXT_PATCHComponentDescription: Dice rolls requested by the Dungeon Adventure Story Agent.ComponentPublisher: dungeon-adventureComponentConfiguration: 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/rejectedManifests: - 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 every REPLACE_WITH_CORE_THING_NAME with the value of
TUTORIAL_THING_NAME. The recipe’s IPC permissions name only this device’s dice
shadow topics. Python writes dice-result.json in the component’s writable
working directory, outside its read-only artifact directory.
Replace packages/edge/tests/greengrass/test_dice.py:
import importlib.utilimport osimport tempfileimport unittestimport uuidfrom importlib.machinery import SourceFileLoaderfrom pathlib import Pathfrom 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 Nonedice_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()These tests exercise valid rolls, duplicates, restart recovery, stale requests, expiry, and persistence failures. The default generator’s heartbeat test is replaced because the component now implements a different behavior.
3. Add the agent’s dice tool
Section titled “3. Add the agent’s dice tool”Add the IoT data-plane client to the Inventory MCP project:
pnpm add @aws-sdk/client-iot-data-plane@3.1169.0 --filter inventoryyarn workspace @dungeon-adventure/inventory add @aws-sdk/client-iot-data-plane@3.1169.0npm install --legacy-peer-deps @aws-sdk/client-iot-data-plane@3.1169.0 -w packages/inventorybun add @aws-sdk/client-iot-data-plane@3.1169.0 --cwd packages/inventoryCreate 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.'); };}Create 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.' }], }; } });}Update 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;};Keep all three inventory tools. The generated Story Agent connection already
discovers tools from this server, so it will also discover roll-dice.
The tool accepts only the die size. Device identity and endpoint come from the
server’s configuration; the model cannot choose another device or MQTT topic.
During local development, inventory tools remain usable without the DICE_*
environment variables. Calling roll-dice returns an unconfigured-device
error until DICE_THING_NAME, DICE_IOT_ENDPOINT and DICE_AWS_REGION are set.
Update packages/story/dungeon_adventure_story/agent/agent.py:
from contextlib import contextmanager
from dungeon_adventure_agent_connection import InventoryMcpServerClientStrands, log_model_errors, log_tool_errorsfrom strands import Agentfrom strands.hooks import HookCallback, HookProvider
AGENT_HOOKS: list[HookProvider | HookCallback] = [log_model_errors, log_tool_errors]
@contextmanagerdef 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 storybegins, 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 thescene in the chosen genre, and populate their inventory with a few startingitems. On subsequent turns, advance the story in response to the player'sactions 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 andstate 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 andask 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 maycall 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, )from contextlib import contextmanager
from dungeon_adventure_agent_connection import InventoryMcpServerClientStrands, log_model_errors, log_tool_errorsfrom strands import Agentfrom strands.hooks import HookCallback, HookProvider
AGENT_HOOKS: list[HookProvider | HookCallback] = [log_model_errors, log_tool_errors]
@contextmanagerdef 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 storybegins, 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 thescene in the chosen genre, and populate their inventory with a few startingitems. On subsequent turns, advance the story in response to the player'sactions 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.IMPORTANT: Only call ONE tool per response turn. Never batch multiple tool calls in a single turn.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 andstate 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 andask 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 maycall 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, )The replacement permits sequential calls so a successful roll can be followed by an inventory update. It still allows only one roll per turn and explicitly stops the challenge when the dice tool fails.
4. Compose the device resources into the existing application
Section titled “4. Compose the device resources into the existing application”Create 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], }); }}Update packages/infra/src/stacks/application-stack.ts to pass the device
configuration to the MCP server and grant its runtime access to the shadow:
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'); }}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 mcpServer = new InventoryMcpServer(this, 'InventoryMcpServer'); 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'); }}Keep the rest of the existing application stack. DiceResources owns the
device parameters, artifact grant, component and its
deployment.
There are three permission boundaries:
- The core’s existing IoT certificate policy permits publishing, subscribing
and receiving on
$aws/things/<thing-name>/shadow/*, which already includes the nameddungeon-diceshadow. No additional certificate policy is needed. - The dice recipe grants the component access to those topics through IPC.
- The Inventory MCP runtime gets
GetThingShadowandUpdateThingShadowon only this thing’s nameddungeon-diceshadow.
The artifact grant lets the core’s token exchange role fetch only
com.example.DungeonDice/*. The deployment depends on component publication.
Build, then deploy with all four parameter values:
pnpm nx syncyarn nx syncnpx nx syncbunx nx syncpnpm installyarnnpm installbun installpnpm lintyarn lintnpm run lintbun lintpnpm nx run-many --target build --allyarn nx run-many --target build --allnpx nx run-many --target build --allbunx nx run-many --target build --allAWS_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"AWS_PROFILE="$TUTORIAL_AWS_PROFILE" AWS_REGION="$TUTORIAL_AWS_REGION" yarn 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"AWS_PROFILE="$TUTORIAL_AWS_PROFILE" AWS_REGION="$TUTORIAL_AWS_REGION" npx 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"AWS_PROFILE="$TUTORIAL_AWS_PROFILE" AWS_REGION="$TUTORIAL_AWS_REGION" bunx 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"Qualify the parameters for the application stack because the WAF stack does not define them.
Use deploy for this walkthrough. Component/version changes replace
CloudFormation resources; deployment revisions
explains the additional rollback flag needed with deploy-sandbox.
Wait until the component is 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 table5. Let the agent roll
Section titled “5. Let the agent roll”Open the deployed game, start a new conversation or reload the existing one, and ask:
“Roll a d20 on the dice device for my attempt to pick this lock.”
The agent should invoke roll-dice and describe the returned value and
consequence. Read the cloud shadow to compare its reported.result with the
tool result and the agent’s reply:
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.jsoncat /tmp/dungeon-dice-shadow.jsonA successful result includes requestId, sides, value and rolledAt.
The device log at /greengrass/v2/logs/com.example.DungeonDice.log records the
same request ID and value. A successful deployment alone does not prove this
round trip.
To exercise the failure path, stop the Greengrass service on this disposable core through its Systems Manager terminal, request another roll, and verify that the tool reports an error after its bounded wait. The agent should tell you the device is unavailable instead of deciding the challenge. Restart the service before continuing. An expired pending request must not roll when the device reconnects; a new tool call creates a new request.
For a version-update exercise, change the component’s log message, rebuild and
run the same deploy command. NEXT_PATCH publishes a new version. Confirm the
new running version, then request another roll.
6. Keep playing, or remove everything
Section titled “6. Keep playing, or remove everything”To remove only the extension:
- Record the
DiceArtifactBucket,DiceComponentArnandDiceDeploymentIdoutputs from the application stack. - Remove
this.deployment.addComponent(component)frompackages/infra/src/dice-resources.ts. Redeploy with the same parameters. This sends an empty deployment revision; wait untillist-installed-componentsno longer listscom.example.DungeonDice. - Restore the base Story Agent prompt,
remove the
registerDiceToolimport and call, and restore the Module 2 application stack. Rebuild and deploy the dungeon. This removes the MCP permissions and its dice configuration. - Delete the retained Greengrass deployment records, component versions and
artifact bucket using the retained-resource cleanup procedure.
Substitute
com.example.DungeonDiceforcom.example.Pulseand use the recorded dice outputs. Include every version/revision created by your update exercise. - Delete the named shadow, then run the setup script’s cleanup and remove the owner-managed instance profile and role as described in the device cleanup guide.
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.jsonThe dungeon remains deployed after those steps. To remove the whole application, continue with Destroying resources, including its retained user pool, SMS role and conversation-history bucket.
Further experiments
Section titled “Further experiments”- Use a Raspberry Pi with a 64-bit OS and a physical sensor. Keep the request ID
and timeout contract while replacing
secrets.randbelow. - Use an ESP32 to read the sensor and send its result to the Linux gateway. That adds firmware and device authentication; it is not another CPU target for this Python component.
- Split the component into a local dice engine and an MQTT bridge connected through Greengrass pub/sub.