Optionnel : lancer des dés avec Greengrass
Conservez le donjon que vous avez déployé dans le Module 4. Avant de le détruire, donnez à son Story Agent un appareil de dés :
“J’essaie de crocheter la serrure. Lance un d20 pour voir si je réussis.”
L’agent appelle roll-dice. Un composant Python sur un Greengrass core produit
le lancer, et l’outil MCP retourne ce résultat d’appareil à l’agent. La réponse
peut alors dire “d20 : 17” et décrire le résultat.
Cette route optionnelle utilise un core EC2 avec un simulateur de dés logiciel. Vous pouvez plus tard remplacer sa fonction de nombre aléatoire par une entrée provenant d’un plateau de dés physique. Le tutoriel Greengrass autonome reste une façon distincte d’apprendre la génération de composants à partir d’un espace de travail vide.
Ce que vous allez ajouter
Section intitulée « Ce que vous allez ajouter »Le shadow cloud contient une requête en attente et le résultat le plus récent. L’outil attend jusqu’à 12 secondes ; il ne génère jamais de lancer de secours. Une vérification de version empêche les appelants concurrents de remplacer une requête active. L’appareil stocke son dernier résultat avant de publier, donc la relivraison MQTT et un redémarrage de composant ne relancent pas la même requête.
Ce bac à sable partage un appareil de dés entre les joueurs. Un appareil occupé retourne une erreur. Il n’ajoute pas de file d’attente à l’échelle de la flotte ni n’associe d’appareils personnels avec les utilisateurs Cognito. Ce sont des extensions séparées pour un produit multijoueur.
1. Provisionner un core sans détruire le donjon
Section intitulée « 1. Provisionner un core sans détruire le donjon »Utilisez le même compte AWS et la même région que le donjon déployé. Définissez le profil explicitement ; utilisez un nouveau préfixe pour les ressources de l’appareil :
export TUTORIAL_AWS_PROFILE=<your-dungeon-profile>export TUTORIAL_AWS_REGION=<your-dungeon-region>export TUTORIAL_PREFIX=gg-dungeon-diceSuivez Provisionner l’appareil core
depuis l’espace de travail dungeon, y compris la suppression de la politique d’installateur
temporaire. Cette page crée l’instance et écrit .greengrass-tutorial.env.
Ne créez pas un autre espace de travail Nx et n’exécutez pas les modules heartbeat autonomes.
Les valeurs par défaut existantes du script de configuration restent inchangées.
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)Initialisez le shadow nommé du nouvel appareil une fois, avant d’activer l’outil. N’exécutez pas cette réinitialisation contre un appareil avec une requête de dés active :
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.jsonLa procédure pas à pas EC2 utilise x86_64 Linux. Un Raspberry Pi exécutant Linux 64 bits utilise
linux-arm64 à la place ; la recette générée et les dépendances natives doivent
cibler cette architecture. Voir support matériel.
Un ESP32 peut fournir une entrée de capteur à une passerelle, mais ne peut pas exécuter ce composant Python.
2. Générer le composant de dés
Section intitulée « 2. Générer le composant de dés »Créez un hôte Python séparé afin que l’artefact de l’appareil ne transporte pas les dépendances cloud du Story Agent :
Exécuter ce générateur@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- Installez le Nx Console VSCode Plugin si ce n'est pas déjà fait
- Ouvrez la console Nx dans VSCode
- Cliquez sur
Generate (UI)dans la section "Common Nx Commands" - Recherchez
@aws/nx-plugin - py#project - Remplissez les paramètres requis
- name: edge
- Cliquez sur
Generate
Options de cette étape1
Requis
Exécuter ce générateur@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- Installez le Nx Console VSCode Plugin si ce n'est pas déjà fait
- Ouvrez la console Nx dans VSCode
- Cliquez sur
Generate (UI)dans la section "Common Nx Commands" - Recherchez
@aws/nx-plugin - greengrass#component - Remplissez les paramètres requis
- project: edge
- name: dice
- language: python
- componentName: com.example.DungeonDice
- componentVersion: NEXT_PATCH
- platform: linux-amd64
- ipc: true
- infra: component-version
- iac: cdk
- Cliquez sur
Generate
Options de cette étape9
Requis
Requis
Remplacez 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()Remplacez 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}"Remplacez chaque REPLACE_WITH_CORE_THING_NAME par la valeur de
TUTORIAL_THING_NAME. Les permissions IPC de la recette nomment uniquement les topics du shadow de dés
de cet appareil. Python écrit dice-result.json dans le répertoire de travail inscriptible
du composant, en dehors de son répertoire d’artefact en lecture seule.
Remplacez 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()Ces tests exercent les lancers valides, les doublons, la récupération après redémarrage, les requêtes obsolètes, l’expiration et les échecs de persistance. Le test heartbeat par défaut du générateur est remplacé car le composant implémente maintenant un comportement différent.
3. Ajouter l’outil de dés de l’agent
Section intitulée « 3. Ajouter l’outil de dés de l’agent »Ajoutez le client de plan de données IoT au projet Inventory MCP :
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/inventoryCréez 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.'); };}Créez 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.' }], }; } });}Mettez à jour 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;};Conservez les trois outils d’inventaire. La connexion Story Agent générée découvre déjà
les outils de ce serveur, elle découvrira donc aussi roll-dice.
L’outil n’accepte que la taille du dé. L’identité de l’appareil et le point de terminaison proviennent de la
configuration du serveur ; le modèle ne peut pas choisir un autre appareil ou topic MQTT.
Pendant le développement local, les outils d’inventaire restent utilisables sans les variables
d’environnement DICE_*. L’appel de roll-dice retourne une erreur d’appareil non configuré
jusqu’à ce que DICE_THING_NAME, DICE_IOT_ENDPOINT et DICE_AWS_REGION soient définis.
Mettez à jour 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, )Le remplacement permet les appels séquentiels afin qu’un lancer réussi puisse être suivi d’une mise à jour d’inventaire. Il n’autorise toujours qu’un seul lancer par tour et arrête explicitement le défi lorsque l’outil de dés échoue.
4. Composer les ressources de l’appareil dans l’application existante
Section intitulée « 4. Composer les ressources de l’appareil dans l’application existante »Créez 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], }); }}Mettez à jour packages/infra/src/stacks/application-stack.ts pour passer la configuration
de l’appareil au serveur MCP et accorder à son runtime l’accès au 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'); }}Conservez le reste de la pile d’application existante. DiceResources possède les
paramètres de l’appareil, l’octroi d’artefact, le composant et son
déploiement.
Il y a trois limites de permissions :
- La politique de certificat IoT existante du core permet la publication, l’abonnement
et la réception sur
$aws/things/<thing-name>/shadow/*, qui inclut déjà le shadow nommédungeon-dice. Aucune politique de certificat supplémentaire n’est nécessaire. - La recette de dés accorde au composant l’accès à ces topics via IPC.
- Le runtime Inventory MCP obtient
GetThingShadowetUpdateThingShadowsur uniquement le shadow nommédungeon-dicede cette chose.
L’octroi d’artefact permet au rôle d’échange de jetons du core de récupérer uniquement
com.example.DungeonDice/*. Le déploiement dépend de la publication du composant.
Construisez, puis déployez avec les quatre valeurs de paramètres :
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"Qualifiez les paramètres pour la pile d’application car la pile WAF ne les définit pas.
Utilisez deploy pour cette procédure. Les changements de composant/version remplacent
les ressources CloudFormation ; révisions de déploiement
explique le flag de rollback supplémentaire nécessaire avec deploy-sandbox.
Attendez que le composant soit 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. Laisser l’agent lancer les dés
Section intitulée « 5. Laisser l’agent lancer les dés »Ouvrez le jeu déployé, démarrez une nouvelle conversation ou rechargez celle existante, et demandez :
“Lance un d20 sur l’appareil de dés pour ma tentative de crocheter cette serrure.”
L’agent devrait invoquer roll-dice et décrire la valeur retournée et
la conséquence. Lisez le shadow cloud pour comparer son reported.result avec le
résultat de l’outil et la réponse de l’agent :
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.jsonUn résultat réussi inclut requestId, sides, value et rolledAt.
Le journal de l’appareil à /greengrass/v2/logs/com.example.DungeonDice.log enregistre le
même ID de requête et la même valeur. Un déploiement réussi seul ne prouve pas cet
aller-retour.
Pour exercer le chemin d’échec, arrêtez le service Greengrass sur ce core jetable via son terminal Systems Manager, demandez un autre lancer, et vérifiez que l’outil signale une erreur après son attente bornée. L’agent devrait vous dire que l’appareil n’est pas disponible au lieu de décider du défi. Redémarrez le service avant de continuer. Une requête en attente expirée ne doit pas lancer lorsque l’appareil se reconnecte ; un nouvel appel d’outil crée une nouvelle requête.
Pour un exercice de mise à jour de version, changez le message de journal du composant, reconstruisez et
exécutez la même commande deploy. NEXT_PATCH publie une nouvelle version. Confirmez la
nouvelle version en cours d’exécution, puis demandez un autre lancer.
6. Continuer à jouer, ou tout supprimer
Section intitulée « 6. Continuer à jouer, ou tout supprimer »Pour supprimer uniquement l’extension :
- Enregistrez les sorties
DiceArtifactBucket,DiceComponentArnetDiceDeploymentIdde la pile d’application. - Supprimez
this.deployment.addComponent(component)depackages/infra/src/dice-resources.ts. Redéployez avec les mêmes paramètres. Cela envoie une révision de déploiement vide ; attendez quelist-installed-componentsne liste pluscom.example.DungeonDice. - Restaurez le prompt Story Agent de base,
supprimez l’import et l’appel
registerDiceTool, et restaurez la pile d’application du Module 2. Reconstruisez et déployez le donjon. Cela supprime les permissions MCP et sa configuration de dés. - Supprimez les enregistrements de déploiement Greengrass conservés, les versions de composant et
le bucket d’artefacts en utilisant la procédure de nettoyage des ressources conservées.
Substituez
com.example.DungeonDiceàcom.example.Pulseet utilisez les sorties de dés enregistrées. Incluez chaque version/révision créée par votre exercice de mise à jour. - Supprimez le shadow nommé, puis exécutez le nettoyage du script de configuration et supprimez le profil d’instance et le rôle gérés par le propriétaire comme décrit dans le guide de nettoyage de l’appareil.
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.jsonLe donjon reste déployé après ces étapes. Pour supprimer l’application entière, continuez avec Détruire les ressources, y compris son pool d’utilisateurs conservé, son rôle SMS et son bucket d’historique de conversation.
Expériences supplémentaires
Section intitulée « Expériences supplémentaires »- Utilisez un Raspberry Pi avec un OS 64 bits et un capteur physique. Conservez l’ID de requête
et le contrat de timeout tout en remplaçant
secrets.randbelow. - Utilisez un ESP32 pour lire le capteur et envoyer son résultat à la passerelle Linux. Cela ajoute le firmware et l’authentification de l’appareil ; ce n’est pas une autre cible CPU pour ce composant Python.
- Divisez le composant en un moteur de dés local et un pont MQTT connecté via Greengrass pub/sub.