Initial User Prompt
Queue
Idle
No active run
Dependency Gate
No pending install
Approval buttons appear here and in chat when requested
Output
No files yet
Manifest appears after first code delivery
System Ready
Agent Sequence

LLM Agent Orchestrator

Dev / Live
Generative AI SSE Python Django Redis/RQ LLM Agent

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 a Django web interface and Redis Queue worker mode, 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: Architect plan, compact project snapshot, diffs, scratchpad decisions, and runtime constraints are injected before relevant agent turns
  • Project Resume: Browser sessions can reconnect to active jobs; stopped runs keep compact state for controlled continuation

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.11+ runtime RQ/Redis worker queue for hosted runs
Frontend Django templates + static JavaScript UI Django (web)
LLM Integration google-generativeai, openai, anthropic SDKs Local OpenAI-compatible API
Storage File-backed generated projects and logs Redis-backed queue/session limits in RQ mode

Language Scope

Python-first execution: The orchestrator can generate text and files for any language. Python remains the hard automated runtime path for syntax checks, dependency installation, sandbox startup probes, and test discovery. A pluggable validator registry now adds advisory JavaScript, PHP, HTML, and CSS checks when the required local tools are available; unavailable validators are reported as skipped instead of interrupting the run.

Production Queue Runtime

RQ / Redis Browser requests enqueue long LLM runs. A separate worker executes provider calls and validation.
Small Server Profile One active worker keeps Oracle Free Tier stable. Queue size is capped so the service cannot be spammed indefinitely.
Live Status /healthz/ reports service health. /queue_status/ reports active and queued jobs.

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 bounded retry/backoff)
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
│   ├── main.py
│   └── src/
│       ├── __init__.py        # Auto-generated
│       └── main.py
└── versions/                  # HISTORY
    ├── main.py.v001
    └── main.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 retry exhaustion or provider failure

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 limit is reached
  5. Valid JSON → Files saved → Flow continues
⚠️ Critical Detail: JSON healing loop does NOT increment turn counter, preventing downstream agents from reviewing code that was never 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, entry point, interfaces, and import safety Keeps requirements testable and unambiguous
Config Temp: 0.6 | Tokens: 30K | Enabled: True Color: #c6e1f4 (light blue)
Import Safety: Architect and validation gates now prefer explicit entry points, import-safety matrices, and generated-project-only checks. Installed packages in .sandbox_deps are excluded from code review and test discovery.

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": "main.py", "content": "..."},
  {"file_path": "engine.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

  1. Launch the web application
  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 Provider request fails or times out mid-simulation Chat may retry with bounded backoff
Solution Check provider/model access and quota Hosted mode: check queue_status and worker logs Try a known available model from the refreshed dropdown

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 for a local module or third-party dependency
Solution 1. Verify the generated entry point imports local files correctly 2. Check that requirements.txt contains only real third-party packages 3. Approve expected sandbox dependencies when prompted 4. If dependency approval is denied, agents must implement a fallback

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: Binary assets and native GUI dependencies may require explicit requirements, approval, and manual review
  • Large Projects: 50+ files may exceed context. Workaround: Split into modules
  • GUI/game frameworks: Dependencies such as pygame can be installed into .sandbox_deps after approval. Long-running startup probes are treated as acceptable for games and event loops.
⚠️ 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"