PydanticAI Multi-Agent Text Adventure

A multi-agent AI system that demonstrates advanced agentic AI patterns through a text-based adventure game — because building another chatbot isn't as fun.

Agent Architecture

• IntentParser — Classifies natural language into structured intents
• AdventureNarrator — Orchestrates game flow, delegates to specialist agents
• RoomDescriptor — Generates rich environmental descriptions using RAG (tools: query_world_lore, get_room_connections)
• InventoryManager — Manages item interactions — pickup, drop, examine, use

Key Features

• RAG (Retrieval) — ChromaDB vector store provides dynamic context to agents
• Tool Calling — Context-aware function invocation via @tool decorator patterns
• State Management — Session state tracked and updated across turns
• Save/Load Game — Persistent sessions with Redis (short-term) and PostgreSQL (long-term)
• Error Handling — Graceful degradation with fallback responses

System Architecture

• Frontend: Next.js CLI-style interface with WebSocket integration
• Backend: FastAPI adventure engine and game state manager
• Agents: Typed PydanticAI agents with clear responsibilities and tools
• RAG System: ChromaDB vector store with room descriptions, item details, and world lore
• Memory: Redis for short-term state, PostgreSQL for long-term persistence

Tech Stack

• Backend: FastAPI, PydanticAI, Redis, PostgreSQL
• Frontend: Next.js, React, TypeScript
• AI/ML: PydanticAI, ChromaDB, OpenAI/Google Vertex AI
• Testing: Unit tests for agents, integration tests for orchestration and LLM components
• Infrastructure: Docker Compose, Python 3.11+

The architecture patterns here — intent parsing, orchestration, context preservation, RAG retrieval, and error handling — are applicable well beyond gaming: customer service, automated workflows, intelligent document processing, and more. A text adventure just makes them fun to explore.