Workflows anlegen und ausführen

Admin

Workflows sind admin-definierte, deterministische Schritt-Pipelines: eine feste Abfolge von Schritten, die Daten einliest, umwandelt und ablegt — zum Beispiel „Rechnungs-Postfach lesen → Zahlungsdaten extrahieren → Mensch prüft → SEPA-Datei schreiben”. Verwaltet werden sie in der Administration im Bereich Workflows; der Bereich ist ausschließlich für Administratoren sichtbar. Endbenutzer haben keine Workflow-Oberfläche.

Workflow oder Agent?

Ein Agent arbeitet frei: Er bekommt einen Auftrag und entscheidet selbst, welche Werkzeuge er in welcher Reihenfolge einsetzt. Ein Workflow ist das Gegenteil — eine deterministische Pipeline, in der jeder Schritt einen genau definierten Input und Output hat und die Reihenfolge feststeht. Das macht Läufe wiederholbar, prüfbar und vollständig protokollierbar. Beides lässt sich kombinieren: Der Schritt-Typ agent.run beauftragt einen bestehenden Agenten als einen Knoten innerhalb der Pipeline. → Agenten-Modell

Einen Workflow anlegen — drei Wege

Der Editor bietet drei gleichwertige Wege zur selben Definition; rechts zeigt eine SVG-Pipeline-Ansicht den Ablauf schreibgeschützt an, und der Validieren-Button prüft die Definition jederzeit vorab.

Weg 1: Per Assistent beschreiben

Im Generator-Feld den gewünschten Ablauf in natürlicher Sprache eintippen („Lies ungelesene Mails aus dem Rechnungspostfach, extrahiere die Zahlungsdaten und schreibe eine SEPA-Datei”) — der Assistent erzeugt daraus einen Entwurf als Schritt-Liste. Folge-Prompts verfeinern die bestehende Definition („füge vor dem Schreiben einen Review-Schritt ein”). Erzeugt der Assistent ausnahmsweise einen ungültigen Entwurf, landet dieser mit einer Fehlerliste im JSON-Tab, wo er von Hand korrigiert werden kann.

Weg 2: Im Schritt-Editor bauen

Jeder Schritt ist eine Karte mit Typ und Konfiguration; die Reihenfolge wird über Pfeil-Schaltflächen geändert. Dazu kommen:

Eingaben (Inputs) — benannte Parameter des Workflows mit Typ, Pflicht-Kennzeichen und optionalem Standardwert. Sie bilden das Formular beim manuellen Start und den erwarteten JSON-Body beim Webhook.
Fehlerverhalten je Schritt — fail (Lauf schlägt fehl, Standard), continue (weiter mit dem nächsten Schritt) oder fallbackStep (Sprung zu einem benannten Schritt); dazu optional Wiederholungen (1–5 Versuche mit Wartezeit).

Weg 3: JSON-Tab für Experten

Der JSON-Tab zeigt die vollständige Definition als JSON und eignet sich für Kopieren, Vorlagen und Feinheiten, die der Karten-Editor nicht abbildet. Es gilt dieselbe Validierung wie überall.

Daten zwischen Schritten

Schritte reichen Daten über Platzhalter weiter, die in Konfigurationsfeldern stehen dürfen:

{{inputs.videoUrl}} — greift auf die Workflow-Eingabe videoUrl zu, z. B. als Argument eines mcp.tool-Schritts.
{{steps.extrahieren.output}} — greift auf den Output des Schritts mit der ID extrahieren zu, z. B. als Kontext im Prompt eines späteren llm.transform-Schritts.

Schritt-Referenz

Typ	Zweck
`llm.transform`	Text per LLM umwandeln (polieren, übersetzen, extrahieren)
`http.request`	Ein konfiguriertes HTTP-API-Tool aufrufen
`file.write`	Ein Artefakt in den Workflow-Ablageordner schreiben
`mail.fetch`	Ein konfiguriertes Postfach deterministisch lesen
`mcp.tool`	Ein Tool eines verbundenen MCP-Servers aufrufen
`agent.run`	Einen bestehenden Agenten beauftragen
`review`	Den Lauf für menschliche Prüfung anhalten

`llm.transform`

Wandelt Eingabetext per LLM um — polieren, übersetzen oder strukturiert extrahieren (mit outputSchema als JSON-Schema für maschinenlesbare Ergebnisse). Personenbezogene Daten werden dabei standardmäßig pseudonymisiert: Das LLM sieht Platzhalter, der Output wird für die Folgeschritte re-identifiziert. Der Schalter bypassPii hebt das für den einzelnen Schritt auf und wird im PII-Audit-Protokoll festgehalten. Konfiguration: prompt, optional model und outputSchema. → PII-Schild

`http.request`

Ruft ein unter Konfigurierte Tools angelegtes HTTP-API-Tool auf und erbt dessen komplettes Sicherheits-Setup (Basis-URL, Authentifizierung, erlaubte Endpunkte). Konfiguration: toolRef (Slug des Tools), method, args. Aufrufe mit Schreib-Wirkung zählen als Schreibschritte (siehe Probelauf). → HTTP-API-Tool einrichten

`file.write`

Schreibt ein Artefakt — etwa eine erzeugte XML- oder Textdatei — in den Workflow-Ablageordner (siehe Grenzen & Betrieb); Pfade außerhalb des Ablageordners werden abgelehnt. Konfiguration: path (relativ), content.

`mail.fetch`

Liest ein unter Konfigurierte Tools angelegtes Postfach deterministisch, ganz ohne LLM. Konfiguration: toolRef (Slug des Postfach-Tools), optional folder, senderFilter, subjectFilter, unreadOnly (Standard: an), maxItems, downloadAttachments (Anhänge landen im Lauf-Unterordner des Ablageordners). Die Optionen markAsRead und archiveFolder verhindern, dass Zeitplan-Läufe dieselben Mails doppelt verarbeiten. → Postfach-Tool einrichten

`mcp.tool`

Ruft ein Tool eines verbundenen MCP-Servers mit festen Argumenten auf — z. B. ein YouTube-Transkript abrufen. Konfiguration: tool (Tool-Name), args, dazu der Haken Nur-Lese-Aufruf (intent: read): Er erklärt den Aufruf als lesend, wodurch er im Probelauf echt ausgeführt wird; ohne den Haken gilt der Aufruf als Schreibschritt. → MCP-Server anbinden

`agent.run`

Beauftragt einen bestehenden Agenten mit einem Prompt und wartet auf dessen Ergebnis. Der Agent arbeitet innerhalb seiner eigenen Werkzeug-Freigaben und Middleware (PII, Dry-Run, Timeout); sein Lauf ist aus der Workflow-Zeitleiste verlinkt. Konfiguration: agentId, prompt, optional timeoutSeconds und scopeOverride. → Einen Agenten anlegen und im Trockenlauf testen

Scope überschreiben (scopeOverride): Ein JSON-Objekt, dessen Felder die gleichnamigen Felder der Agenten-Quelle ersetzen — alle anderen bleiben, wie sie auf der Agentenseite eingestellt sind. Beispiel: {"item": "{{steps.s1.output.datei}}"} lässt einen Arbeitsordner- oder Tresor-Agenten genau diese eine Datei lesen; der Ordner bleibt der eingestellte. Statt eines Objekts geht auch eine einzelne Bindung, die ein Objekt liefert. Ist der Wert kein Objekt, scheitert der Schritt mit Begründung, bevor der Agent startet.
Ordner-Quellen füttern, nicht abfragen: Ein Workflow-Lauf markiert nichts als verarbeitet und verschiebt keine Dateien; „Nur neue Dateien“ ist bei überschriebenem Scope aus, sofern das Override onlyNew nicht selbst setzt. Die Eingabe deshalb gezielt per scopeOverride nennen. → Agenten verketten
Ein Lauf je Schritt: Auch ein Agent mit „Lauf je Datei“ oder „Lauf je Mail“ läuft im Workflow genau einmal.
Ergebnis weitergeben: Der Schritt liefert {agentRunId, status, summary, result}. result enthält das JSON-Ergebnis des Agenten (Ergebnis-Schema auf der Agentenseite) — Folgeschritte binden einzelne Felder mit {{steps.<id>.output.result.<feld>}}. Ohne Ergebnis-Schema ist result leer; dann {{steps.<id>.output.summary}} verwenden. Auch im Probelauf ist result gefüllt.
Workflow aus Beschreibung: Der Generator kennt die vorhandenen Agenten samt Ergebnisfeldern und baut solche Ketten selbst, z. B. „Lies die Rechnung X mit dem Agenten Rechnungen und schreibe den Betrag in eine Datei“.
Hinweis: Workflows sind Administratoren vorbehalten. Ein überschriebener Scope kann einen Agenten auf beliebige Tresor-Ordner, Postfächer oder (Desktop) Plattenordner richten; Tresor-Rechte gelten über „Ausführen als Benutzer“. Die Quelle „Arbeitsordner“ gibt es nur in der Desktop-App.

`review`

Hält den Lauf an und legt ihn einem Administrator zur Prüfung vor — siehe Review-Schritte auflösen. Sinnvoll unmittelbar vor Schreibschritten, wenn davor ein LLM extrahiert oder erzeugt hat.

Sicherheits-Markierungen im Editor

Der Editor markiert riskante Konstellationen direkt an den Schritt-Karten:

Gelber Rahmen/Chip — der Schritt umgeht das PII-Schild (bypassPii). Personenbezogene Daten verlassen das System unpseudonymisiert; jeder solche Aufruf wird auditiert.
Blauer Chip — Schreibschritt: Der Schritt verändert etwas außerhalb des Workflows (Datei, HTTP-Schreibaufruf, schreibendes MCP-Tool).
Rote Warnung — PII-Bypass kombiniert mit einem Nicht-EU-Provider: Personenbezogene Daten würden unpseudonymisiert an einen Anbieter außerhalb der EU gehen. Reaktion: den Bypass entfernen, dem Schritt ein Modell eines EU-Providers zuweisen — oder die Konstellation bewusst und dokumentiert in Kauf nehmen. → Datensouveränität

Ausführen und überwachen

Manueller Start: Der Start-Button öffnet ein Formular, das aus den definierten Eingaben erzeugt wird (Pflichtfelder, Standardwerte).
Probelauf (Dry-Run): Der empfohlene erste Test jedes Workflows. Leseschritte laufen echt; Schreibschritte werden nicht ausgeführt, sondern nur als DryRunSuppressed-Ereignis protokolliert — inklusive dessen, was geschrieben worden wäre. Review-Schritte werden übersprungen (ihr Prüf-Inhalt landet im Protokoll).
Lauf-Liste: Jeder Lauf erscheint mit Status-Badge — Läuft, Wartet auf Review, Erfolgreich, Fehlgeschlagen, Abgebrochen — samt Auslöser und Dauer.
Zeitleiste: Die Detail-Ansicht eines Laufs zeigt je Schritt Start, Ende, Versuche und einen Output-Auszug als Ereignisfolge mit Farbpunkten. Bei agent.run-Schritten ist der Agenten-Lauf direkt verlinkt.
Abbrechen: Ein laufender oder wartender Lauf lässt sich jederzeit abbrechen.

Review-Schritte auflösen (Human-in-the-Loop)

Erreicht ein Lauf einen review-Schritt, pausiert er mit Status Wartet auf Review. Administratoren sehen ein Badge an der Workflows-Kachel der Administration und ein Banner im Workflows-Bereich; zusätzlich geht eine E-Mail-Benachrichtigung an die Administratoren (über die konfigurierte SMTP-Anbindung). Ein pausierter Lauf überlebt einen App- oder Server-Neustart — er wartet, bis jemand entscheidet.

Im Review-Panel stehen die geprüften Daten als Formular (bei strukturierten Ergebnissen), JSON-Ansicht oder Vorschau bereit. Aktionen:

Genehmigen — der Lauf setzt fort; optional vorher einzelne Werte korrigieren (die Korrekturen überschreiben das Ergebnis des geprüften Schritts).
Erneut ausführen mit Anmerkung — wiederholt den geprüften Schritt mit der Anmerkung als Zusatzanweisung, maximal 3-mal je Review; steht nur bei generativen, wiederholbaren Schritt-Typen zur Verfügung (in der aktuellen Version gibt es noch keinen solchen Typ — die Aktion erscheint erst mit künftigen generativen Schritten, z. B. Bild-Erzeugung).
Abbrechen — der Lauf endet mit Status Abgebrochen.

Trigger: Zeitplan und Webhook

Der Trigger-Tab erscheint erst bei gespeicherten Workflows. Unabhängig vom Trigger gilt: Pro Workflow läuft maximal ein Lauf gleichzeitig.

Zeitplan (Cron)

Ein Cron-Ausdruck in UTC (z. B. 0 6 * * 1-5 = werktags 06:00 UTC) startet den Workflow automatisch; der Tab zeigt die nächste Ausführung an, ein Aktiv-Schalter pausiert den Zeitplan ohne ihn zu löschen. Cron-Syntax wie bei Agenten-Triggern. → Einen Cron-Trigger einrichten

Webhook

Externe Systeme (z. B. ein eigenes n8n, ein Git-Server, ein Formular-Backend) starten den Workflow per HTTP:

Im Trigger-Tab ein Token erzeugen. Es wird nur ein einziges Mal angezeigt — sofort in einen Passwort-Manager kopieren; gespeichert wird nur ein Hash.

Den Aufruf einrichten: POST /api/workflows/{id}/trigger mit dem Token im Header X-Workflow-Token und den Workflow-Eingaben als JSON-Body:

curl -X POST https://cw.example.com/api/workflows/<workflow-id>/trigger \
  -H "X-Workflow-Token: <token>" \
  -H "Content-Type: application/json" \
  -d '{ "videoUrl": "https://www.youtube.com/watch?v=…" }'

Antworten: Ein falsches oder fehlendes Token ergibt 401; läuft bereits ein Lauf des Workflows, wird der Aufruf mit 409 abgewiesen und am laufenden Lauf protokolliert.

Token rotieren erzeugt ein neues Token (wieder nur einmal sichtbar) und macht das alte sofort ungültig — alle Aufrufer müssen umgestellt werden.

Grenzen & Betrieb

Ein Lauf pro Workflow: Weitere Auslöser — egal ob manuell, Zeitplan oder Webhook — werden abgewiesen und am laufenden Lauf protokolliert.
Zeitpläne brauchen den Server-Modus (Lizenz). Auf dem Desktop laufen Zeitpläne nur, solange die App geöffnet ist — für Dauerbetrieb den Web-/Server-Modus nutzen (wie bei Agenten). → Web vs. Desktop
Artefakt-Ablage: file.write und Mail-Anhänge landen im Ablageordner aus der Konfiguration Workflows:ArtifactRoot; Standard ist Evanto/CompanyWizard/workflow-artifacts im lokalen App-Daten-Verzeichnis (macOS: ~/Library/Application Support/…, Windows: %LOCALAPPDATA%\…, Linux: ~/.local/share/…). Anhänge werden je Lauf in einem run-<id>-Unterordner abgelegt.
Die Einrichtung der Bausteine — HTTP-API-Tools, Postfächer, MCP-Server, Agenten, SMTP — ist nicht Teil des Workflow-Editors; siehe die verlinkten Artikel.

Beispiel 1: Rechnungs-Postfach → Prüfung → SEPA-Datei

Ziel: Werktags morgens neue Rechnungen aus einem Postfach holen, Zahlungsdaten extrahieren, von einem Menschen prüfen lassen und eine SEPA-Datei ablegen.

Eingaben: keine — alle Parameter stehen fest in der Konfiguration.
Schritt mail.fetch: toolRef auf das Rechnungs-Postfach-Tool, subjectFilter: "Rechnung", unreadOnly an, downloadAttachments an, markAsRead an (verhindert Doppelverarbeitung im Zeitplan-Betrieb).
Schritt llm.transform: Prompt „Extrahiere Empfänger, IBAN, Betrag und Verwendungszweck aus diesen Rechnungen: {{steps.mails.output}}” mit outputSchema für eine Liste von Zahlungsposten. PII-Schild bleibt an — die Pseudonymisierung wird für den nächsten Schritt automatisch aufgelöst.
Schritt review: Der Lauf pausiert; ein Admin prüft die extrahierten Zahlungsdaten im Formular, korrigiert ggf. Beträge und genehmigt.
Schritt file.write: Schreibt die SEPA-Datei (pain.001-XML) aus {{steps.extrahieren.output}} in den Ablageordner.
Trigger: Zeitplan 0 6 * * 1-5 (werktags 06:00 UTC), nach einem erfolgreichen Probelauf aktivieren.

Beispiel 2: YouTube-Import per Webhook

Ziel: Ein externes System meldet eine Video-URL; CompanyWizard holt das Transkript und bereitet es redaktionell auf.

Eingabe: videoUrl (Text, Pflicht).
Schritt mcp.tool: Ruft das Transkript-Tool des angebundenen YouTube-MCP-Servers mit args: { "url": "{{inputs.videoUrl}}" } auf — Nur-Lese-Aufruf ankreuzen.
Schritt llm.transform: Prompt „Poliere dieses Transkript zu einem gut lesbaren Artikel: {{steps.transkript.output}}”.
Schritt llm.transform: Übersetzt den polierten Text („Übersetze nach Deutsch: {{steps.polieren.output}}”).
Trigger: Webhook-Token erzeugen und den Aufrufer mit dem curl-Muster von oben einrichten — Body: { "videoUrl": "…" }.
Test: Erst ein Probelauf mit einer Beispiel-URL, dann der erste echte Webhook-Aufruf.