?

LLM Agent Orchestrator Documentation

Web-deployed multi-agent AI system for autonomous software development with role-based orchestration and self-healing agent outputs.

OVERVIEW
ARCHITECTURE
AGENTS
CONFIGURATION
WORKFLOW
TROUBLESHOOTING

What is the LLM Agent Orchestrator?

A sophisticated multi-agent system for autonomous software development. Built with Python, supporting both Django web interface and CustomTkinter desktop application, it enables teams of specialized AI agents to collaborate on complex coding tasks through a persistent virtual file system.

🎯 Design Philosophy: This system bridges the gap between simple chatbots and complex multi-agent architectures. Each agent has a distinct persona, role, and expertise area, working together through structured communication protocols to produce complete, executable software projects.

Core Capabilities

  • Multi-Agent Collaboration: 6+ specialized agents (Strategist, PM, Architect, Programmer, Bug-Hunter, Consensus Finder)
  • Multi-Provider Support: Google Gemini, OpenAI GPT, Anthropic Claude, and Local LLMs (LM Studio)
  • Virtual File System: Persistent code storage with automatic versioning and history tracking
  • Self-Healing JSON: Automatic retry logic with syntax error recovery for code generation
  • Context Injection: Full codebase automatically loaded into agent context before each response
  • Project Resume: Load existing projects and continue from any checkpoint

System Components

Agent Layer Specialized AI personas with distinct system prompts Temperature and token limits per agent
Orchestration Engine Round-robin speaker rotation Question-based delegation (QUESTION TO syntax) Approval-based progression (APPROVAL trigger)
File System Layer current/ - Active codebase (executable) versions/ - Historical snapshots logs/ - Conversation and configuration history

Use Cases

✅ Ideal For • Proof-of-concept prototypes • CLI tools and automation scripts • Small web applications (Flask, FastAPI) • Educational code examples • Single-file utilities
❌ Not Recommended For • Production-critical systems • Projects requiring compiled languages (C++, Rust) • Complex GUI applications • Projects needing binary assets (images, audio) • Real-time systems with hard deadlines

Technical Stack

Backend Python 3.10+ Threading & Queue for async
Frontend CustomTkinter (desktop) Django (web)
LLM Integration google-generativeai, openai, anthropic SDKs Local OpenAI-compatible API
Storage File-based (no database) JSON for logs/config

System Architecture

Core Components

1. AgentSimulation (agent_logic.py)

Central orchestration engine managing conversation state, chat history, retry logic, JSON validation, and file system operations.

2. LLM Provider Layer (llm_providers.py)

GeminiProvider google-generativeai SDK 1M+ token context
OpenAIProvider openai SDK v1.0+ Most reliable API
AnthropicProvider anthropic SDK Extended context windows
LocalProvider OpenAI-compatible REST http://localhost:1234/v1

Data Flow

1. User Input → Prompt
2. Select Agent (Round-Robin / QUESTION TO)
3. Load Context (Architect plan + current/ files)
4. LLM API Call (with 3-attempt retry)
5. Parse Response (validate JSON if Programmer)
6. Save Files (current/ + versions/)
7. Update UI → Next Turn

File System Structure

output/project_name_20240115_143022/
├── logs/
│   ├── conversation.log      # JSON-lines
│   └── agents.json            # Config snapshot
├── current/                   # EXECUTABLE
│   ├── run.py
│   └── src/
│       ├── __init__.py        # Auto-generated
│       └── main.py
└── versions/                  # HISTORY
    ├── run.py.v001
    └── run.py.v002

Communication Protocols

APPROVAL Consensus Finder signals completion Advances round or ends simulation
QUESTION TO [Role] Delegates to specific agent Example: QUESTION TO Programmer: Fix import
AGENT_FAILURE Retry exhaustion signal Halts after 3 failed attempts

JSON Self-Healing

  1. Parser detects syntax error in Programmer response
  2. Error message constructed with original attempt
  3. Correction prompt sent back to Programmer (no turn increment)
  4. Loop until valid JSON or retry exhaustion
  5. Valid JSON → Files saved → Flow continues
⚠️ Critical Detail: JSON healing loop does NOT increment turn counter, preventing infinite loops where downstream agents get called before code is saved.

Agent System

1. Strategist (Konrad) - Optional

Role Strategic planning and requirement interpretation Creates task checklists with role assignments
Config Temp: 0.8 | Tokens: 8K | Enabled: False Color: #9a9fa0 (gray)

2. Project Manager (Klaus)

Role Converts plan into User Stories Defines domain-specific minimal features Makes fundamental technical decisions
Config Temp: 0.7 | Tokens: 8K | Enabled: True Color: #bb8fcd (purple)

3. Software Architect (Eva)

Role Creates definitive technical design (pure spec, no code) Defines file structure and API signatures Enforces Two-Stage Bootstrap pattern
Config Temp: 0.6 | Tokens: 30K | Enabled: True Color: #c6e1f4 (light blue)
💡 Two-Stage Bootstrap: run.py sets sys.path and calls src.main. All imports use src. prefix. Prevents ImportError.

4. Programmer (Ben)

Role 1:1 implementation of Architect's design Strict JSON output format (enforced)
Config Temp: 0.2 | Tokens: 30K | Enabled: True Color: #53ff79 (green)

JSON Format:

{"files": [
  {"file_path": "run.py", "content": "..."},
  {"file_path": "src/main.py", "content": "..."}
]}

5. Bug-Hunter (Findus)

Role Deep code analysis for logical errors Circular dependency detection Logic cohesion verification
Config Temp: 0.1 | Tokens: 8K | Enabled: True Color: #8cb4df (blue)

6. Consensus Finder (Judge)

Role Final completeness verification Compares planned vs. actual files Blocks approval until 100% complete
Config Temp: 0.7 | Tokens: 8K | Enabled: True Color: #27e0bb (cyan)

Communication Patterns

Round-Robin:
  PM → Architect → Programmer → Bug-Hunter → Consensus
  
Question-Based:
  Bug-Hunter finds error → QUESTION TO Programmer
  Programmer fixes → Back to Bug-Hunter
  Bug-Hunter approves → Continue to Consensus

Configuration System

Agent Parameters

name Display name in UI
internal_name Persona nickname
system_prompt Complete role definition
color Hex code (#RRGGBB)
enabled Boolean toggle
temperature 0.0-1.0 randomness
max_output_tokens 256-32768 max length
Creative Strategist, PM Temp: 0.7-0.8 | Tokens: 4K-8K
Design Architect Temp: 0.5-0.6 | Tokens: 16K-30K
Implementation Programmer Temp: 0.1-0.3 | Tokens: 16K-30K
Analysis Bug-Hunter, Consensus Temp: 0.1-0.2 | Tokens: 4K-8K

Environment Variables

GEMINI_API_KEY ai.google.dev
OPENAI_API_KEY platform.openai.com
ANTHROPIC_API_KEY console.anthropic.com

Best Practices

  • System Prompts: Use ALL-CAPS for critical rules (NEVER, MUST, ALWAYS)
  • Temperature: Code generation: 0.1-0.3, Design: 0.5-0.7, Brainstorming: 0.8-1.0
  • Tokens: 1 token ≈ 4 characters. Account for context overhead
  • Ordering: Architect MUST come before Programmer (plan cached for context injection)
⚠️ Critical: Architect must precede Programmer. System caches Architect's plan as last_architect_plan for injection into Programmer/Bug-Hunter/Consensus contexts.

Simulation Workflow

1. Initialization

  1. Launch application (desktop/web)
  2. Load default agent config
  3. Check API key environment variables
  4. Detect available LLM providers

2. Configuration

User Select provider/model Enter API key Adjust agents Set rounds (1-10)
System Validate API key Update UI dropdowns Initialize logs Prepare queue

3. Orchestration Loop

Round N:
  Turn 1-5: Agents respond in sequence
  
  If APPROVAL → Advance Round / End
  If QUESTION TO → Jump to target agent
  Else → Next agent

4. Multi-Pass Refinement

Pass 1: Programmer delivers → Bug-Hunter finds issue
 Pass 2: Programmer fixes → Bug-Hunter approves
 Pass 3: Consensus checks → Missing file found
 Pass 4: Programmer adds → Consensus → APPROVAL

5. Completion

Success APPROVAL + round limit reached
Pause User clicks Stop
Failure 3 retries exhausted
Error Critical exception

Project Resume

  1. Select existing project folder
  2. System creates backup: backup_pre_resume_TIMESTAMP/
  3. Load logs/conversation.log into histories
  4. Inject all files from current/
  5. Add continuity mandate to prompts
  6. Enter new task or "Continue"
💡 Continuity Mandate: When resuming, prompts include: "This is continuation of existing project. Provided files represent current state. Continue work on this basis. Do NOT reinvent. Respect existing code as Ground Truth."

Troubleshooting Guide

API Issues

Immediate Red Error

Symptom Error immediately on start No agent responses
Solution 1. Verify API key (copy-paste) 2. Check model dropdown 3. Test connection 4. Try different model

Gemini 400 Error

Symptom App freezes mid-simulation Chat stops updating
Solution Desktop: Restart (Ctrl+C) Django: Restart server Prevention: Use OpenAI/Anthropic

Local LLM Refused

Cause LM Studio not running Wrong port (need 1234)
Solution 1. Start LM Studio 2. Verify port 1234 3. Test: curl localhost:1234/v1/models 4. Enter "local" as API key

JSON Errors

Infinite Healing Loop

Cause Model doesn't understand correction Temperature too high
Solution 1. Lower Programmer temp to 0.1 2. Use stronger model (GPT-4, Opus) 3. Simplify project scope

Import Errors

ModuleNotFoundError

Symptom ModuleNotFoundError: No module named 'src'
Solution 1. Check run.py has sys.path setup 2. Verify imports: from src.module import X 3. Check __init__.py exists 4. Run from project root

Circular Import

Cause Module A imports B, B imports A
Solution 1. Trace import chain 2. Use forward refs: def foo(x: 'Class') 3. Move imports inside functions 4. Extract shared code to 3rd module

Known Limitations

  • Binary Assets: Cannot generate images/audio. Workaround: URLs or manual placeholders
  • Large Projects: 50+ files may exceed context. Workaround: Split into modules
  • Complex GUIs: Often incomplete. Workaround: Explicit feature list in prompt
⚠️ Critical Recovery: If broken beyond repair:
  1. Close app/stop server
  2. Delete output/ directory
  3. Verify API key
  4. Start minimal (PM, Architect, Programmer, Consensus)
  5. Test: "Create hello world script"

Copyright © 2026 Dr. Felix Sébastien Bourier. All rights reserved.