Pular para o conteúdo

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.

Diagram

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.

Use a mesma conta AWS e Região da dungeon implantada. Defina o perfil explicitamente; use um novo prefixo para os recursos do dispositivo:

Janela do terminal
export TUTORIAL_AWS_PROFILE=<your-dungeon-profile>
export TUTORIAL_AWS_REGION=<your-dungeon-region>
export TUTORIAL_PREFIX=gg-dungeon-dice

Siga 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.

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

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:

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

O 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.

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
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
Opções desta etapa9

Obrigatório

Obrigatório

Substitua packages/edge/greengrass/dice/main.py:

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

Substitua packages/edge/greengrass/dice/recipe.yaml:

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

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

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.

Adicione o cliente do plano de dados IoT ao projeto Inventory MCP:

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

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

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');
}
}

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 nomeada dungeon-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 GetThingShadow e UpdateThingShadow em apenas a shadow nomeada dungeon-dice desta 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:

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

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:

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

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:

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

Um 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.

Para remover apenas a extensão:

  1. Registre as saídas DiceArtifactBucket, DiceComponentArn e DiceDeploymentId da pilha de aplicação.
  2. Remova this.deployment.addComponent(component) de packages/infra/src/dice-resources.ts. Reimplante com os mesmos parâmetros. Isso envia uma revisão de implantação vazia; aguarde até que list-installed-components não liste mais com.example.DungeonDice.
  3. 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.
  4. 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.DungeonDice por com.example.Pulse e use as saídas de dados registradas. Inclua cada versão/revisão criada pelo seu exercício de atualização.
  5. 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.
Janela do terminal
aws --profile "$TUTORIAL_AWS_PROFILE" --region "$TUTORIAL_AWS_REGION" \
iot-data delete-thing-shadow --endpoint-url "https://${DICE_IOT_ENDPOINT}" \
--thing-name "$TUTORIAL_THING_NAME" --shadow-name dungeon-dice \
/tmp/dungeon-dice-shadow-deleted.json

A 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.

  • 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.