AI NPC Agent Service

An agent-backed narrative service for a Unity game prototype. It generates evolving world lore, selects events from live game state, produces character dialogue, and exposes a controlled path for blockchain-aware NPC actions through CDP AgentKit.

This service pairs with minitown-ai-game, the Unity client that sends world state and renders the generated events.

Architecture

Unity game state
      |
      v
Flask API ---> LangGraph ReAct agent ---> OpenAI
      |                 |
      |                 +---- CDP AgentKit tools ---> Base
      |
      +---- lore, events, dialogue

Endpoints

• POST /generate_lore evolves narrative context from recent events.
• POST /generate_event selects a structured event using the available characters and locations.
• POST /generate_dialogue creates context-aware NPC dialogue.
• POST /ask exposes the underlying agent for controlled prototype interactions.

All routes require the X-Api-Key header. The shared secret is configured through MY_API_KEY; there is no built-in default.

Run locally

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
python agent.py

Populate .env with OpenAI and CDP credentials plus a strong MY_API_KEY. The default host is loopback-only.

Security and production gaps

• Credentials are loaded from environment variables and excluded from source control.
• Request sizes are bounded, but this remains a prototype—not a hardened public transaction service.
• Production use needs authenticated user identity, per-user authorization, rate limits, spend and tool policies, structured model-output validation, audit logging, and isolated wallets.
• Generated narrative and tool actions should be treated as untrusted until validated.

Status

Completed game/agent integration prototype; not under active development.