Frankenbot - Multi-Agent Event-Management-System

Ein Flask-basiertes Multi-Agent-System zur Orchestrierung und Verwaltung von KI-Agenten für Event-Management. Entwickelt für den Diversity-Ball Wien 2026.

🎯 Überblick

Frankenbot ist ein intelligentes Event-Management-System, bei dem spezialisierte KI-Agents zusammenarbeiten, um komplexe Event-Organisationsaufgaben zu bewältigen. Ein zentraler Orchestrator koordiniert die Kommunikation zwischen den Agents und delegiert Tasks basierend auf Expertise.

✨ Haupt-Features

🤖 Multi-Agent Orchestrierung

• Orchestrator als zentraler Hub: Alle Agent-Kommunikation läuft über den Orchestrator
• Spezialisierte Agents: Budget Manager, Catering Manager, Location Manager, Program Manager, etc.
• Agent-zu-Agent Kommunikation: Agents können Fragen stellen, Subtasks erstellen und neue Agents vorschlagen
• Dynamische Modellauswahl: 29+ KI-Modelle verfügbar (OpenCode, Anthropic, Ollama)

📋 Task-Management

• Persistente Speicherung: SQLite-Datenbank für Tasks
• Automatische Task-Verarbeitung: TaskBeat verarbeitet Tasks alle 10 Sekunden
• Auto-Cleanup: Löscht completed Tasks automatisch nach 7 Tagen
• Auto-Refresh UI: Tasks-Seite aktualisiert sich automatisch alle 15 Sekunden
• Task-Delegation: Orchestrator analysiert Tasks und weist sie passenden Agents zu
• Status-Tracking: pending → in_progress → completed

💬 Chat-System

• Live-Streaming: Server-Sent Events für Echtzeit-Antworten
• Agent-Auswahl: Chat mit spezifischen Agents oder dem Orchestrator
• Session-basierte History: Kontext bleibt über Konversation erhalten

📧 Email-Integration

• IMAP: Email-Posteingang überwachen
• SMTP: Emails versenden
• Email-to-Task: Automatische Task-Erstellung aus Emails
• Whitelist-System: Nur autorisierte Absender (diversityball.at Domain)
• Intelligente Vorstellung: Neue Absender werden automatisch gebeten sich vorzustellen
• Team-Member Lernsystem: Orchestrator baut automatisch Wissensdatenbank auf

📁 Datei-Management

• Agent Work-Folders: Jeder Agent hat eigenes Arbeitsverzeichnis
• Email-Vorlagen: Wiederverwendbare Email-Templates
• Projekt-Dateien: Zentrale Dokumentenverwaltung
• Upload & Download: Web-basierter Datei-Manager

🧠 Memory-System

• JSON-basierte Erinnerungen: Strukturierte Agent-Memories
• Kategorien: tasks, notes, decisions, contacts
• Agent-spezifisch: Jeder Agent verwaltet eigene Erinnerungen
• Memory-Summaries: Kompakte Übersichten für Prompts

📚 Wissensdatenbank

• On-Demand Zugriff: Agents nutzen @READ_KNOWLEDGE statt volle KB im Prompt
• Performance-Optimierung: Reduziert Prompt-Größe um ~15KB
• Event-spezifisch: Diversity-Ball Wien 2026 Informationen
• Self-Learning: System lernt automatisch über Team-Members und Verantwortlichkeiten

👥 Team-Management

• Team-Members Datenbank: Reale Mitarbeiter mit Rollen und Verantwortlichkeiten
• Automatisches Lernen: Neue Absender werden erkannt und vorgestellt
• Orchestrator Beat: Prüft alle 30 Minuten Tasks und eskaliert bei Bedarf
• Direkter Kontakt: Orchestrator kann Team-Members per Email/Telegram kontaktieren
• Intelligente Koordination: Weiß wer wofür verantwortlich ist

💬 Telegram-Integration

• Bidirektionale Kommunikation: Nachrichten senden und empfangen
• QR-Code Setup: Einfache Bot-Verbindung über Settings-Seite
• Task-Erstellung: Telegram-Nachrichten werden automatisch zu Tasks
• Antworten: Agent-Responses werden zurück zu Telegram gesendet
• User-Whitelist: Nur autorisierte Telegram-User

🚀 Installation

Voraussetzungen

# Python 3.10+
python --version

# OpenCode CLI (für Agent-Ausführung)
opencode --version

Abhängigkeiten installieren

pip install flask python-dotenv

Email-Konfiguration (Optional)

cp .env.example .env
# .env editieren und Email-Credentials eintragen

📖 Verwendung

App starten

# Foreground
python app.py

# Background (empfohlen)
nohup python app.py > app_output.log 2>&1 &

Die Anwendung läuft dann auf: http://localhost:5000

Agent-Kommandos

Agents können folgende Kommandos in ihren Antworten verwenden:

Frage an Orchestrator

@ASK_ORCHESTRATOR
Question: Wie hoch ist das verfügbare Budget für Catering?
Context: Ich plane das Menü und brauche Budget-Info
@END

Subtask erstellen

@CREATE_SUBTASK
Task: Location-Vertrag prüfen
Requirements: Rechtliche Prüfung der Mietbedingungen
@END

Wissensdatenbank durchsuchen

@READ_KNOWLEDGE
Topic: Budget
@END

Neuen Agent vorschlagen

@SUGGEST_AGENT
Role: Security Manager
Skills: Sicherheitsplanung, Crowd Management
Reason: Für große Events mit 500+ Gästen benötigt
@END

Team-Member kontaktieren

@SEND_EMAIL
To: georg.tschare@signtime.media
Subject: Budget-Freigabe benötigt
Body: Hallo Georg, für das Catering benötigen wir eine Budget-Freigabe...
@END

Team-Member aktualisieren

@UPDATE_TEAM_MEMBER
Identifier: p.dyderski@live.at
TelegramID: 123456789
Responsibilities: System-Administration, 3D-Visualisierung, AI-Agenten, R&D
@END

Neues Team-Mitglied hinzufügen

@ADD_TEAM_MEMBER
Name: Max Mustermann
Role: Marketing Coordinator
Responsibilities: Social Media, Content Creation
Email: max@diversityball.at
@END

🗂️ Projekt-Struktur

frankenbot/
├── app.py                          # Haupt-Flask-App (2900+ Zeilen)
├── agent_config.json               # Agent-Modell-Zuweisungen
├── diversityball_knowledge.md      # Event-Wissensdatenbank
├── email_journal.db                # SQLite-Datenbank (Emails, Tasks, Team-Members)
│
├── agents/                         # Agent-Verzeichnisse
│   ├── orchestrator/
│   │   ├── systemprompt.md
│   │   ├── personality.md
│   │   ├── work/                   # Arbeitsverzeichnis
│   │   └── memory/                 # JSON-Erinnerungen
│   ├── budget_manager/
│   ├── catering_manager/
│   ├── location_manager/
│   └── ...
│
├── templates/                      # HTML-Templates (Jinja2)
│   ├── base.html
│   ├── index.html                  # Dashboard
│   ├── chat.html                   # Agent-Chat
│   ├── orchestrator.html           # Orchestrator-Chat
│   ├── tasks.html                  # Task-Management
│   ├── agents.html                 # Agent-Verwaltung
│   ├── files.html                  # Datei-Manager
│   └── emails.html                 # Email-Interface
│
├── static/
│   └── style.css                   # CSS-Styling
│
└── uploads/                        # Hochgeladene Dateien

🤖 Verfügbare Agents

Agent	Rolle	Verantwortlich für
Orchestrator	Koordinator	Task-Delegation, Agent-Kommunikation
Budget Manager	Finanzplanung	Budget-Tracking, Kostenkalkulation
Catering Manager	Verpflegung	Menüplanung, Catering-Koordination
Location Manager	Veranstaltungsort	Raumbuchung, Logistik
Program Manager	Programmablauf	Zeitplanung, Ablaufkoordination
Researcher	Recherche	Web-Recherche, Informationsbeschaffung
Document Editor	Dokumentation	Dokument-Erstellung, Bearbeitung
Tax Advisor	Steuern	Steuerliche Beratung, AKM-Meldungen
Musik Rechte Advisor	Musikrechte	GEMA/AKM-Compliance
Zusammenfasser	Synthese	Informations-Aggregation

🔧 Technologie-Stack

• Backend: Flask 3.x
• Frontend: Bootstrap 5, Vanilla JavaScript
• Database: SQLite (Email-Journal, Tasks, Team-Members)
• AI: OpenCode CLI (Multi-Provider Support: Anthropic, Ollama, etc.)
• Templates: Jinja2
• Streaming: Server-Sent Events (SSE)
• Bot: python-telegram-bot, QR-Code Generation

🎨 UI-Routen

Route	Beschreibung
/	Dashboard - Agent-Übersicht & letzte Tasks
/chat	Chat mit individuellen Agents
/orchestrator	Orchestrator-Chat mit Task-Verteilung
/tasks	Task-Management mit Auto-Refresh
/agents	Agent-Verwaltung (Erstellen, Bearbeiten, Modell-Auswahl)
/files	Datei-Manager (Upload, Download, Agent Work-Folders, View)
/emails	Email-Interface (Senden, Empfangen, Vorlagen)
/settings	System-Einstellungen, Telegram QR-Code, Poller-Konfiguration

⚙️ Konfiguration

Agent-Modelle anpassen

Bearbeite agent_config.json:

{
  "orchestrator": "anthropic/claude-3.7-sonnet",
  "budget_manager": "opencode/qwen2.5-coder:32b",
  "catering_manager": "anthropic/claude-3.5-sonnet"
}

Email-Setup

Bearbeite .env:

EMAIL_ADDRESS=your@email.com
EMAIL_PASSWORD=your_app_password
EMAIL_IMAP_SERVER=imap.gmail.com
EMAIL_SMTP_SERVER=smtp.gmail.com

Telegram-Konfiguration

Bearbeite .env:

TELEGRAM_BOT_TOKEN=your-bot-token-here
TELEGRAM_ALLOWED_USERS=123456789,987654321
TELEGRAM_BOT_USERNAME=your_bot_name_bot

Setup-Anleitung:

1. Erstelle Bot via @BotFather
2. Hole deine User-ID via @userinfobot
3. QR-Code scannen auf /settings Seite

Background-Threads

• EmailPoller: Prüft alle 2 Minuten auf neue Emails
• TaskBeat: Verarbeitet Tasks alle 10 Sekunden
• TaskWorker: Führt Agent-Tasks aus (Timeout: 10 Min)
• OrchestratorBeat: Prüft alle 30 Minuten auf blockierte Tasks ⭐ NEU
• TelegramBot: Polling für Telegram-Nachrichten (wenn konfiguriert)

📊 Performance

Optimierungen

• ✅ Wissensdatenbank nicht im Prompt (on-demand via @READ_KNOWLEDGE)
• ✅ Model-Cache (1h TTL)
• ✅ Agent arbeiten in eigenen work-Verzeichnissen
• ✅ Timeout: 600 Sekunden (10 Min) für komplexe Tasks
• ✅ Task-Cleanup: Auto-Löschung nach 7 Tagen
• ✅ Persistente Tasks in SQLite-Datenbank
• ✅ Self-Learning Team-Management

Geschätzte Ausführungszeiten

• Einfache Tasks: 30-60 Sekunden
• Komplexe Tasks: 2-5 Minuten
• Research-Tasks: 3-8 Minuten

🔒 Security

Implementierte Maßnahmen

• ✅ XSS-Schutz: HTML-Escaping in allen Templates (orchestrator.html, chat.html)
• ✅ Email-Whitelist: Nur autorisierte Absender (diversityball.at Domain)
• ✅ Telegram-Whitelist: Nur autorisierte User-IDs
• ✅ Exception-Handling: Spezifische Exception-Typen mit Logging
• ✅ Request-Validierung: .get() mit Defaults
• ✅ Path Traversal Protection: Agent-Files nur aus eigenem work-Verzeichnis
• ✅ Session-basierte Auth: Flask-Sessions

Empfehlungen für Produktion

• 🔐 HTTPS aktivieren (TLS/SSL)
• 🔐 Secrets in Umgebungsvariablen (nicht in Code)
• 🔐 CSP Headers setzen
• 🔐 Rate Limiting für API-Endpoints
• 🔐 WSGI Server verwenden (Gunicorn, uWSGI)

🐛 Debugging

Logs prüfen

# Echtzeit-Logs
tail -f app_output.log

# Letzte 50 Zeilen
tail -50 app_output.log

# Nach Errors suchen
grep -i error app_output.log

App-Status

# Läuft die App?
ps aux | grep "python3 app.py"

# Port 5000 belegt?
lsof -i :5000

📝 Entwicklung

Code-Quality

• ✅ 72 Funktionen, 29 Routes
• ✅ Keine unused imports
• ✅ Spezifisches Exception-Handling
• ✅ Logging für alle kritischen Operationen

Git-Workflow

# Status prüfen
git status

# Änderungen committen
git add .
git commit -m "feat: neue Funktion"

# Pushen
git push origin main

📚 Weitere Dokumentation

• CHANGES.md - Detaillierte Feature-Implementierungen
• FEATURES.md - Feature-Übersicht
• QUICKSTART.md - Schnellstart-Anleitung
• .env.example - Email-Konfiguration

🎓 Use Cases

Event-Planung

1. Orchestrator empfängt Planungs-Anfrage
2. Erstellt Subtasks für Budget, Location, Catering
3. Agents arbeiten parallel
4. Orchestrator aggregiert Ergebnisse

Email-basierte Tasks

1. Email kommt an (von Whitelist-Absender)
2. EmailPoller erstellt Task
3. TaskBeat weist Task zu passendem Agent
4. Agent arbeitet Task ab und antwortet per Email

Neuer Team-Member (Self-Learning)

1. Email von unbekanntem @diversityball.at Absender
2. System erkennt: "Nicht in Team-DB!"
3. Orchestrator übernimmt automatisch
4. Begrüßt und bittet um Vorstellung (Name, Rolle, Verantwortlichkeiten)
5. Beantwortet auch die eigentliche Anfrage
6. Nutzt @ADD_TEAM_MEMBER zum Speichern
7. Zukünftig: Bessere Koordination durch bekannte Verantwortlichkeiten

Orchestrator Beat Monitoring

1. Alle 30 Minuten: System-Check
2. Findet Tasks ohne Fortschritt (>2h pending)
3. Findet blockierte Tasks (>4h in_progress)
4. Fragt Orchestrator was zu tun ist
5. Orchestrator entscheidet ob Eskalation nötig
6. Bei Bedarf: @SEND_EMAIL an verantwortliches Team-Mitglied

Wissensdatenbank-Abfrage

1. Agent braucht Info (z.B. Budget)
2. Nutzt @READ_KNOWLEDGE Topic: Budget
3. System extrahiert relevante Sektion
4. Agent erhält nur benötigte Informationen

🤝 Mitwirken

Dieses Projekt wurde entwickelt für den Diversity-Ball Wien 2026.

📄 Lizenz

Dieses Projekt ist für internen Gebrauch und Event-Management entwickelt.

---

Version: 2.0.0
Letztes Update: 21. Februar 2026
Status: Production-Ready ✅
Neue Features: Self-Learning Team-Management, Orchestrator Beat, Task-Persistierung, Telegram-Integration