Zum Hauptinhalt springen

Automatisierung für Technische Nutzer

Diese Seite ist für Personen gedacht, die mit HTTP, JSON, APIs, Expressions und strukturierter Konfiguration arbeiten. Ziel ist ein mentales Modell, mit dem du im CLYE AI nicht nur einfache Regeln, sondern auch komplexere Automationen zuverlässig bauen kannst.

Mentales Modell​

Eine Automation besteht technisch aus fünf Bausteinen:

  1. Trigger: Wann startet sie?
  2. Trigger-Daten: Welche Daten stehen dem Lauf zur Verfügung?
  3. Condition: Soll dieser Lauf wirklich weitergehen?
  4. Action Tool: Welches Tool wird aufgerufen?
  5. Action Args: Mit welchen Parametern wird das Tool aufgerufen?

Praktisch ist das:

  • WHEN: Trigger
  • IF: JavaScript-Expression
  • THEN: Tool-Aufruf mit vorbereiteten Parametern

Ausführungsmodell​

Technisch läuft eine Automation in dieser Reihenfolge:

  1. Der Trigger erzeugt einen Laufkontext.
  2. Der Lauf stellt Trigger-Daten als event bzw. event.data bereit.
  3. Die Condition wird als JavaScript-Ausdruck ausgewertet.
  4. Wenn die Condition true ergibt, werden die Action-Parameter vorbereitet.
  5. In actionArgs werden {{ ... }}-Ausdrücke ausgewertet.
  6. Danach wird das konfigurierte Tool ausgeführt.
  7. QoS-Regeln bestimmen, ob bei Fehlern wiederholt, parallelisiert oder gestoppt wird.

Wichtig:

  • Eine fehlerhafte Condition stoppt den Lauf nicht mit einem harten Crash, sondern führt dazu, dass die Automation für diesen Lauf als nicht passend behandelt wird.
  • Ein Tool-Fehler ist etwas anderes als eine nicht passende Condition.
  • Für chat/send_message werden auch Rückgaben wie success: false als echter Fehler gewertet.

Trigger-Arten​

Der CLYE AI unterstützt vier Trigger-Arten:

  • Event
  • Zeit
  • HTTP
  • Tool

Event​

Event-Trigger sind der Standard, wenn du auf interne Änderungen reagieren willst.

Typische Filter:

  • type
  • objectId

Zusätzlich kann bei Event-Triggern eine Condition feiner auf event.data prüfen.

Beispiel:

event.data.status == "open" && event.data.priority == "high"

Zeit​

Zeit-Trigger eignen sich für Routinen und periodische Jobs.

Relevante Muster:

  • interval
  • daily
  • weekdays
  • weekly
  • monthly

Die Zeitzone ist konfigurierbar und standardmäßig auf Europe/Berlin gesetzt.

HTTP​

HTTP-Trigger machen eine Automation von außen aufrufbar. Nach dem Speichern bekommt die Automation eine eigene URL mit nicht erratbarem Token.

Unterstützte Methoden:

  • GET
  • POST
  • PUT
  • DELETE

Der Request wird als event.data bereitgestellt:

  • event.data.method
  • event.data.body
  • event.data.query
  • event.data.headers
  • event.data.url

Tool​

Tool-Trigger machen eine Automation selbst zu einem aufrufbaren Baustein. Das ist sinnvoll, wenn:

  • andere Automationen sie wiederverwenden sollen
  • ein Assistent sie als Tool aufrufen soll
  • du größere Abläufe modularisieren willst

Technisch heißt das: Statt auf ein externes Ereignis zu warten, wird die Automation selbst als Tool exponiert.

Das event-Objekt verstehen​

Für Conditions und viele Expression-Auswertungen ist event das zentrale Objekt.

Welche event.type-Werte du im Event-Trigger typischerweise auswählen kannst, welche systemseitigen Typen es gibt und wie externe Typen als external.<type> auftauchen, steht gesammelt unter Event-Typen für Automationen.

Wenn ein echter Event-Trigger vorliegt, enthält event typischerweise mehr als nur data, zum Beispiel:

  • event.id
  • event.type
  • event.timestamp
  • event.data
  • event.metadata
  • event.userId
  • event.objectId
  • event.causedBy
  • event.spaceIds
  • event.sequence
  • event.actorId

Wenn kein voller Event-Datensatz vorliegt, ist mindestens event.data relevant.

Conditions: JavaScript statt Regelsprache​

Conditions sind JavaScript-Ausdrücke, die zu true oder false ausgewertet werden.

Typische Muster:

event.data.amount >= 1000
event.data.customer != null && event.data.customer.tier == "enterprise"
Array.isArray(event.data.items) && event.data.items.some((item) => item.price > 100)

Wichtige Praxisregel:

  • Verwende defensive Checks wie != null, typeof ... == "string" oder Array.isArray(...), wenn Daten optional sein können.

Action Args: statische Werte plus {{ ... }}​

Die Parameter eines Action Tools können statisch sein oder Expressions enthalten. In Strings werden {{ ... }}-Blöcke ausgewertet.

Beispiele:

params:
  title: "Täglicher Bericht"
  source: "{{ event.data.query.source }}"
  summary: "{{ 'Kunde ' + (event.data.body.customerId ?? 'unbekannt') }}"

Das ist wichtig:

  • Die Condition selbst ist ein reiner JavaScript-Ausdruck.
  • In actionArgs werden Werte feldweise vorbereitet.
  • String-Felder können {{ ... }} enthalten.
  • Auch verschachtelte Objekte wie metadata können solche Ausdrücke enthalten.

Action Tools richtig auswählen​

Technisch ruft eine Automation ein Tool auf. In der Oberfläche wählst du es aus der Tool-Liste des Spaces aus.

Praktisch sind Tool-IDs üblicherweise im Format:

  • <toolbox-id>/<tool-name>
  • <mcp-server-id>/<tool-name>

Beispiele:

  • chat/send_message
  • ein Tool aus einem angebundenen MCP-Server

Die Oberfläche hilft beim Auswählen und validiert die Eingaben auf Basis des Input-Schemas des jeweiligen Tools.

chat/send_message als Universalbaustein​

Für viele technische Integrationen ist chat/send_message das flexibelste Start-Tool.

Typische Einsatzfälle:

  • HTTP-Request an einen Assistenten weiterreichen
  • Event-Daten automatisch zusammenfassen lassen
  • Vorprüfung, Klassifikation oder Antwortentwurf auslösen
  • Follow-up-Fragen in bestehende Chats einspeisen

Wichtige Parameter:

  • chatId: in bestehenden Chat schreiben
  • spaceId: neuen Chat im Space starten
  • message: Text oder Nachrichtenobjekt
  • metadata: Zusatzdaten
  • intention: menschenlesbare Beschreibung des Schritts

Faustregel:

  • Nutze spaceId, wenn jeder Trigger einen neuen Vorgang erzeugen soll.
  • Nutze chatId, wenn du denselben Vorgang fortschreiben willst.

Kosten und Effizienz​

chat/send_message ist fachlich oft sehr stark, aber auch der Schritt, der typischerweise echte LLM-Kosten und zusätzliche Laufzeit verursacht.

Darum gilt als technische Best Practice:

  • zuerst mit Condition, Code oder vorgeschalteten Tools prüfen, ob der Fall überhaupt relevant ist
  • zuerst einfache Regeln, Filter, Deduplizierung und Datentransformation ausführen
  • erst dann chat/send_message aufrufen, wenn wirklich Zusammenfassung, Klassifikation, Formulierung oder ein anderer KI-Schritt gebraucht wird

Beispiel:

  • Eine Automation prüft regelmäßig E-Mails oder ein externes System.
  • Code oder Filter entscheiden zuerst, ob es überhaupt neue und interessante Fälle gibt.
  • Nur diese Treffer werden dann per chat/send_message an einen Assistenten gegeben.

HTTP-Trigger als Integrations-API​

Ein HTTP-Trigger kann wie ein kleiner interner Endpoint behandelt werden. Das ist besonders nützlich, wenn du kein vollständiges eigenes Backend bauen willst, aber strukturierte Requests in Automationen einspeisen möchtest.

Einfache Schutzschicht​

Die Trigger-URL enthält bereits einen geheimen Token. Für zusätzliche Absicherung kannst du die Condition als Shared-Secret-Prüfung verwenden.

Beispiele:

event.data.headers.authorization == "Bearer MEIN_SHARED_SECRET"
event.data.headers["x-api-key"] == "MEIN_SHARED_SECRET"
event.data.method == "POST" && String(event.data.headers["content-type"] ?? "").includes("application/json")

Typisches Muster​

  1. Externes System ruft die HTTP-Trigger-URL auf.
  2. Condition prüft Methode, Auth und Pflichtfelder.
  3. chat/send_message oder ein anderes Tool verarbeitet den Request.
  4. Das Ergebnis wird als Tool-Ergebnis im Automationslauf sichtbar.

Eigene Events als Entkopplung​

Ein sehr gutes technisches Muster ist, Erkennung und Reaktion über eigene Events zu trennen.

Das bedeutet:

  1. Eine Automation erkennt etwas technisch oder fachlich.
  2. Sie dispatcht daraus ein oder mehrere klar benannte Events.
  3. Andere Automationen reagieren auf genau diese Events.

Beispiel:

  1. Eine Automation prüft regelmäßig, welche Dateien sich geändert haben.
  2. Für jede Änderung erzeugt sie ein Event wie file.changed.
  3. Andere Automationen reagieren darauf, z. B. mit Indexierung, Benachrichtigung oder chat/send_message.

Warum das oft besser ist:

  • retrybar: Die Schritte sind sauber getrennt und können unabhängig erneut laufen.
  • einfacher: Jede Automation hat nur eine klarere Verantwortung.
  • flexibler: Ein Eingang kann auf mehrere Ziel-Events gemappt werden.
  • erweiterbar: Mehrere Folgeautomationen können auf dasselbe Event reagieren.

Gerade wenn aus einem technischen Polling oder Vergleich mehrere fachliche Fälle entstehen können, ist dieses Muster meist sauberer als eine große monolithische Automation.

Event-Policy und Entdoppelung​

Für Event-Trigger gibt es neben type und objectId noch die Event Policy.

Wichtig ist vor allem:

  • default: jedes passende Event kann einen Lauf auslösen
  • latestPerObject: bei mehreren Events pro Objekt wird nur das neueste verarbeitet

Das ist besonders nützlich bei:

  • Reindexing
  • mehrfachen Statusupdates in kurzer Folge
  • idempotenten Folgeschritten pro Objekt

QoS: Retries, Parallelität, Fehlverhalten​

Für technisch robuste Automationen ist der QoS-Bereich wichtig.

Relevante Felder:

  • qos.maxRetries
  • qos.stopOnFailure
  • qos.maxParallelRuns

Praktische Bedeutung:

  • maxRetries: 0: keine Wiederholung
  • maxRetries > 0: fehlgeschlagene Läufe werden erneut versucht
  • stopOnFailure: true: nach einem endgültigen Fehler stoppt die Kette
  • maxParallelRuns: 1: strikt sequentiell
  • maxParallelRuns > 1: parallele Abarbeitung möglich

Faustregeln:

  • Für API-Aufrufe mit Seiteneffekten lieber konservativ starten.
  • Für reine Lese- oder Analysejobs kann mehr Parallelität sinnvoll sein.
  • Wenn Doppelausführung problematisch ist, zuerst Idempotenz und Event-Policy klären.

YAML als Code pflegen​

Automationen können nicht nur in der UI, sondern auch als Dateien gedacht werden. Im technischen Dateimodell liegt eine Automation als YAML-Datei unter /automations/<name>.yml.

Beispiel:

title: Ticket an Assistenten weitergeben
description: Nimmt HTTP-Requests entgegen und schickt sie an einen Assistenten.

reactions:
  inbound-ticket:
    on:
      http: true
    condition: event.data.method == "POST" && event.data.headers.authorization == "Bearer MEIN_SHARED_SECRET" && event.data.body != null && typeof event.data.body.message == "string"
    run:
      call: chat/send_message
      params:
        spaceId: "11111111-1111-4111-8111-111111111111"
        intention: "Ticket an Assistenten senden"
        message: "{{ 'Neues Ticket: ' + (event.data.body.message ?? '') }}"
        metadata:
          source: "http-trigger"
          ticketId: "{{ event.data.body.ticketId }}"

Wichtige Kurzschreibweisen:

  • run.call wird zu actionTool
  • run.params wird zu actionArgs
  • on.http: true aktiviert einen HTTP-Trigger
  • on.tool: true aktiviert einen Tool-Trigger

Das ist besonders nützlich, wenn du:

  • Automationen versionieren willst
  • Änderungen im Team reviewen willst
  • mehrere ähnliche Automationen reproduzierbar erzeugen willst

Gute technische Muster​

1. Klein anfangen, dann generalisieren​

Zuerst einen klaren Trigger und ein einfaches Tool wählen, danach erst Expressions und Wiederverwendung ausbauen.

Wenn ein Ablauf wächst, ist ein eigener Event-Schritt oft der beste nächste Schnitt.

2. Condition für Routing, nicht für komplette Business-Logik​

Die Condition sollte Läufe grob zulassen oder ablehnen. Komplexe Nutzlastaufbereitung gehört eher in actionArgs oder in das aufgerufene Tool.

Wenn die Vorlogik größer wird, ist ein Code-Schritt meist besser als ein früher LLM-Aufruf. Das spart Kosten und macht das Verhalten stabiler.

3. Nachrichten explizit bauen​

Wenn du chat/send_message nutzt, formuliere im message-Feld bewusst, welche Daten wichtig sind. Externe Rohdaten ungefiltert an einen Assistenten weiterzugeben ist selten die beste Variante.

4. Metadaten mitschreiben​

Zusätzliche Felder in metadata helfen bei Nachvollziehbarkeit und späteren Folgeautomationen.

5. Idempotenz mitdenken​

Wenn derselbe externe Request mehrfach auftreten kann, sollte entweder:

  • die Event-Policy passend gesetzt sein
  • ein bestehender chatId-Pfad verwendet werden
  • oder das Zielsystem Mehrfachläufe tolerieren

6. Technische Erkennung von fachlicher Reaktion trennen​

Wenn eine Automation zunächst nur erkennt, dass etwas passiert ist, sollte sie oft lieber ein eigenes Event dispatchen statt sofort alle Folgeschritte selbst zu erledigen.

Das ist besonders sinnvoll bei:

  • Dateiänderungen
  • Polling von externen Systemen
  • Delta-Abgleichen
  • Mapping von einem Eingang auf mehrere unterschiedliche Reaktionen

Wo die Grenzen liegen​

Automationen sind sehr flexibel, aber kein Ersatz für eine komplette Integrationsplattform.

Ein eigenes vorgeschaltetes Backend ist oft sinnvoll, wenn du:

  • komplexe Authentifizierung brauchst
  • HMAC-Signaturen oder aufwendige Request-Validierung brauchst
  • mehrere externe Systeme zusammenführen willst
  • lange Transformationsketten außerhalb eines Tool-Aufrufs brauchst

In solchen Fällen ist der CLYE AI oft der Orchestrierungs- oder LLM-Schritt, nicht zwingend der einzige Integrationspunkt.

Empfohlene Arbeitsweise​

  1. Trigger-Daten zuerst verstehen.
  2. Condition defensiv formulieren.
  3. Mit einem kleinen Tool-Aufruf starten.
  4. QoS bewusst setzen.
  5. Erst danach Ketten, Wiederverwendung und YAML-Pflege ausbauen.

Kurz gesagt​

Mit dem CLYE AI kannst du technisch anspruchsvolle Automationen bauen, wenn du Trigger, event.data, JavaScript-Conditions, Code-Schritte, eigene Events, templated actionArgs und Tool-Aufrufe sauber zusammendenkst. Für viele Integrationen ist die Kombination aus Vorprüfung per Condition oder Code, Dispatch eigener Fach-Events und chat/send_message nur bei echtem KI-Bedarf der sauberste Einstieg.

Inhalt