PydanticAI Multi-Agent Text Adventure

PythonPydanticAIAI AgentsFastAPINext.jsRAGPostgreSQLRedisChromaDB
Completed

A multi-agent AI system that demonstrates advanced agentic AI architecture patterns through the engaging medium of a text-based adventure game. Rather than building another chatbot, this project showcases how multiple AI agents can collaborate to create a dynamic, context-aware system using the PydanticAI framework.

Agentic AI Capabilities Demonstrated

This project implements a comprehensive set of agentic AI patterns:

Agent Architecture

  • Classification Agent: Intent parsing from natural language with structured outputs
  • Orchestration Agent: Coordinator that delegates to specialist agents
  • Specialist Agents: Domain-specific agents for rooms, inventory, and entities
  • Tool Calling: Context-aware function invocation using @tool decorator patterns

Advanced Features

  • RAG (Retrieval): Vector database provides dynamic context to agents
  • State Management: Session state tracked and updated by agents
  • Multi-Turn Context: Conversation history maintained across sessions
  • Save/Load Game: Persistent game sessions with Redis and PostgreSQL storage
  • Error Handling: Graceful degradation with fallback responses

System Architecture

The system consists of multiple components working together:

  • Frontend: Next.js React application with command-line interface and real-time WebSocket integration
  • Backend: FastAPI server acting as the 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
  • Content: Markdown files containing rich world content

Agent Responsibilities

IntentParser

  • Purpose: Classifies natural language commands into structured intents
  • Tools Available: N/A
  • Pattern: Classification

AdventureNarrator

  • Purpose: Orchestrates game flow, delegates to specialists
  • Tools Available: parse_command, agent delegation
  • Pattern: Orchestration

RoomDescriptor

  • Purpose: Generates rich environmental descriptions using RAG
  • Tools Available: query_world_lore, get_room_connections
  • Pattern: Specialist + RAG

InventoryManager

  • Purpose: Manages item interactions (pickup, drop, examine, use)
  • Tools Available: update_inventory, examine_item
  • Pattern: Specialist

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 and functional pieces, integration tests for orchestration and LLM components
  • Infrastructure: Docker Compose, Python 3.11+

Challenges, Solutions, and Other Remarks

This project was completed as a comprehensive exploration of the PydanticAI framework and modern agentic AI patterns. It demonstrates how to build sophisticated multi-agent systems that can:

  1. Parse Intent: Convert natural language into structured commands
  2. Orchestrate Flow: Route requests to appropriate specialist agents
  3. Maintain Context: Preserve conversation state across multiple turns
  4. Retrieve Knowledge: Dynamically inject relevant context using vector search
  5. Handle Errors: Gracefully degrade when encountering unexpected situations

The architecture patterns shown here are applicable to real-world applications beyond gaming, including customer service bots, automated workflows, and intelligent document processing systems. The choice of a text adventure as the demonstration vehicle makes the complex AI patterns accessible and engaging while showcasing their practical capabilities.

View Project