740 lines
37 KiB
Markdown
740 lines
37 KiB
Markdown
# 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:**
|
||
|
||
```python
|
||
{
|
||
"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:**
|
||
|
||
```python
|
||
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) |
|