AI Company System — Technische Architektur

Architektur-Diagramm

Das System besteht aus einem zentralen Orchestrator (der einzige nicht-LLM-Prozess), der alle Agent-Instanzen steuert, Nachrichten routet und den globalen State verwaltet.

Datenfluss

Alle Agents kommunizieren nie direkt miteinander. Jede Nachricht läuft über den Orchestrator, der sie in die Message-Queue legt und an den nächsten Agent weiterleitet. Das ermöglicht Logging, Retry-Logik und State-Updates an einer zentralen Stelle.

Kommunikationsrichtungen

Orchestrator

Der Orchestrator ist die einzige nicht-LLM-Komponente. Er ist ein deterministischer Prozess (Python-Script, n8n-Workflow oder Node.js-Service), der:

• Agent-Instanzen startet (API-Calls an LLM-Provider)
• Nachrichten zwischen Agents routet
• Den project_state.json verwaltet und bei jedem Schritt aktualisiert
• Retry-Logik und Error-Recovery steuert
• Parallele Worker-Instanzen managed (Promise.all / asyncio.gather)
• Logs schreibt für jeden Agent-Call (Input, Output, Tokens, Dauer)

orchestrator.config

{
  "llm_provider": "anthropic",
  "default_model": "claude-sonnet-4-5-20250929",
  "ceo_model": "claude-opus-4-5-20251101",
  "max_parallel_workers": 10,
  "max_retry_loops": 2,
  "task_package_size": 5,
  "state_file": "./data/project_state.json",
  "log_dir": "./logs/",
  "researcher_tools": ["web_search", "rag_query"]
}

Agent-Definitionen

Jeder Agent ist eine Konfiguration aus: Rolle, System-Prompt, erlaubten Tools, Input-Schema und Output-Schema. Der Orchestrator instanziiert Agents bei Bedarf.

Project State File

Die zentrale Projektakte. Wird nach jedem Schritt vom Orchestrator aktualisiert. Dient als Single Source of Truth.

project_state.json — Schema

{
  "project_id": "uuid",
  "name": "Projektname",
  "status": "planning | in_progress | review | completed | failed",
  "created_at": "ISO-8601",
  "updated_at": "ISO-8601",

  "plan": {
    "goals": ["..."],
    "non_goals": ["..."],
    "tech_stack": ["..."],
    "constraints": ["..."]
  },

  "phases": [
    {
      "id": 1,
      "name": "Phase 1: Setup",
      "status": "completed | in_progress | pending",
      "depends_on": [],
      "tasks": [
        {
          "id": "task-001",
          "title": "...",
          "complexity": 3,
          "status": "pending | assigned | done | failed",
          "assigned_package": "pkg-001",
          "result": null | { ... },
          "retry_count": 0
        }
      ],
      "packages": [
        {
          "id": "pkg-001",
          "task_ids": ["task-001", "task-002"],
          "total_complexity": 14,
          "worker_status": "pending | running | done | failed"
        }
      ],
      "review": {
        "critic_issues": [],
        "valid_issues": [],
        "integration_ok": null | true | false
      }
    }
  ],

  "decisions_log": [
    { "timestamp": "...", "agent": "ceo", "decision": "...", "reason": "..." }
  ],

  "known_issues": [],
  "total_tokens_used": 0,
  "total_cost_usd": 0.0
}

Message-Format

Jede Nachricht zwischen Orchestrator und Agent folgt einem einheitlichen Schema.

AgentMessage

{
  "message_id": "uuid",
  "timestamp": "ISO-8601",
  "from": "orchestrator",
  "to": "agent_role",
  "type": "task | review | decision | query | result",
  "payload": { ... },
  "context": {
    "project_id": "...",
    "phase_id": 1,
    "relevant_state": { ... }  // komprimierter Ausschnitt
  },
  "metadata": {
    "tokens_in": 0,
    "tokens_out": 0,
    "duration_ms": 0,
    "model": "...",
    "retry": 0
  }
}

Task-Schema

Task-Objekt

{
  "id": "task-001",
  "title": "API-Endpoint für User-Login erstellen",
  "description": "Detaillierte Beschreibung...",
  "acceptance_criteria": ["POST /auth/login", "JWT zurückgeben", "Rate-Limiting"],
  "complexity": 3,          // 1-5 Skala
  "depends_on": ["task-000"], // Abhängigkeiten innerhalb der Phase
  "deliverables": ["code", "tests"],
  "context_files": ["src/auth/"]  // Nur diese Dateien dem Worker geben
}

Komplexitäts-Skala

Projekt-Lifecycle

Status-Transitions

Phasen-Loop (Detail)

Für jede Phase wird folgender Zyklus durchlaufen:

Review-Cycle

Der dreistufige Review-Prozess ist das Qualitäts-Herzstück des Systems:

Error-Recovery

Ohne klare Fehlerbehandlung können Agents in Endlosschleifen landen. Das System definiert strikte Regeln.

Retry-Matrix

Tech-Stack Empfehlungen

Dateistruktur

ai-company-system/
├── config/
│   ├── orchestrator.config.json
│   └── agents/
│       ├── ceo.prompt.md
│       ├── planner.prompt.md
│       ├── project_manager.prompt.md
│       ├── estimator.prompt.md
│       ├── worker.prompt.md
│       ├── critic.prompt.md
│       ├── pragmatist.prompt.md
│       ├── integrator.prompt.md
│       └── researcher.prompt.md
├── src/
│   ├── orchestrator.py          # Hauptprozess
│   ├── agent_runner.py          # LLM-API-Aufrufe
│   ├── state_manager.py         # project_state.json R/W
│   ├── message_router.py        # Nachrichtenverteilung
│   ├── parallel_dispatcher.py   # Worker-Parallelisierung
│   └── error_handler.py         # Retry + Eskalation
├── data/
│   └── projects/
│       └── {project_id}/
│           ├── project_state.json
│           ├── phases/
│           │   ├── phase_1_results.json
│           │   └── phase_2_results.json
│           └── artifacts/        # generierte Dateien
├── logs/
│   └── {project_id}/
│       ├── agent_calls.jsonl     # jeder API-Call
│       └── decisions.jsonl       # CEO-Entscheidungen
├── rag/
│   ├── embeddings.py
│   └── sources/               # Gesetzbücher, Docs etc.
└── README.md

Skalierung

Horizontale Skalierung

• Mehr Worker parallel: Limitiert durch API-Rate-Limits des LLM-Providers (Anthropic: Tier-abhängig, bis zu 4000 RPM)
• Mehrere Projekte gleichzeitig: Jedes Projekt hat eigenen State → Orchestrator kann mehrere Projekte managen
• Verschiedene Modelle pro Rolle: CEO = Opus (teuer, klug), Worker = Sonnet (günstig, schnell), Researcher = Haiku für einfache Lookups

Optimierungshebel

Kosten & Token-Budget

Grobe Kalkulation pro Phase mit 25 Tasks (5 Pakete à 5 Tasks):

AI Company System · Technische Architektur v1.0 · Februar 2026