Implementare e configurare l'agente Story

Task 1: Implementare l’agente Story

L’agente Story è un agente Strands generato con --protocol=ag-ui nel Modulo 1, in modo che l’interfaccia utente possa ricevere lo streaming da esso tramite il protocollo Agent-User Interaction via CopilotKit. Utilizza il server MCP Inventory per gestire gli oggetti del giocatore e persiste già la cronologia delle conversazioni tramite il session.py che il generatore ha fornito nel Modulo 1 — una volta distribuito, si tratta del S3SessionManager integrato di Strands che scrive nello stesso bucket S3 da cui legge il queryActions dell’API Game, in modo che il browser possa ricostruire le trascrizioni alla rivisitazione.

Implementazione dell’agente

Aggiorna agent.py in packages/story/dungeon_adventure_story/agent:

from contextlib import contextmanager

from dungeon_adventure_agent_connection import InventoryMcpServerClientStrands, log_model_errors, log_tool_errors
from strands import Agent


@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.
IMPORTANT: Only call ONE tool per response turn. Never batch multiple tool calls in a single turn.
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=[log_model_errors, log_tool_errors],
        )

from contextlib import contextmanager

from dungeon_adventure_agent_connection import InventoryMcpServerClientStrands, log_model_errors, log_tool_errors
from strands import Agent, tool
from strands_tools import current_time
from strands import Agent


@tool
def subtract(a: int, b: int) -> int:
    return a - b


@contextmanager
def get_agent():
    inventory_mcp_server = InventoryMcpServerClientStrands.create()
    with (
        inventory_mcp_server,
    ):
        yield Agent(
            name="StoryAgent",
            description="StoryAgent Strands Agent",
            system_prompt="""
You are a mathematical wizard.
Use your tools for mathematical tasks.
Refer to tools as your 'spellbook'.
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.
IMPORTANT: Only call ONE tool per response turn. Never batch multiple tool calls in a single turn.
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=[subtract, current_time, *inventory_mcp_server.list_tools_sync()],
            tools=[*inventory_mcp_server.list_tools_sync()],
            hooks=[log_model_errors, log_tool_errors],
        )

agent.py rimuove lo strumento di esempio subtract e sostituisce il prompt di sistema con uno da dungeon-master che invita il primo messaggio dell’utente a dichiarare il nome del giocatore e il genere, e utilizza gli strumenti del server MCP Inventory. main.py non necessita di modifiche qui — la gestione delle sessioni era già configurata quando l’agente è stato generato.

Task 2: Testare l’agente localmente

Compilare il codice

Per compilare il codice:

pnpm build

yarn build

npm run build

bun build

Se riscontri errori di lint, esegui il seguente comando per correggerli automaticamente.

pnpm lint

yarn lint

npm run lint

bun lint

Chattare con l’agente

Il target generato agent-chat apre un REPL interattivo contro il tuo agente. Viene eseguito in modo autonomo e si connette al tuo agente in esecuzione locale, quindi prima avvia il server locale dell’agente in un terminale:

pnpm nx agent-dev story

yarn nx agent-dev story

npx nx agent-dev story

bunx nx agent-dev story

Quindi, in un secondo terminale, avvia la chat:

pnpm nx agent-chat story

yarn nx agent-chat story

npx nx agent-chat story

bunx nx agent-chat story

Il tuo primo messaggio dovrebbe comunicare all’agente il nome del tuo eroe e il genere (ad esempio: My name is Alice. Start my zombie adventure.) e la storia verrà trasmessa in streaming.

Congratulazioni. Hai costruito e testato il tuo primo agente Strands localmente! 🎉🎉🎉