Opcional: role dados com Greengrass
Mantenha a dungeon que você implantou no Módulo 4. Antes de destruí-la, dê ao seu Story Agent um dispositivo de dados:
“Eu tento arrombar a fechadura. Role um d20 para ver se eu consigo.”
O agente chama roll-dice. Um componente Python em um Greengrass core produz
o lançamento, e a ferramenta MCP retorna esse resultado do dispositivo ao agente. A resposta
pode então dizer “d20: 17” e descrever o resultado.
Esta rota opcional usa um core EC2 com um simulador de dados de software. Você pode posteriormente substituir sua função de número aleatório por entrada de uma bandeja de dados física. O tutorial Greengrass independente permanece como uma forma separada de aprender a geração de componentes a partir de um workspace vazio.
O que você vai adicionar
Seção intitulada “O que você vai adicionar”A shadow na nuvem mantém uma solicitação pendente e o resultado mais recente. A ferramenta aguarda até 12 segundos; ela nunca gera um lançamento de fallback. Uma verificação de versão impede que chamadores concorrentes substituam uma solicitação ativa. O dispositivo armazena seu último resultado antes de publicar, então a reentrega MQTT e uma reinicialização do componente não relançam a mesma solicitação.
Este sandbox compartilha um dispositivo de dados entre jogadores. Um dispositivo ocupado retorna um erro. Ele não adiciona uma fila em toda a frota ou associa dispositivos pessoais com usuários Cognito. Essas são extensões separadas para um produto multi-jogador.
1. Provisione um core sem derrubar a dungeon
Seção intitulada “1. Provisione um core sem derrubar a dungeon”Use a mesma conta AWS e Região da dungeon implantada. Defina o perfil explicitamente; use um novo prefixo para os recursos do dispositivo:
export TUTORIAL_AWS_PROFILE=<your-dungeon-profile>export TUTORIAL_AWS_REGION=<your-dungeon-region>export TUTORIAL_PREFIX=gg-dungeon-diceSiga Provisione o dispositivo core
do workspace da dungeon, incluindo a remoção da política temporária do instalador.
Essa página cria a instância e escreve .greengrass-tutorial.env.
Não crie outro workspace Nx ou execute os módulos heartbeat independentes.
Os padrões existentes do script de configuração permanecem inalterados.
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)Inicialize a shadow nomeada do novo dispositivo uma vez, antes de habilitar a ferramenta. Não execute esta redefinição contra um dispositivo com uma solicitação de dados ativa:
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.jsonO passo a passo do EC2 usa Linux x86_64. Um Raspberry Pi executando Linux de 64 bits usa
linux-arm64 em vez disso; tanto a receita gerada quanto as dependências nativas devem
ter como alvo essa arquitetura. Veja suporte de hardware.
Um ESP32 pode fornecer entrada de sensor para um gateway, mas não pode executar este componente Python.
2. Gere o componente de dados
Seção intitulada “2. Gere o componente de dados”Crie um host Python separado para que o artefato do dispositivo não carregue as dependências de nuvem do Story Agent:
Execute este gerador@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- Instale o Nx Console VSCode Plugin se ainda não o fez
- Abra o console Nx no VSCode
- Clique em
Generate (UI)na seção "Common Nx Commands" - Procure por
@aws/nx-plugin - py#project - Preencha os parâmetros obrigatórios
- name: edge
- Clique em
Generate
Opções desta etapa1
Obrigatório
Execute este gerador@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- Instale o Nx Console VSCode Plugin se ainda não o fez
- Abra o console Nx no VSCode
- Clique em
Generate (UI)na seção "Common Nx Commands" - Procure por
@aws/nx-plugin - greengrass#component - Preencha os parâmetros obrigatórios
- project: edge
- name: dice
- language: python
- componentName: com.example.DungeonDice
- componentVersion: NEXT_PATCH
- platform: linux-amd64
- ipc: true
- infra: component-version
- iac: cdk
- Clique em
Generate
Opções desta etapa9
Obrigatório
Obrigatório
Substitua 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()Substitua 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}"Substitua todos os REPLACE_WITH_CORE_THING_NAME pelo valor de
TUTORIAL_THING_NAME. As permissões IPC da receita nomeiam apenas os tópicos da shadow de dados
deste dispositivo. Python escreve dice-result.json no diretório de trabalho gravável
do componente, fora de seu diretório de artefato somente leitura.
Substitua 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()Esses testes exercitam lançamentos válidos, duplicatas, recuperação de reinicialização, solicitações obsoletas, expiração e falhas de persistência. O teste heartbeat padrão do gerador é substituído porque o componente agora implementa um comportamento diferente.
3. Adicione a ferramenta de dados do agente
Seção intitulada “3. Adicione a ferramenta de dados do agente”Adicione o cliente do plano de dados IoT ao projeto 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/inventoryCrie 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.'); };}Crie 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.' }], }; } });}Atualize 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;};Mantenha todas as três ferramentas de inventário. A conexão do Story Agent gerada já
descobre ferramentas deste servidor, então ela também descobrirá roll-dice.
A ferramenta aceita apenas o tamanho do dado. A identidade do dispositivo e o endpoint vêm da
configuração do servidor; o modelo não pode escolher outro dispositivo ou tópico MQTT.
Durante o desenvolvimento local, as ferramentas de inventário permanecem utilizáveis sem as
variáveis de ambiente DICE_*. Chamar roll-dice retorna um erro de dispositivo
não configurado até que DICE_THING_NAME, DICE_IOT_ENDPOINT e DICE_AWS_REGION sejam definidos.
Atualize 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, )A substituição permite chamadas sequenciais para que um lançamento bem-sucedido possa ser seguido por uma atualização de inventário. Ela ainda permite apenas um lançamento por turno e explicitamente para o desafio quando a ferramenta de dados falha.
4. Componha os recursos do dispositivo na aplicação existente
Seção intitulada “4. Componha os recursos do dispositivo na aplicação existente”Crie 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], }); }}Atualize packages/infra/src/stacks/application-stack.ts para passar a
configuração do dispositivo ao servidor MCP e conceder ao seu runtime acesso à 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'); }}Mantenha o restante da pilha de aplicação existente. DiceResources possui os
parâmetros do dispositivo, concessão de artefato, componente e sua
implantação.
Existem três limites de permissão:
- A política de certificado IoT existente do core permite publicar, assinar
e receber em
$aws/things/<thing-name>/shadow/*, que já inclui a shadow nomeadadungeon-dice. Nenhuma política de certificado adicional é necessária. - A receita de dados concede ao componente acesso a esses tópicos através do IPC.
- O runtime Inventory MCP obtém
GetThingShadoweUpdateThingShadowem apenas a shadow nomeadadungeon-dicedesta thing.
A concessão de artefato permite que a função de troca de token do core busque apenas
com.example.DungeonDice/*. A implantação depende da publicação do componente.
Construa e depois implante com todos os quatro valores de parâmetro:
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"Qualifique os parâmetros para a pilha de aplicação porque a pilha WAF não os define.
Use deploy para este passo a passo. Mudanças de componente/versão substituem
recursos CloudFormation; revisões de implantação
explica a flag de rollback adicional necessária com deploy-sandbox.
Aguarde até que o componente esteja 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. Deixe o agente rolar
Seção intitulada “5. Deixe o agente rolar”Abra o jogo implantado, inicie uma nova conversa ou recarregue a existente, e pergunte:
“Role um d20 no dispositivo de dados para minha tentativa de arrombar esta fechadura.”
O agente deve invocar roll-dice e descrever o valor retornado e
consequência. Leia a shadow na nuvem para comparar seu reported.result com o
resultado da ferramenta e a resposta do agente:
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.jsonUm resultado bem-sucedido inclui requestId, sides, value e rolledAt.
O log do dispositivo em /greengrass/v2/logs/com.example.DungeonDice.log registra o
mesmo ID de solicitação e valor. Uma implantação bem-sucedida sozinha não prova esta
ida e volta.
Para exercitar o caminho de falha, pare o serviço Greengrass neste core descartável através de seu terminal Systems Manager, solicite outro lançamento e verifique que a ferramenta relata um erro após sua espera limitada. O agente deve dizer que o dispositivo está indisponível em vez de decidir o desafio. Reinicie o serviço antes de continuar. Uma solicitação pendente expirada não deve rolar quando o dispositivo se reconectar; uma nova chamada de ferramenta cria uma nova solicitação.
Para um exercício de atualização de versão, altere a mensagem de log do componente, reconstrua e
execute o mesmo comando deploy. NEXT_PATCH publica uma nova versão. Confirme a
nova versão em execução e então solicite outro lançamento.
6. Continue jogando ou remova tudo
Seção intitulada “6. Continue jogando ou remova tudo”Para remover apenas a extensão:
- Registre as saídas
DiceArtifactBucket,DiceComponentArneDiceDeploymentIdda pilha de aplicação. - Remova
this.deployment.addComponent(component)depackages/infra/src/dice-resources.ts. Reimplante com os mesmos parâmetros. Isso envia uma revisão de implantação vazia; aguarde até quelist-installed-componentsnão liste maiscom.example.DungeonDice. - Restaure o prompt base do Story Agent,
remova a importação e chamada de
registerDiceTool, e restaure a pilha de aplicação do Módulo 2. Reconstrua e implante a dungeon. Isso remove as permissões MCP e sua configuração de dados. - Exclua os registros de implantação Greengrass retidos, versões de componente e
bucket de artefato usando o procedimento de limpeza de recursos retidos.
Substitua
com.example.DungeonDiceporcom.example.Pulsee use as saídas de dados registradas. Inclua cada versão/revisão criada pelo seu exercício de atualização. - Exclua a shadow nomeada, então execute a limpeza do script de configuração e remova o perfil de instância e função gerenciados pelo proprietário conforme descrito no guia de limpeza do dispositivo.
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.jsonA dungeon permanece implantada após essas etapas. Para remover toda a aplicação, continue com Destruindo recursos, incluindo seu pool de usuários retido, função SMS e bucket de histórico de conversas.
Experimentos adicionais
Seção intitulada “Experimentos adicionais”- Use um Raspberry Pi com um SO de 64 bits e um sensor físico. Mantenha o ID de solicitação
e contrato de timeout enquanto substitui
secrets.randbelow. - Use um ESP32 para ler o sensor e enviar seu resultado para o gateway Linux. Isso adiciona firmware e autenticação de dispositivo; não é outro alvo de CPU para este componente Python.
- Divida o componente em um motor de dados local e uma ponte MQTT conectada através do pub/sub Greengrass.