Story 에이전트 구현 및 구성

작업 1: Story 에이전트 구현

Story 에이전트는 모듈 1에서 --protocol=ag-ui로 생성된 Strands 에이전트로, UI가 CopilotKit을 통해 Agent-User Interaction protocol로 스트리밍할 수 있습니다. 플레이어의 아이템을 관리하기 위해 Inventory MCP Server를 사용하며, 모듈 1에서 생성기가 프로비저닝한 session.py를 통해 대화 기록을 이미 유지합니다 — 배포되면 이는 Strands의 내장 S3SessionManager가 Game API의 queryActions가 읽는 동일한 S3 버킷에 쓰는 것이므로, 브라우저가 재방문 시 대화 기록을 재구성할 수 있습니다.

에이전트 구현

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


@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는 샘플 subtract 도구를 제거하고 시스템 프롬프트를 던전 마스터 프롬프트로 교체합니다. 이 프롬프트는 첫 번째 사용자 메시지에서 플레이어의 이름과 장르를 명시하도록 유도하며, Inventory MCP Server의 도구를 사용합니다. main.py는 여기서 변경할 필요가 없습니다 — 에이전트가 생성될 때 세션 관리가 이미 연결되어 있었습니다.

작업 2: 로컬에서 에이전트 테스트

코드 빌드

코드를 빌드하려면:

pnpm build

yarn build

npm run build

bun build

린트 오류가 발생하면 다음 명령을 실행하여 자동으로 수정할 수 있습니다.

pnpm lint

yarn lint

npm run lint

bun lint

에이전트와 대화하기

생성된 agent-chat 타겟은 에이전트에 대한 대화형 REPL을 엽니다. 독립적으로 실행되며 로컬에서 실행 중인 에이전트에 연결되므로, 먼저 한 터미널에서 에이전트의 로컬 서버를 시작합니다:

pnpm nx agent-dev story

yarn nx agent-dev story

npx nx agent-dev story

bunx nx agent-dev story

그런 다음 두 번째 터미널에서 채팅을 시작합니다:

pnpm nx agent-chat story

yarn nx agent-chat story

npx nx agent-chat story

bunx nx agent-chat story

첫 번째 메시지는 에이전트에게 영웅의 이름과 장르를 알려야 합니다(예: My name is Alice. Start my zombie adventure.). 그러면 스토리가 스트리밍됩니다.

축하합니다. 첫 번째 Strands 에이전트를 로컬에서 빌드하고 테스트했습니다! 🎉🎉🎉