Agent Network

Core Orchestrator

AgentRuntime in services/characteros/agent_runtime.py is the central orchestrator. It's a singleton (always use get_agent_runtime_singleton() — never instantiate per-request). The runtime imports and manages all 25+ agents, lazy-initializing them on first use to minimize startup time.

Orchestration Patterns

Agents communicate through typed contracts, RAG retrieval, and shared memory bridges. Key patterns:

• WriterAgent → ContinuityAgent (3-pass validation)
• CharacterAgent → MemoryBridge (memory persistence)
• AudioSceneAgent → VoiceSelectionAgent (voice mapping)
• DirectorAgent → WriterAgent (mood injection)

Agent Lifecycle

Each agent follows a consistent lifecycle: initialization (lazy on first use), validation (typed contracts at boundaries), telemetry (@traced decorator on all public methods), error handling (CharacterOSError codes), memory persistence (non-blocking MemoryBridge calls).

Production Safety

All agents use sanitize_story_excerpts() when handling RAG results, dump_validated() for response contracts, @traced for telemetry, and BatchEmbeddingService for cached embeddings. Parallel TTS calls are guarded with asyncio.Semaphore(5) to prevent memory exhaustion.

Content Generation (4)

These agents create story content: ReaderAgent answers story questions with RAG, CharacterAgent generates character dialogue locked to canon, WriterAgent creates multi-character scenes (max 5), and NarratorAgent adds narrative framing.

Quality Assurance (4)

These agents validate content: ContinuityAgent checks 5 layers (traits, relationships, timeline, dialogue, spoilers), DialogueQualityAgent scores naturalness, EmotionalBeatAnalyzer tracks character arcs, and ScenePacingOptimizer balances action and dialogue.

Audio & Voice (7)

These agents handle voice and audio production: VoiceSelectionAgent maps character traits to voice DNA, VoiceConfigurationAgent adjusts 300+ voice settings (speed, pitch, emotion), AudioSceneAgent parses dialogue and detects emotion per line, VoiceVault IP-locks voice DNA to projects.

Supporting (8)

These agents provide orchestration and utility: DirectorAgent injects mood and pacing, AtmosphereAgent adds context about setting and tone, CharacterParticipantManager generates character reactions in collaboration sessions.

Evolution & Consensus (2)

These agents enable personality growth: EmotionalArcEvolverAgent computes character evolution from reactions, ConsensusAnalyzerAgent detects when multiple writers describe the same character differently and synthesizes a unified voice.