Tùy chọn: tung xúc xắc với Greengrass
Giữ nguyên dungeon mà bạn đã triển khai trong Module 4. Trước khi hủy nó, hãy cung cấp cho Story Agent của nó một thiết bị xúc xắc:
“Tôi cố gắng mở khóa. Tung một d20 để xem liệu tôi có thành công không.”
Agent gọi roll-dice. Một thành phần Python trên lõi Greengrass tạo ra
kết quả tung xúc xắc, và công cụ MCP trả về kết quả thiết bị đó cho agent. Phản hồi
sau đó có thể nói “d20: 17” và mô tả kết quả.
Tuyến đường tùy chọn này sử dụng lõi EC2 với trình mô phỏng xúc xắc phần mềm. Bạn có thể sau này thay thế hàm số ngẫu nhiên của nó bằng đầu vào từ khay xúc xắc vật lý. Hướng dẫn Greengrass độc lập vẫn là một cách riêng biệt để học cách tạo thành phần từ workspace trống.
Những gì bạn sẽ thêm vào
Phần tiêu đề “Những gì bạn sẽ thêm vào”Shadow đám mây giữ một yêu cầu đang chờ xử lý và kết quả gần nhất. Công cụ chờ tối đa 12 giây; nó không bao giờ tạo ra kết quả tung dự phòng. Kiểm tra phiên bản ngăn chặn các người gọi đồng thời thay thế một yêu cầu đang hoạt động. Thiết bị lưu trữ kết quả cuối cùng của nó trước khi xuất bản, vì vậy việc gửi lại MQTT và khởi động lại thành phần không tung lại cùng một yêu cầu.
Sandbox này chia sẻ một thiết bị xúc xắc giữa các người chơi. Một thiết bị bận trả về lỗi. Nó không thêm hàng đợi trên toàn bộ đội và không liên kết các thiết bị cá nhân với người dùng Cognito. Đó là các phần mở rộng riêng biệt cho sản phẩm nhiều người chơi.
1. Cung cấp lõi mà không phá hủy dungeon
Phần tiêu đề “1. Cung cấp lõi mà không phá hủy dungeon”Sử dụng cùng tài khoản AWS và Region như dungeon đã triển khai. Đặt profile một cách rõ ràng; sử dụng tiền tố mới cho tài nguyên thiết bị:
export TUTORIAL_AWS_PROFILE=<your-dungeon-profile>export TUTORIAL_AWS_REGION=<your-dungeon-region>export TUTORIAL_PREFIX=gg-dungeon-diceLàm theo Cung cấp thiết bị lõi
từ workspace dungeon, bao gồm việc xóa chính sách cài đặt tạm thời.
Trang đó tạo instance và ghi .greengrass-tutorial.env.
Không tạo workspace Nx khác hoặc chạy các module heartbeat độc lập.
Các giá trị mặc định hiện có của script thiết lập không thay đổi.
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)Khởi tạo named shadow của thiết bị mới một lần, trước khi bật công cụ. Không chạy lệnh reset này đối với thiết bị có yêu cầu xúc xắc đang hoạt động:
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.jsonHướng dẫn EC2 sử dụng x86_64 Linux. Raspberry Pi chạy Linux 64-bit sử dụng
linux-arm64 thay thế; cả recipe được tạo và các phụ thuộc gốc đều phải
nhắm đến kiến trúc đó. Xem hỗ trợ phần cứng.
ESP32 có thể cung cấp đầu vào cảm biến cho gateway, nhưng không thể chạy thành phần Python này.
2. Tạo thành phần xúc xắc
Phần tiêu đề “2. Tạo thành phần xúc xắc”Tạo một host Python riêng biệt để artifact thiết bị không mang theo các phụ thuộc đám mây của Story Agent:
Chạy generator này@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- Cài đặt Nx Console VSCode Plugin nếu bạn chưa cài đặt
- Mở Nx Console trong VSCode
- Nhấp
Generate (UI)trong phần "Common Nx Commands" - Tìm kiếm
@aws/nx-plugin - py#project - Điền các tham số bắt buộc
- name: edge
- Nhấp
Generate
Tùy chọn cho bước này1
Bắt buộc
Chạy generator này@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- Cài đặt Nx Console VSCode Plugin nếu bạn chưa cài đặt
- Mở Nx Console trong VSCode
- Nhấp
Generate (UI)trong phần "Common Nx Commands" - Tìm kiếm
@aws/nx-plugin - greengrass#component - Điền các tham số bắt buộc
- project: edge
- name: dice
- language: python
- componentName: com.example.DungeonDice
- componentVersion: NEXT_PATCH
- platform: linux-amd64
- ipc: true
- infra: component-version
- iac: cdk
- Nhấp
Generate
Tùy chọn cho bước này9
Bắt buộc
Bắt buộc
Thay thế 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()Thay thế 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}"Thay thế mọi REPLACE_WITH_CORE_THING_NAME bằng giá trị của
TUTORIAL_THING_NAME. Quyền IPC của recipe chỉ đặt tên các chủ đề shadow xúc xắc của thiết bị này.
Python ghi dice-result.json trong thư mục làm việc có thể ghi của thành phần,
bên ngoài thư mục artifact chỉ đọc của nó.
Thay thế 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()Các bài kiểm tra này thực hiện các lần tung hợp lệ, trùng lặp, khôi phục khởi động lại, yêu cầu cũ, hết hạn và lỗi lưu trữ. Bài kiểm tra heartbeat mặc định của generator được thay thế vì thành phần hiện thực hiện một hành vi khác.
3. Thêm công cụ xúc xắc của agent
Phần tiêu đề “3. Thêm công cụ xúc xắc của agent”Thêm client data-plane IoT vào dự án 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/inventoryTạo 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.'); };}Tạo 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.' }], }; } });}Cập nhật 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;};Giữ cả ba công cụ inventory. Kết nối Story Agent được tạo đã
khám phá các công cụ từ server này, vì vậy nó cũng sẽ khám phá roll-dice.
Công cụ chỉ chấp nhận kích thước xúc xắc. Danh tính thiết bị và endpoint đến từ
cấu hình của server; model không thể chọn thiết bị hoặc chủ đề MQTT khác.
Trong quá trình phát triển cục bộ, các công cụ inventory vẫn có thể sử dụng mà không cần các biến
môi trường DICE_*. Gọi roll-dice trả về lỗi thiết bị chưa được cấu hình
cho đến khi DICE_THING_NAME, DICE_IOT_ENDPOINT và DICE_AWS_REGION được đặt.
Cập nhật 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, )Việc thay thế cho phép các lần gọi tuần tự để một lần tung thành công có thể được theo sau bởi cập nhật inventory. Nó vẫn chỉ cho phép một lần tung mỗi lượt và rõ ràng dừng thử thách khi công cụ xúc xắc thất bại.
4. Soạn tài nguyên thiết bị vào ứng dụng hiện có
Phần tiêu đề “4. Soạn tài nguyên thiết bị vào ứng dụng hiện có”Tạo 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], }); }}Cập nhật packages/infra/src/stacks/application-stack.ts để truyền cấu hình thiết bị
cho MCP server và cấp quyền truy cập runtime vào 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'); }}Giữ phần còn lại của application stack hiện có. DiceResources sở hữu các
tham số thiết bị, cấp phép artifact, thành phần và
triển khai của nó.
Có ba ranh giới quyền:
- Chính sách chứng chỉ IoT hiện có của lõi cho phép xuất bản, đăng ký
và nhận trên
$aws/things/<thing-name>/shadow/*, đã bao gồm named shadowdungeon-dice. Không cần chính sách chứng chỉ bổ sung. - Recipe xúc xắc cấp cho thành phần quyền truy cập vào các chủ đề đó thông qua IPC.
- Runtime Inventory MCP nhận
GetThingShadowvàUpdateThingShadowtrên chỉ named shadowdungeon-dicecủa thing này.
Cấp phép artifact cho phép vai trò trao đổi token của lõi chỉ lấy
com.example.DungeonDice/*. Triển khai phụ thuộc vào việc xuất bản thành phần.
Build, sau đó triển khai với tất cả bốn giá trị tham số:
pnpm nx syncyarn nx syncnpx nx syncbunx nx syncpnpm installyarnnpm installbun installpnpm lint --skip-nx-cacheyarn lint --skip-nx-cachenpm run lint --skip-nx-cachebun lint --skip-nx-cachepnpm 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"Chỉ định các tham số cho application stack vì WAF stack không định nghĩa chúng.
Sử dụng deploy cho hướng dẫn này. Các thay đổi thành phần/phiên bản thay thế
tài nguyên CloudFormation; deployment revisions
giải thích cờ rollback bổ sung cần thiết với deploy-sandbox.
Chờ cho đến khi thành phần là 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. Để agent tung xúc xắc
Phần tiêu đề “5. Để agent tung xúc xắc”Mở trò chơi đã triển khai, bắt đầu cuộc trò chuyện mới hoặc tải lại cuộc trò chuyện hiện có, và hỏi:
“Tung một d20 trên thiết bị xúc xắc cho nỗ lực mở khóa này của tôi.”
Agent nên gọi roll-dice và mô tả giá trị trả về và
hậu quả. Đọc shadow đám mây để so sánh reported.result của nó với
kết quả công cụ và phản hồi của 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.jsonKết quả thành công bao gồm requestId, sides, value và rolledAt.
Log thiết bị tại /greengrass/v2/logs/com.example.DungeonDice.log ghi lại
cùng request ID và giá trị. Một triển khai thành công đơn thuần không chứng minh
vòng lặp này.
Để thực hiện đường dẫn thất bại, dừng dịch vụ Greengrass trên lõi dùng một lần này thông qua terminal Systems Manager của nó, yêu cầu một lần tung khác, và xác minh rằng công cụ báo cáo lỗi sau thời gian chờ giới hạn của nó. Agent nên nói với bạn rằng thiết bị không khả dụng thay vì quyết định thử thách. Khởi động lại dịch vụ trước khi tiếp tục. Một yêu cầu đang chờ hết hạn không được tung khi thiết bị kết nối lại; một lần gọi công cụ mới tạo một yêu cầu mới.
Để thực hiện bài tập cập nhật phiên bản, thay đổi thông báo log của thành phần, rebuild và
chạy cùng lệnh deploy. NEXT_PATCH xuất bản một phiên bản mới. Xác nhận
phiên bản đang chạy mới, sau đó yêu cầu một lần tung khác.
6. Tiếp tục chơi, hoặc xóa mọi thứ
Phần tiêu đề “6. Tiếp tục chơi, hoặc xóa mọi thứ”Để chỉ xóa phần mở rộng:
- Ghi lại các output
DiceArtifactBucket,DiceComponentArnvàDiceDeploymentIdtừ application stack. - Xóa
this.deployment.addComponent(component)khỏipackages/infra/src/dice-resources.ts. Triển khai lại với cùng các tham số. Điều này gửi một revision triển khai trống; chờ cho đến khilist-installed-componentskhông còn liệt kêcom.example.DungeonDice. - Khôi phục prompt Story Agent cơ bản,
xóa import và lời gọi
registerDiceTool, và khôi phục application stack Module 2. Rebuild và triển khai dungeon. Điều này xóa quyền MCP và cấu hình xúc xắc của nó. - Xóa các bản ghi triển khai Greengrass được giữ lại, các phiên bản thành phần và
artifact bucket bằng cách sử dụng quy trình dọn dẹp tài nguyên được giữ lại.
Thay thế
com.example.DungeonDicechocom.example.Pulsevà sử dụng các output xúc xắc đã ghi lại. Bao gồm mọi phiên bản/revision được tạo bởi bài tập cập nhật của bạn. - Xóa named shadow, sau đó chạy dọn dẹp script thiết lập và xóa instance profile và role được quản lý bởi chủ sở hữu như được mô tả trong hướng dẫn dọn dẹp thiết bị.
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.jsonDungeon vẫn được triển khai sau các bước đó. Để xóa toàn bộ ứng dụng, tiếp tục với Hủy tài nguyên, bao gồm user pool được giữ lại, vai trò SMS và bucket lịch sử cuộc trò chuyện của nó.
Các thử nghiệm tiếp theo
Phần tiêu đề “Các thử nghiệm tiếp theo”- Sử dụng Raspberry Pi với hệ điều hành 64-bit và cảm biến vật lý. Giữ request ID
và hợp đồng timeout trong khi thay thế
secrets.randbelow. - Sử dụng ESP32 để đọc cảm biến và gửi kết quả của nó đến gateway Linux. Điều đó thêm firmware và xác thực thiết bị; nó không phải là mục tiêu CPU khác cho thành phần Python này.
- Tách thành phần thành một engine xúc xắc cục bộ và một cầu nối MQTT được kết nối thông qua pub/sub Greengrass.