LLM Agent Orchestrator

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

Multi-agent AI system for autonomous software development. Role-based orchestration with self-healing outputs.

Audience: AI engineers and developers

Key Features

Role-based multi-agent orchestration
Self-healing JSON output recovery
Persistent virtual file system

Use Cases

Autonomous code generation workflows
Multi-agent collaboration prototyping

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

Parser detects syntax error in Programmer response
Error message constructed with original attempt
Correction prompt sent back to Programmer (no turn increment)
Loop until valid JSON or retry exhaustion
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

Recommended Configs by Role

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

Launch application (desktop/web)
Load default agent config
Check API key environment variables
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

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

Select existing project folder
System creates backup: backup_pre_resume_TIMESTAMP/
Load logs/conversation.log into histories
Inject all files from current/
Add continuity mandate to prompts
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:

Close app/stop server
Delete output/ directory
Verify API key
Start minimal (PM, Architect, Programmer, Consensus)
Test: "Create hello world script"

LLM Agent Orchestrator

Key Features

Use Cases

What is the LLM Agent Orchestrator?

Core Capabilities

System Components

Use Cases

Technical Stack

System Architecture

Core Components

1. AgentSimulation (agent_logic.py)

2. LLM Provider Layer (llm_providers.py)

Data Flow

File System Structure

Communication Protocols

JSON Self-Healing

Agent System

1. Strategist (Konrad) - Optional

2. Project Manager (Klaus)

3. Software Architect (Eva)

4. Programmer (Ben)

5. Bug-Hunter (Findus)

6. Consensus Finder (Judge)

Communication Patterns

Configuration System

Agent Parameters

Recommended Configs by Role

Environment Variables

Best Practices

Simulation Workflow

1. Initialization

2. Configuration

3. Orchestration Loop

4. Multi-Pass Refinement

5. Completion

Project Resume

Troubleshooting Guide

API Issues

Immediate Red Error

Gemini 400 Error

Local LLM Refused

JSON Errors

Infinite Healing Loop

Import Errors

ModuleNotFoundError

Circular Import

Known Limitations