Agent System Architecture

Overview

CASYS RPG implements a sophisticated multi-agent architecture that combines LLM-based processing with symbolic reasoning. The system uses a neurosymbolic approach where each agent specializes in specific cognitive functions while working together through a central Story Graph.

System Architecture

graph TD
    subgraph Core System
        SG[Story Graph] --> |Orchestrates| AS[Agent System]
        SG --> |Manages| SM[State Management]
    end

    subgraph Agent System
        AS --> RA[Rules Agent]
        AS --> DA[Decision Agent]
        AS --> NA[Narrator Agent]
        AS --> TA[Trace Agent]
    end

    subgraph State Management
        SM --> CM[Cache Manager]
        SM --> WM[Workflow Manager]
    end

    RA --> |Validates| SM
    DA --> |Updates| SM
    NA --> |Reads| SM
    TA --> |Monitors| SM

Core Components

Story Graph

Central Orchestrator

The Story Graph acts as the central nervous system, coordinating all agents and managing the game's workflow.

• Key Features
  • Workflow orchestration
  • Parallel processing
  • State management
  • Error handling

Rules Agent

Rule Engine

The Rules Agent validates game mechanics and ensures consistency of actions.

• Key Features
  • Rule validation
  • Constraint checking
  • Game mechanics
  • State validation

Decision Agent

Decision Processor

The Decision Agent analyzes player choices and determines outcomes using LLM-based processing.

• Key Features
  • Choice analysis
  • Outcome determination
  • LLM integration
  • Rule compliance

Narrator Agent

Content Generator

The Narrator Agent manages content generation and presentation.

• Key Features
  • Content generation
  • Text formatting
  • Style management
  • Narrative consistency

Trace Agent

System Monitor

The Trace Agent handles logging, monitoring, and analytics.

• Key Features
  • Event logging
  • Analytics
  • Monitoring
  • Debugging

Communication Flow

sequenceDiagram
    participant U as User
    participant SG as Story Graph
    participant AG as Agents
    participant ST as State

    U->>SG: Action

    par Agent Processing
        SG->>AG: Process Rules
        SG->>AG: Generate Content
        SG->>AG: Make Decision
    end

    AG-->>SG: Results
    SG->>ST: Update State
    SG->>U: Response

Implementation Details

Protocol-Based Design

The system uses protocols for agent interfaces:

class AgentProtocol(Protocol):
    """Base protocol for all agents."""

    async def initialize(self) -> None:
        """Initialize agent resources."""
        ...

    async def process(self, context: Context) -> Result:
        """Process agent-specific logic."""
        ...

State Management

State is managed immutably:

class GameState(BaseModel):
    """Immutable game state."""

    section: int
    context: Dict[str, Any]
    history: List[Event]
    metadata: Dict[str, Any]

Best Practices

1. Agent Design
2. Single Responsibility Principle
3. Protocol-based interfaces
4. Immutable state

5. Error boundaries

6. Communication

7. Async processing
8. Type safety
9. Error handling

10. State validation

11. Performance

12. Parallel execution
13. State caching
14. Resource management
15. Memory efficiency

Neurosymbolic Integration

The system combines:

1. Neural Components
2. LLM-based processing
3. Pattern recognition
4. Natural language understanding

5. Content generation

6. Symbolic Components

7. Rule systems
8. State machines
9. Logic validation
10. Structured data

This hybrid approach provides:

• Rich reasoning capabilities
• Natural language interaction
• Rule-based consistency
• Structured workflow

Workflow Generation

The system supports automatic workflow generation:

1. Input Processing
2. Story scripts
3. Game rules

4. Content templates

5. Graph Generation

6. Node creation
7. Edge definition

8. State mapping

9. Agent Integration

10. Role assignment
11. Protocol binding
12. State management