PowerOn/wiki
3
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
wiki/z-archive/b-reference/automation-business-spec.md
ValueOn AG b66bb51df5 DOcu updated
2026-04-06 00:46:32 +02:00

37 KiB
Raw Blame History

PowerOn Automation Unification — Business Specification

Version: 2.0
Datum: 2026-04-05
Status: Draft

1. Executive Summary

PowerOn enthält heute drei teilweise überlappende Systeme für die Automatisierung von Workflows. Die Ziel-Architektur konsolidiert diese zu einer einheitlichen Platform mit klaren Grenzen zwischen Services, Features und Shared Libraries.

Leitprinzipien:

  • Keine Migration von Altdaten — Automation v1 ist nicht produktiv, wird nicht migriert
  • Automation v1 bleibt bestehen, bis es durch das neue Feature abgelöst ist
  • Klare Datenmodelle mit definierten State Machines als stabile, erweiterbare Grundlage
  • Klare Trennung von Mandant/Feature/Feature-Instanz und zugehöriger RBAC-Logik
  • Skalierbare AI-Tool-Architektur mit Toolboxes und Sub-Agents für 50–100+ Tools

2. Ist-Analyse

2.1 Drei bestehende Systeme

System Modell Stärke Schwäche
Automation v1 Template + Cron + Placeholders Stabiles, bewährtes Scheduling mit Callback-basiertem Sync, inkrementeller Job-Registrierung, Execution-Logs Kein visuelles Editing, kein Branching, starres Template-Modell
Automation2 Graph-Editor (n8n-style) + Run/Task-Modell Visuelles Modellieren, Branching, Loops, Human-in-the-loop, Pause/Resume, diverse Node-Typen Kein AI-Chat im Editor, kein UDB-Zugang, Scheduler-Sync weniger robust als v1
AI Workspace Chat-driven AI Agent mit Tools Natural-language Interaktion, 40+ Core Tools + Action Tools, Streaming, RAG Kein persistiertes Workflow-Modell, kein Scheduling

2.2 Wer nutzt die Method/Action Library?

Die workflows/methods/ Library (methodAi, methodOutlook, methodSharepoint, etc.) ist bereits die de facto gemeinsame Basis. Alle Systeme nutzen ActionExecutor.executeAction():

Consumer Pfad zur Action Library
Workspace AI Agent ActionToolAdapter registriert dynamicMode=True Actions als Agent-Tools → LLM wählt Tool → ActionExecutor
Automation2 Graph Engine ActionNodeExecutor liest _method/_action aus Node-Definition → ActionExecutor
Automation v1 WorkflowProcessor → modeAutomation → ActionExecutor
Workspace Dynamic Mode WorkflowProcessor → modeDynamic → AI plant Tasks → ActionExecutor

2.3 Wer nutzt die AI Tools?

Tool-Typ Registrierung Nutzung
Core Tools (40: readFile, webSearch, sendMail, etc.) _registerCoreTools() Workspace Agent, CommCoach Agent
Action Tools (dynamicMode Actions) ActionToolAdapter.registerAll() Workspace Agent (toolSet-übergreifend)
Graph Node Types (ai.prompt, email.checkEmail, etc.) STATIC_NODE_TYPES in nodeDefinitions/ Automation2 executeGraph

Benötigen die AI Tools die Method/Actions? Ja, direkt. ActionToolAdapter transformiert jede dynamicMode=True Action in ein Agent-Tool. Und die Automation2-Nodes mappen über _method/_action auf dieselbe Library.

2.4 Identifizierte Inkonsistenzen

# Inkonsistenz
I-1 Zwei Datenmodelle: AutomationDefinition (v1) vs Automation2Workflow (v2) — kein gemeinsames Workflow-Konzept
I-2 Zwei Datenbanken: poweron_automation vs poweron_automation2
I-3 Zwei Scheduler: v1 (inkrementell, callback automation.changed) vs v2 (full wipe + re-register, callback automation2.workflow.changed)
I-4 Zwei Execution Engines: WorkflowManager + WorkflowProcessor vs executionEngine.executeGraph
I-5 Kein AI-Chat im Graphical Editor
I-6 WorkspaceInput ist nicht als wiederverwendbare Komponente extrahiert
I-7 UDB nur in Workspace und CommCoach, nicht im Graphical Editor
I-8 AI Tools skalieren nicht: 50+ Tools ohne Gruppierungslogik, alle werden dem LLM gleichzeitig exponiert

3. Ziel-Architektur

3.1 Vier Säulen

┌──────────────────────────────────────────────────────────────────────┐
│                        POWERON UNIFIED PLATFORM                       │
│                                                                       │
│  ┌─────────────┐   ┌──────────────────────┐   ┌──────────────────┐  │
│  │  AI Service  │   │  Graphical Editor     │   │  Automation      │  │
│  │  (Säule 1)   │   │  (Säule 2)            │   │  Scheduler       │  │
│  │              │   │                        │   │  (Säule 3)       │  │
│  │ • AI Gateway │   │ • Visual Flow Builder  │   │                  │  │
│  │ • Agent Loop │   │ • Node Palette         │   │ • Cron Engine    │  │
│  │ • Toolboxes  │   │ • AI Chat Sidebar      │   │ • Event Trigger  │  │
│  │ • Sub-Agents │   │ • UDB Integration      │   │ • Webhook Entry  │  │
│  │ • Streaming  │   │ • Tracing/Debug Log    │   │ • Run History    │  │
│  │ • Failover   │   │ • Test Runner          │   │ • Monitoring     │  │
│  │ • Neutraliz. │   │ • Version Management   │   │ • Notifications  │  │
│  └──────┬───────┘   └──────────┬─────────────┘   └────────┬─────────┘  │
│         │                      │                           │            │
│  ┌──────▼──────────────────────▼───────────────────────────▼─────────┐  │
│  │             SÄULE 4: UNIFIED ACTION LIBRARY (Toolboxes)           │  │
│  │                                                                    │  │
│  │  Toolbox "ai"        │ Toolbox "email"       │ Toolbox "files"    │  │
│  │  ─────────────       │ ──────────────        │ ──────────────     │  │
│  │  ai.process          │ outlook.readEmails    │ context.extract    │  │
│  │  ai.webResearch      │ outlook.searchEmails  │ context.neutralize │  │
│  │  ai.summarize        │ outlook.draftEmail    │ file.create        │  │
│  │  ai.translate        │ outlook.sendDraft     │ context.transform  │  │
│  │  ai.generate         │                       │                    │  │
│  │                      │                       │                    │  │
│  │  Toolbox "sharepoint"│ Toolbox "clickup"     │ Toolbox "jira"     │  │
│  │  ─────────────────── │ ──────────────        │ ─────────────      │  │
│  │  sharepoint.findDoc  │ clickup.searchTasks   │ jira.connect       │  │
│  │  sharepoint.readDocs │ clickup.createTask    │ jira.exportTickets │  │
│  │  sharepoint.upload   │ clickup.updateTask    │ jira.importTickets │  │
│  │  ...                 │ ...                   │ ...                │  │
│  │                                                                    │  │
│  │  Toolbox "trustee"   │ Toolbox "chatbot"     │ [future toolboxes] │  │
│  │  ──────────────────  │ ──────────────        │                    │  │
│  │  trustee.extract     │ chatbot.queryDB       │ slack.sendMessage  │  │
│  │  trustee.process     │                       │ teams.postChannel  │  │
│  │  trustee.syncAcctng  │                       │ google.readDrive   │  │
│  └───────────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────────┘

3.2 Säule 1: AI Service (besteht, zu erweitern um Toolbox-Architektur)

Status: Kern bereit (serviceAi + serviceAgent + aicore).

Erweiterung: Toolbox-Architektur für 50–100+ Tools → siehe Abschnitt 5.

3.3 Säule 2: Graphical Editor (Feature "graphicalEditor")

Status: Basis vorhanden (Automation2FlowEditor), zu erweitern.

Funktionalität:

  1. Visual Flow Builder (besteht): Canvas, Nodes, Connections, Branching, Loops
  2. Node Palette (besteht): Abgeleitet aus Toolbox-Registry — jede Toolbox-Action kann als Node exponiert werden
  3. AI Chat Sidebar (neu): Agent mit Toolbox "workflow" für Graph-Manipulation
  4. UDB Integration (neu): UnifiedDataBar im Editor
  5. Tracing/Debug Log (zu erweitern): RunStepLog mit Input-Snapshot, Duration, Error pro Node
  6. Test Runner (zu erweitern): Visual Highlighting, Step-by-Step, AI-assisted Debugging
  7. Version Management (neu): Draft/Published Lifecycle

3.4 Säule 3: Automation Scheduler (zu konsolidieren)

Status: v1-Scheduling hat bewährte Patterns, die direkt in v2 übernommen werden.

Von v1 übernehmen:

  • Inkrementeller Sync (nur geänderte Jobs registrieren/entfernen, nicht full wipe)
  • Persistierter Job-Handle (eventId) auf dem Workflow für Debugging
  • automation.changed Callback-Pattern für reaktive Synchronisation
  • Handler lädt Workflow neu und prüft active vor Execution
  • Execution-Logs als Audit Trail (capped auf 50 Einträge)
  • Creator-User Tracking via sysCreatedBy für Execution-Kontext

Von v2 beibehalten:

  • IntervalTrigger für einfache Wiederholungen
  • Main-Loop-Bridging (call_soon_threadsafe) für Thread-Safety
  • Delayed Startup Sync (5s) für DB-Readiness
  • Striktes Cron-Parsing (5/6 Felder)

3.5 Säule 4: Unified Action Library mit Toolboxes

Status: Infrastruktur besteht (workflows/methods/ + methodDiscovery + ActionExecutor). Zu erweitern um Toolbox-Konzept.

→ Detailliert in Abschnitt 5.

4. Mandant/Feature/RBAC-Architektur

4.1 Hierarchie

System (PowerOn Platform)
│
├── System Template Rollen (isSystemRole=true, mandateId=null, featureCode=null)
│   "admin", "user", "viewer"
│   → kopiert bei Mandant-Erstellung via copySystemRolesToMandate()
│
├── Feature Template Rollen (isSystemRole=false, mandateId=null, featureCode=X)
│   "workspace-admin", "workspace-user", "workspace-viewer"
│   "graphicalEditor-admin", "graphicalEditor-user", ...
│   → kopiert bei Feature-Instanz-Erstellung via _copyTemplateRoles()
│
├── Mandant (Tenant)
│   ├── Mandate-Rollen (kopiert von System Templates)
│   │   mandateId=X, featureInstanceId=null, featureCode=null
│   │   "admin", "user", "viewer"
│   │   └── UserMandateRole ← UserMandate ← User
│   │
│   ├── Feature-Instanz A (z.B. "AI Workspace Produktion")
│   │   ├── Feature-Instanz-Rollen (kopiert von Feature Templates)
│   │   │   mandateId=X, featureInstanceId=Y, featureCode="workspace"
│   │   │   "workspace-admin", "workspace-user", "workspace-viewer"
│   │   │   └── FeatureAccessRole ← FeatureAccess ← User
│   │   └── Daten (Workflows, Files, Chats, ...)
│   │
│   ├── Feature-Instanz B (z.B. "Graphical Editor Dev")
│   │   ├── Feature-Instanz-Rollen (kopiert von Feature Templates)
│   │   │   mandateId=X, featureInstanceId=Z, featureCode="graphicalEditor"
│   │   │   "graphicalEditor-admin", "graphicalEditor-user", ...
│   │   └── Daten (Workflows, Runs, Tasks, ...)
│   │
│   └── Feature-Instanz C (z.B. "Trustee Buchhaltung")
│       ├── Feature-Instanz-Rollen
│       └── Daten (Positionen, Belege, ...)
│
└── Feature Catalog (Global)
    ├── Feature "workspace" (code, label, icon)
    ├── Feature "graphicalEditor" (code, label, icon)
    ├── Feature "trustee" (code, label, icon)
    └── ...

4.2 Zwei getrennte Template-Rollen-Systeme

Es gibt zwei getrennte Template-Systeme — diese sind nicht dieselben:

System Template Rollen (für Mandanten)

Feld Wert
isSystemRole true
mandateId null
featureInstanceId null
featureCode null
roleLabel "admin", "user", "viewer"
Kopier-Mechanismus copySystemRolesToMandate() in interfaceBootstrap.py
Ausgelöst bei Mandant-Erstellung
Ziel-Rolle mandateId=X, featureInstanceId=null, isSystemRole=false + kopierte AccessRules

Feature Template Rollen (für Feature-Instanzen)

Feld Wert
isSystemRole false
mandateId null
featureInstanceId null
featureCode z.B. "workspace", "automation2"
roleLabel z.B. "workspace-admin", "workspace-user", "workspace-viewer"
Kopier-Mechanismus _copyTemplateRoles() in interfaceFeatures.py
Ausgelöst bei Feature-Instanz-Erstellung
Ziel-Rolle mandateId=X, featureInstanceId=Y, isSystemRole=false + kopierte AccessRules

Wichtig: Templates werden nur bei Erstellung kopiert. Spätere Änderungen werden nicht automatisch propagiert. (Ausnahme: _syncTemplateRolesToDb() synct neue UI-Objekte auf bestehende Mandate-Rollen mit gleichem roleLabel.)

4.3 RBAC-Resolution (Priority-System)

Rollen-Typ Scope RBAC Priority
Global/Template mandateId=null, featureInstanceId=null 1 (niedrigste)
Mandate-Rolle mandateId=X, featureInstanceId=null 2
Instanz-Rolle mandateId=X, featureInstanceId=Y 3 (höchste)

Resolution:

  1. Lade Mandate-Rollen (via UserMandate → UserMandateRole)
  2. Lade Feature-Instanz-Rollen (via FeatureAccess → FeatureAccessRole)
  3. Lade AccessRules für alle gefundenen Rollen
  4. Höchste Priorität gewinnt bei DATA-Permissions (Instanz schlägt Mandant schlägt Global)
  5. View wird OR-verknüpft über alle Rollen der höchsten Prioritätsstufe
  6. Item-Spezifität innerhalb einer Stufe: exact > prefix > generic

4.3 AccessRule-Kontexte

Kontext Item-Beispiel Prüft
UI ui.feature.graphicalEditor.editor Seitenleiste, Navigation, Buttons
RESOURCE resource.feature.graphicalEditor.execute Ausführungsberechtigungen
DATA Auto-generiert aus Tabellenname + featureCode CRUD auf Datenbank-Ebene

4.4 Feature-Container-Pattern

Jedes Feature folgt einem einheitlichen Container-Pattern:

features/<featureName>/
├── main<FeatureName>.py              ◄── Feature-Definition
│   ├── FEATURE_CODE = "<featureName>"
│   ├── UI_OBJECTS = [...]            ◄── RBAC UI-Objekte
│   ├── RESOURCE_OBJECTS = [...]      ◄── RBAC Resource-Objekte
│   ├── TEMPLATE_ROLES = [...]        ◄── Rollen-Templates mit AccessRules
│   ├── REQUIRED_SERVICES = [...]     ◄── Service-Dependencies
│   ├── registerFeature(catalog)      ◄── Registriert Objekte + synct Rollen
│   └── getFeatureDefinition()        ◄── Katalog-Metadaten
│
├── routeFeature<FeatureName>.py      ◄── FastAPI Router (HTTP)
│   └── router = APIRouter(prefix="/api/<featureName>")
│
├── interfaceFeature<FeatureName>.py  ◄── DB-Interface (CRUD + RBAC)
│   └── getInterface(user, mandateId, featureInstanceId)
│
├── datamodelFeature<FeatureName>.py  ◄── Pydantic-Modelle
│
└── [optional] service<Name>/         ◄── Feature-spezifische Services
    └── mainService<Name>.py

Automatische Discovery: registry.py scannt features/*/routeFeature*.py und features/*/main*.py. Routers werden automatisch gemountet, Features automatisch im Katalog registriert. Kein manuelles Wiring nötig.

5. AI-Tool-Architektur: Toolboxes und Sub-Agents

5.1 Problem: Tool-Explosion

Aktuell werden ~50 Tools dem LLM in einem einzigen Prompt exponiert. Bei 100+ Tools:

  • LLM-Context wird überladen → schlechtere Tool-Auswahl
  • Irrelevante Tools für den aktuellen Kontext → Confusion und Halluzinationen
  • Keine Feature-isolierte Tool-Bereitstellung

5.2 Konzept: Toolboxes

Eine Toolbox ist eine thematisch gebündelte Gruppe von Tools mit einem klaren Scope. Toolboxes ersetzen das bisherige flache _CORE_ONLY_TOOLS-Set.

Toolbox-Registry
│
├── Toolbox "core" (immer verfügbar)
│   ├── readFile, listFiles, searchInFileContent
│   ├── writeFile, deleteFile, renameFile, copyFile
│   ├── listFolders, createFolder, deleteFolder
│   ├── webSearch, readUrl
│   └── detectLanguage, translateText
│
├── Toolbox "ai" (AI-Operationen)
│   ├── summarizeContent, describeImage
│   ├── generateImage, textToSpeech, speechToText
│   ├── renderDocument, createChart, executeCode
│   └── neutralizeData
│
├── Toolbox "datasources" (Externe Verbindungen)
│   ├── listConnections, browseDataSource, searchDataSource
│   ├── downloadFromDataSource, uploadToExternal
│   └── browseContainer, readContentObjects, extractContainerItem
│
├── Toolbox "email" (Outlook-Integration)
│   ├── sendMail
│   └── outlook.readEmails, outlook.searchEmails, outlook.draftEmail
│
├── Toolbox "sharepoint" (SharePoint-Integration)
│   └── sharepoint.findDoc, sharepoint.read, sharepoint.upload, ...
│
├── Toolbox "clickup" (ClickUp-Integration)
│   └── clickup.searchTasks, clickup.createTask, ...
│
├── Toolbox "jira" (Jira-Integration)
│   └── jira.connect, jira.exportTickets, ...
│
├── Toolbox "workflow" (Graph-Manipulation für Editor-Chat)
│   ├── readWorkflowGraph, addNode, removeNode
│   ├── connectNodes, setNodeParameter
│   ├── listAvailableNodeTypes, validateGraph
│   └── listWorkflowHistory, readWorkflowMessages
│
├── Toolbox "trustee" (Feature-spezifisch)
│   └── trustee.extract, trustee.process, trustee.syncAccounting
│
└── Toolbox "chatbot" (Feature-spezifisch)
    └── chatbot.queryDatabase

5.3 Toolbox-Bereitstellung: Initiales Set + dynamische Eskalation

Kern-Idee: Der Agent startet mit einem kompakten, eingeschränkten Tool-Set. Er kennt aber den Katalog aller verfügbaren Toolboxes. Wenn er für eine Aufgabe Spezial-Tools braucht, kann er eine Toolbox anfordern — und bekommt sie in der nächsten Runde bereitgestellt.

Warum nicht alle Tools sofort?

  • Bei 50–100+ Tools wird der LLM-Context überladen → schlechtere Tool-Auswahl
  • Irrelevante Tools führen zu Confusion und Halluzinationen
  • Die meisten Interaktionen brauchen nur 10–15 Core-Tools

Mechanismus: requestToolbox Meta-Tool

Runde 1:
  Tools: core (readFile, webSearch, ...) + requestToolbox
  System-Prompt enthält: "Verfügbare Toolboxes: email, sharepoint, clickup, 
                          jira, workflow, ai, datasources, trustee, ..."
  
  User: "Lies meine letzten Emails und fasse sie zusammen"
  LLM: → requestToolbox("email")  [braucht Email-Tools]

Runde 2:
  Tools: core + email (sendMail, outlook_readEmails, outlook_searchEmails, ...) 
         + requestToolbox
  
  LLM: → outlook_readEmails(connectionRef, folder="Inbox", limit=10)

Runde 3:
  LLM: → (Text-Antwort mit Zusammenfassung)
  → COMPLETED

requestToolbox Tool-Definition:

{
    "name": "requestToolbox",
    "description": "Request additional specialized tools for the current task. "
                   "Call this when you need capabilities beyond your current tools.",
    "parameters": {
        "type": "object",
        "properties": {
            "toolboxId": {
                "type": "string",
                "description": "ID of the toolbox to activate",
                "enum": [...]  # Dynamisch: nur verfügbare Toolboxes
            },
            "reason": {
                "type": "string",
                "description": "Why you need this toolbox"
            }
        },
        "required": ["toolboxId"]
    }
}

AgentConfig:

class AgentConfig(BaseModel):
    maxRounds: int = 25
    maxCostCHF: Optional[float] = None
    initialToolboxes: List[str] = ["core"]    # Initiales Set
    availableToolboxes: List[str] = []         # Was angefordert werden darf
    temperature: Optional[float] = None

Konfiguration pro Feature:

Feature initialToolboxes availableToolboxes (anforderbar)
Workspace ["core"] ["ai", "datasources", "email", "sharepoint", "clickup", "jira", "workflow"] — gefiltert nach User-Connections
Graphical Editor Chat ["core", "workflow"] ["ai"]
CommCoach ["core"] [] (keine Eskalation erlaubt)
Chatbot ["core"] []

Vorteile:

  • Lean Context: Die meisten Chats brauchen nur Core-Tools → schnellere, präzisere Antworten
  • Selbst-navigierend: LLM entscheidet selbst, wann Spezial-Tools nötig sind
  • Kontrolliert: availableToolboxes limitiert, was der Agent anfordern darf (RBAC)
  • Skaliert: 100+ Tools kein Problem — der LLM sieht immer nur was er gerade braucht
  • Transparent: requestToolbox("email", reason="User fragt nach Emails") ist nachvollziehbar im Tracing

Automatische Toolbox-Verfügbarkeit basierend auf Connections: Welche Toolboxes in availableToolboxes erscheinen, hängt von den aktiven User-Connections ab. Hat der User keine Outlook-Verbindung, erscheint "email" gar nicht in der Liste — der Agent kann sie auch nicht anfordern.

5.4 Sub-Agents (Feature Data Agents)

Für datenintensive Features mit eigenem Schema (z.B. Trustee Buchhaltung) existiert bereits das Sub-Agent-Pattern:

User Prompt im Workspace
    │
    ▼
Main Agent (Toolboxes: core, ai, datasources, ...)
    │
    ├── Tool: queryFeatureInstance("trustee", instanceId, question)
    │       │
    │       ▼
    │   Sub-Agent (Feature Data Agent)
    │       Eigene ToolRegistry: browseTable, queryTable
    │       Eigenes System-Prompt mit Schema-Wissen
    │       Limitiert: maxRounds=5, maxCost=0.10 CHF
    │       │
    │       ▼
    │   Antwort zurück an Main Agent
    │
    ├── Tool: readFile(fileId)
    │       (Core Tool, direkt)
    │
    └── Tool: outlook_readEmails(connectionRef)
            (Action Tool, direkt)

Empfehlung: Sub-Agent-Pattern ausweiten auf:

  • Trustee (besteht): browseTable, queryTable auf Buchhaltungsdaten
  • Workflow (neu): Graph-Manipulation als Sub-Agent im Editor-Chat
  • Future Features mit eigenem Datenmodell: Gleicher Pattern

Vorteil: Der Main Agent bleibt schlank. Feature-spezifisches Datenwissen ist im Sub-Agent gekapselt. Der LLM des Main Agents sieht nur ein einzelnes Tool (queryFeatureInstance) statt 10+ tabellenspezifische Tools.

5.5 State Machine: AI Agent Run (mit Toolbox-Eskalation)

                    ┌──────────┐
                    │  IDLE    │
                    └────┬─────┘
                         │ runAgent(prompt, initialToolboxes, availableToolboxes)
                         ▼
                    ┌──────────┐
              ┌────►│ THINKING │◄──────────────────────────────────┐
              │     └────┬─────┘                                   │
              │          │                                          │
              │          ├── LLM Response (Text only) ──────────────┼──► COMPLETED
              │          │                                          │
              │          └── LLM Response (ToolCalls)               │
              │               │                                     │
              │               ▼                                     │
              │     ┌────────────────────┐                          │
              │     │ EXECUTING_TOOLS     │                          │
              │     └────┬───────────────┘                          │
              │          │                                          │
              │          ├── requestToolbox(id) ───┐                │
              │          │                         ▼                │
              │          │              ┌─────────────────────┐     │
              │          │              │ TOOLBOX_ESCALATION   │     │
              │          │              │ Toolbox wird aktiviert│     │
              │          │              │ Tools der nächsten    │     │
              │          │              │ Runde erweitert      │     │
              │          │              └──────────┬──────────┘     │
              │          │                         │                │
              │          ├── Sub-Agent call ───┐   │                │
              │          │                     ▼   │                │
              │          │          ┌──────────────┐│                │
              │          │          │SUB_AGENT_CALL ││                │
              │          │          └──────┬───────┘│                │
              │          │                 │        │                │
              │          ├── Regular tools ─┼────────┼────────────────┘
              │          │   (results → next round)
              │
              │ maxRounds / maxCost reached
              ▼
        ┌──────────┐
        │ COMPLETED │ (oder FAILED / CANCELLED)
        └──────────┘

6. Use Cases

UC-1: Datenquellen einbinden → besteht, keine Änderung

UC-2: AI Workspace mit UDB → besteht, keine Änderung

UC-3: Workflow im Workspace erstellen/bearbeiten

Beschreibung: User beschreibt im Workspace-Chat einen gewünschten Workflow → Agent nutzt Toolbox "workflow" → generiert Graph → speichert als Draft → User öffnet im Graphical Editor.

Voraussetzung: Die "workflow" Toolbox muss im Workspace aktivierbar sein. Die Tools validieren jeden Graph-Mutationsschritt:

  • addNode(type, parameters) → prüft: existiert der Node-Typ? Sind die Parameter valide?
  • connectNodes(source, target) → prüft: sind die I/O-Typen kompatibel? Keine Zyklen?
  • validateGraph() → vollständige Validierung inkl. Trigger-Prüfung

UC-4: AI Chat im Graphical Editor

Beschreibung: Der Graphical Editor hat eine Sidebar mit Chat. Der Agent nutzt Toolbox "workflow" mit speziellem System-Prompt, der den aktuellen Graph kennt. Er kann Nodes hinzufügen, entfernen, umkonfigurieren und den Graph erklären.

Architektur: Gleicher serviceAgent.runAgent() Pfad wie Workspace, aber:

  • Anderes ToolSet: toolboxes: ["core", "workflow"]
  • System-Prompt enthält den aktuellen Graph als Kontext
  • Frontend: Extrahierte ChatBar-Komponente + ChatStream

UC-5: Workflow testen mit Tracing Log

Beschreibung: User klickt "Test Run" → Graph wird ausgeführt → jeder Node wird visuell hervorgehoben (Status-Farben) → Tracing Log zeigt pro Node: Input, Output, Dauer, Fehler.

Bei Fehlern: User bespricht den Fehler im AI Chat → Agent liest den RunStepLog und schlägt Korrekturen vor.

Technisch:

  • RunStepLog pro Node mit Timestamps, Input-Snapshot, Duration, Error-Stack
  • SSE/WebSocket für Live-Updates des Node-Status
  • Run-Modes: "Full Run" und "Step-by-Step" (Pause nach jedem Node)

UC-6: Workflow automatisieren (Scheduler)

Beschreibung: User konfiguriert Schedule im Editor (via trigger.schedule Node oder Invocation) → konsolidierter Scheduler registriert Cron-Job → Run-History wird persistiert → bei Fehlern Notifications.

7. State Machines

7.1 Workflow Lifecycle

                    ┌───────┐
          create ──►│ DRAFT │◄──── edit (neuer graph)
                    └───┬───┘
                        │ publish
                        ▼
                    ┌───────────┐
          unpublish│ PUBLISHED  │◄──── edit → erzeugt neuen Draft,
                │  └───────────┘      Published bleibt aktiv
                │       │
                │       │ archive (manuell oder nach Deaktivierung)
                │       ▼
                │  ┌───────────┐
                │  │ ARCHIVED   │
                │  └───────────┘
                │       │
                └───────┘ re-publish (aus Archiv zurückholen)

Regeln:

  • Ein Workflow hat genau eine published Version (oder keine)
  • Scheduled Runs nutzen immer die published Version
  • Edit erzeugt immer einen neuen Draft — die published Version bleibt stabil
  • Archive ist reversibel

7.2 WorkflowRun Lifecycle

                    ┌─────────┐
     executeGraph──►│ RUNNING  │
                    └────┬────┘
                         │
        ┌────────────────┼────────────────┐
        │                │                │
        ▼                ▼                ▼
   ┌─────────┐    ┌──────────┐    ┌────────┐
   │ PAUSED   │    │COMPLETED │    │ FAILED │
   └────┬────┘    └──────────┘    └────────┘
        │
        │ resume (human task complete / email received)
        │
        ▼
   ┌─────────┐
   │ RUNNING  │ (Weiter ab pausiertem Node)
   └────┬────┘
        │
        ├──► COMPLETED
        ├──► FAILED
        ├──► PAUSED (nächster Input-Node)
        └──► CANCELLED (manuell abgebrochen)

Pause-Gründe:

  • input.* Node → HumanTask erstellt → wartet auf User-Eingabe
  • email.checkEmail → wartet auf neue Email (Background Poller)

7.3 HumanTask Lifecycle

   ┌─────────┐
   │ PENDING  │ (erstellt bei Pause)
   └────┬────┘
        │
        ├── User completes → COMPLETED (Run wird resumed)
        ├── User cancels → CANCELLED (Run wird cancelled)
        └── Timeout → EXPIRED (Run failsafe: cancel oder default)

7.4 Scheduler Job Lifecycle

   ┌─────────────┐
   │ UNREGISTERED │ (Workflow exists, kein Schedule)
   └──────┬──────┘
          │ activate + publish mit schedule invocation
          ▼
   ┌─────────────┐
   │ REGISTERED   │ (APScheduler Job aktiv, eventId gesetzt)
   └──────┬──────┘
          │
          ├── Cron fires → executeGraph → WorkflowRun
          ├── Workflow deactivated → UNREGISTERED (Job entfernt, eventId=null)
          ├── Schedule geändert → Job replaced (replaceExisting=true)
          └── Workflow gelöscht → UNREGISTERED (Job entfernt)

8. Empfehlungen und offene Punkte

8.1 Starke Konzepte (umsetzen)

Konzept Bewertung
Toolbox-Architektur Skaliert von 50 auf 100+ Tools ohne LLM-Überlastung. Klare Isolierung pro Thema.
Sub-Agents pro Feature Bewährtes Pattern (Trustee), erweiterbar. Hält Main Agent schlank.
Validierungs-Layer für Workflow-Modellierung Graph-Mutation nur über validierte Tools. LLM kann keinen inkonsistenten Graph erzeugen.
v1-Scheduling-Patterns in v2 übernehmen Inkrementeller Sync ist robuster als Full-Wipe. Execution-Logs sind essentiell für Audit.
State Machines als Grundlage Klare Zustände, klare Übergänge. Erweiterbar ohne Breaking Changes.

8.2 Was User brauchen, um das als zentrales Arbeitsinstrument zu nutzen

User Need Feature Priorität
Schneller Einstieg Workflow-Templates für häufige Use Cases (z.B. "Email-Attachment → AI Analyse → SharePoint Upload") Hoch
Vertrauen Tracing Log + Test Runner — User muss sehen, was der Workflow tut Hoch
Effizienz AI-gestützte Workflow-Erstellung per Chat Hoch
Fehlertoleranz Retry-Policies, Pause/Resume, klare Fehlermeldungen Hoch
Kontext UDB im Editor — Zugriff auf Files/Sources bei der Konfiguration Hoch
Zusammenarbeit Workflows teilen im Mandant, Rollen-basierter Zugriff Mittel
Monitoring Dashboard: laufende Automationen, nächste Runs, Fehlerrate, Kosten Mittel
Flexibilität Custom Script Nodes (Python-Sandbox), AI Decision Nodes Mittel
Mobile Notifications + Approval-Tasks per Mobile Phase 2

8.3 Offene Architektur-Fragen

Frage Empfehlung
Toolbox-Selektion: statisch oder dynamisch? Hybrid: Basis-Toolboxes pro Feature statisch konfiguriert, Connection-basierte Toolboxes dynamisch aktiviert.
Sub-Agent Tiefe: verschachtelt? Maximal 1 Level tief. Main Agent → Sub-Agent. Kein Sub-Sub-Agent (zu komplex, unkontrollierbar).
Graph-Execution und WorkflowManager: zusammenführen? Nein, getrennt lassen. executeGraph für den Graphical Editor, WorkflowManager bleibt für den dynamischen Workspace-Modus. Verschiedene Orchestrierungsmodelle.
Feature-Code: automation2 → graphicalEditor? Ja, Rename in Phase 1. Klarer Name für User und Entwickler.

9. Phasen-Plan

Phase 1: Foundation

  • Unified Workflow Datenmodell (Workflow + WorkflowVersion + WorkflowRun + RunStepLog + HumanTask)
  • Toolbox-Registry implementieren (Ablösung _CORE_ONLY_TOOLS)
  • ChatBar-Komponente extrahieren
  • Feature Rename: automation2 → graphicalEditor
  • Scheduler konsolidieren (v1 Patterns in v2 Engine)

Phase 2: Editor Enhancement

  • AI Chat Sidebar im Editor (Toolbox "workflow" + Graph-Manipulation-Tools)
  • UDB Integration im Editor
  • WorkflowVersion Lifecycle (Draft/Published)
  • Enhanced RunStepLog + Visual Tracing

Phase 3: Productization

  • Workflow Templates / Marketplace
  • Monitoring Dashboard
  • Retry Policies pro Node
  • Notifications bei Scheduler-Fehlern
  • Automation v1 Feature entfernen (wird nicht mehr benötigt)

Phase 4: Advanced

  • AI Decision Node (ai.decide)
  • Custom Script Node (Python Sandbox)
  • Dynamische Toolbox-Aktivierung basierend auf Connections
  • Sub-Agent Pattern für weitere Features

10. Glossar

Begriff Definition
Toolbox Thematisch gebündelte Gruppe von AI-Tools, die kontextabhängig aktiviert werden
Sub-Agent Spezialisierter Mini-Agent mit eigener Tool-Registry, aufgerufen vom Main Agent
Workflow Persistiertes Automatisierungsmodell mit Graph-Struktur
WorkflowVersion Immutable Snapshot eines Workflow-Graphen (draft, published, archived)
WorkflowRun Einzelne Ausführung einer WorkflowVersion
RunStepLog Detaillierter Log pro Node-Execution innerhalb eines Runs
HumanTask Aufgabe für menschliche Eingabe, erstellt bei Pause eines Runs
Node Ausführungsschritt im Graph (Trigger, Action, Flow-Control, Input/Human)
Method Integrations-Kategorie (z.B. methodOutlook) mit mehreren Actions
Action Spezifische Operation innerhalb einer Method (z.B. outlook.readEmails)
Invocation Entry-Point für einen Workflow (Manual, Schedule, Webhook, Form, Event)
UDB Unified Data Bar — Multi-Tab-Panel für Chats, Files und Sources
ChatBar Wiederverwendbare Prompt-Input-Komponente
Feature Container Einheitliches Verzeichnis-Pattern für ein Feature (main, route, interface, datamodel)