Durchsuchbare Dokumentation aufrufen | Zurück zur Dokumentationsübersicht

Navigation: Dokumentationen agorum core > agorum core für Entwickler > agorum core workflow 3.0 > Übersicht vorhandener Knoten

KI-Chat 

Interne ID: agorum.ai.chat

Hinweise:

  • Diese Dokumentation bezieht sich auf die aktuellste Version des Plugins agorum core ai. Aktualisieren Sie das hier beschriebene Plugin, um die Dokumentation verwenden zu können.
  • Wenn Sie zusätzlich das Plugin ALBERT | AI agents verwenden, erweitert sich die Funktionalität des Workflow-Knotens. Die Zusatzoptionen sind ebenfalls in dieser Dokumentation beschrieben, jeweils mit dem Hinweis, dass sie nur mit dem Plugin ALBERT | AI agents zur Verfügung stehen.

Mit diesem Knoten sprechen Sie das konfigurierte Sprachmodell an, indem Sie über den Knoten Befehlstexte an die KI senden und Antworten von der KI erhalten. Der Knoten für den KI-Chat kann Ihnen bei vielen Aufgaben helfen, hier einige einfache Beispiele:

Aussehen des Knotens

Verhaltensweise

Erreicht das System den Knoten im Workflow, prüft das System die gesetzten Parameter und sendet die Befehlstexte, die Sie angegeben haben, an die konfigurierte KI. Die KI antwortet in Form eines JavaScript-Objekts in der Datenvariable. 

Angenommen, der Knoten erhält ein Dokument in deutscher Sprache als Input und der KI-Chat-Knoten soll den Inhalt dieses Dokuments übersetzen.  Dann könnten Sie als Befehlstext Folgendes angeben:

Übersetze den Text des Dokuments in die englische Sprache.

Das System erstellt dann eine Anfrage an das KI-Sprachmodell mit dem Textbefehl und dem angehängten Dokument. Das Sprachmodell antwortet mit dem übersetzten Text.

Daten für die KI im Workflow zur Verfügung stellen

Sie haben mehrere Möglichkeiten, im Workflow-Knoten Daten (Texte oder Dokumente) für die KI anzugeben:

Diese Möglichkeiten entsprechen weitgehend der Benutung eines KI-Chat-Fensters wie Sie es kennen. Auch im Chat-Fenster gibt es die Möglichkeit Informationen oder Dateien als Kontext zu hinterlegen, Befehle direkt einzugeben, und Folgebefehle in einem bestehenden Chat mit Historie zu verwenden.

Im Kontext können Sie folgende Variablen verwenden:

Variable Beschreibung
${currentDate:dd.MM.yyyy HH:mm:ssXXX} Einfügen des aktuellen Datums im angegebenen Format
${userFullName} Einfügen des vollständigen Namens (Vorname und Nachname) des aktuellen Benutzers
${userName} Einfügen des Benutzernamens des aktuellen Benutzers
${userLanguageCode} Einfügen der eingestellten Sprache des aktuellen Benutzers
${tool("name-of-tool", {
  "parameter1": [1,2,3],
  "parameter2": {"test":"okay"},
  "parameter3": "test"
})}		 Wenn Sie auch das Plugin ALBERT | AI agents und die KI-Tools verwenden, können Sie ein Tool gezielt über eine Angabe im Kontext einsetzen. Sie benötigen dazu den Namen des Tools und Informationen über die Tool-Parameter. 

Zusammenspiel der Textfelder

Der KI-Chat-Knoten setzt den endgültigen Prompt aus drei Textfeldern zusammen: Pre-Text, Text und Post-Text. Das System verkettet diese drei Felder in genau dieser Reihenfolge zu einem einzigen Prompt-String, der an die KI gesendet wird.

Diese Aufteilung ist besonders nützlich, wenn der eigentliche Text eine Variable ist: Sie können einen festen Einleitungstext als Pre-Text und eine feste Schlussanweisung als Post-Text hinterlegen, während der variable Inhalt im Feld Text steht.

Beispiel:

Ablauf und Historie

Der Chat-Verlauf wird gespeichert und hat folgende Struktur, damit Sie den Ablauf genau nachvollziehen können.

"role": "user"

Die Informationen, die an die KI gesendet werden, sind die Benutzereingabe, in diesem Fall durch den Workflow-Knoten. Sie können sie an der Rolle user erkennen.

   {
       "dateTime": "2025-06-23T12:06:27.520Z",     
       "attachmentsTexts": [
          "Filename: Willkommen.pdf\nuuid: 24e790a0-6c6f-11ef-b01a-00007f000101\nContent of file:\n```Text in deutscher Sprache```"
        ],
        "environment": "chat",
        "role": "user",
        "attachments": [
          "24e790a0-6c6f-11ef-b01a-00007f000101"
        ],
        "text": "Übersetze den Text des Dokuments in die englische Sprache."
      },

 

"role": "assistant"

Zurück erhält das System eine Antwort vom Sprachmodell. Diese Antwort wird ebenfalls in der JSON-Struktur abgelegt und kann in der Historie an der Rolle assistant erkannt werden.

      { 
        "dateTime": "2025-06-23T12:06:31.257Z",    
        "environment": "chat",
        "role": "assistant",
        "text": "Filename: Welcome.pdf\nuuid: 24e790a0-6c6f-11ef-b01a-00007f000101\nContent of file:\n\n```Text in English language```",
        "toolCalls": []
      }

Der Abschnitt toolCalls ist nur relevant, wenn Sie KI-Tools im Workflow-Knoten verwenden. Der Inhalt ist abhängig von den verwendeten Tools. Das folgende Beispiel zeigt die Verwendung des Tools create_image:

        "toolCalls": [
          {
            "name": "create_image",
            "arguments": {
              "size": "1024x1536",
              "apiKey": "your_api_key_here"
            },
            "contextId": "0781031b-1d73-4c24-8b3c-418147ac522e",
            "id": "call_Du7WgnglHZ4vYOA3DIMNI76L"
          }
        ]

 

"role": "system"

Wenn Sie zusätzlich einen allgemeinen Kontext in der KI-Voreinstellung des Sprachmodells hinterlegt hätten bzw. einen Kontext im Workflow-Knoten mitgeben würden, würde diese Information zusammen mit der Benutzeranfrage an die KI übergeben und in der Historie mit der Rolle system gespeichert.

      {
        "dateTime": "2025-06-23T12:06:27.505Z",
        "role": "system",
        "text": "Sei ein Englischübersetzer"
      },

 

"role": "tool"

Wenn Sie nicht nur das Plugin ALBERT | AI einsetzen, sondern auch das Plugin ALBERT | AI agents nutzen und Tools im Workflow-Knoten verwenden, gibt es einen zusätzlichen Abschnitt mit Informationen über die Antworten der KI-Tools. Dieser Abschnitt wird in der Historie mit der Rolle tool aufgeführt. In diesem Beispiel wird ein Fehler vom KI-Tool zurückgegeben.

      {
        "dateTime": "2025-06-23T14:39:21.432Z",
        "toolResponses": [
          {
            "response": {
              "isError": true,
              "content": [
                {
                  "text": "Error creating image",
                  "type": "text"
                }
              ]
            },
            "name": "create_image",
            "id": "call_Du7WgnglHZ4vYOA3DIMNI76L"
          }
        ],
        "environment": "chat",
        "role": "tool"
      },

 

Endpoints

Der KI-Chat-Knoten unterscheidet zwischen einem Default-Outlet und einem inProgress-Outlet. Falls die Verarbeitung durch die KI möglicherweise längere Zeit in Anspruch nimmt, können Sie das inProgress-Outlet verwenden, um abzufragen, ob die Verarbeitung beendet ist.

Standard Veränderbar? Weitere Endpoints möglich?
Default (Inlet) Nein, kann nur ausgeblendet werden. nein, nicht nötig
Default (Outlet) Nein, kann nur ausgeblendet werden. nein, nicht nötig
error (Outlet) Nein, kann nur ausgeblendet werden. nein, nicht nötig
inProgress Nein, kann nur ausgeblendet werden. nein, nicht nötig

Parameter

<
Parameter Beschreibung Beispiel
KI-Voreinstellung Definiert die konfigurierte KI-Voreinstellung, die für den Aufruf genutzt werden soll. Wählen Sie die KI-Voreinstellung in der Auswahlliste aus.  test-ollama
Kontext Definiert den Kontext, den das System an die KI mitgibt.
  • Der Kontext unterstützt die KI dabei, Ihre Befehle und Anweisungen umzusetzen, indem Sie der KI etwa ein bestimmtes Szenario mitgeben.
  • Wenn Sie den Kontext als Datei mitgeben (über den Parameter Kontext-Datei), ignoriert das System diesen Parameter.

Für weitere Informationen siehe Daten für die KI zur Verfügung stellen.

 Sei ein Englischübersetzer.
Kontext-Datei Definiert den Kontext als Datei, d. h. der Kontext steht in der Datei.

Wenn Sie diesen Parameter verwenden, ignoriert das System den Parameter Kontext.

Für weitere Informationen siehe Daten für die KI zur Verfügung stellen.

 Dateien/Demo/Willkommen.pdf
Pre-Text Definiert den Pre-Text, den das System vor dem eigentlichen Text einfügt.

Verwenden Sie den Pre-Text, wenn der eigentliche Text eine Variable ist und davor noch ein fester Text hinterlegt werden soll.

Für weitere Informationen siehe Daten für die KI zur Verfügung stellen.

 Übersetze den Text in die englische Sprache.
Text Definiert den Prompt für die KI, d. h. eine konkrete Anweisung oder Frage.

Für weitere Informationen siehe Daten für die KI zur Verfügung stellen.

 Verwende für die Übersetzung amerikanisches Englisch.
Post-Text Definiert den Post-Text, den das System nach dem eigentlichen Text einfügt.

Verwenden Sie den Post-Text, wenn der eigentliche Text eine Variable ist und dahinter noch ein fester Text folgen soll.

Für weitere Informationen siehe Daten für die KI zur Verfügung stellen.

 Erstelle die Übersetzung als Text ohne Formatierung.
Historienvariable Definiert die Variable, aus der die Historie geladen werden kann.
  • Die Historienvariable ist optional. 
  • Die Variable muss ein Array mit einem Aufbau nach folgendem Muster sein, das aus der Antwort einer KI-Chat-Anfrage übernommen werden kann.
 Siehe Aufbau der Historienvariable
Tools Wenn Sie das Plugin ALBERT | AI agents verwenden (und nicht nur agorum core ai) können Sie KI-Tools im Chat verwenden. Mit ALBERT | AI agents können Sie die mitgelieferten Standardtools benutzen oder eigene Tools erstellen. Wählen Sie die Tools, die Sie im Chat verwenden wollen, in der Auswahlliste aus.  Siehe Tools
API-Time-out Definiert den Zeitraum in Millisekunden, nach welcher Zeit die API die Verbindung zum Service abbricht, wenn das System keine Verbindung zum Service herstellen kann. Wenn Sie nichts angeben, wird der in der KI-Voreinstellung verwendete Wert bzw. der Standardwert verwendet. 6000
Eingangsvariable verwenden Aktiviert
Übergibt die Dokumente der Eingangsvariablen als zusätzlichen Kontext an die KI. Auf diese Art kann die KI Daten von Dokumenten verarbeiten.

Deaktiviert
Übergibt keine Eingangsvariable.		  
Eingangsvariable Für die generelle Schreibweise von Variablen im Editor oder als Expression siehe Schreibweise von Variablen.  
Datenvariable Definiert die Variable, in der das Ergebnis der KI als JavaScript-Struktur enthalten ist.
  • Die Datenvariable ist ein Pflichtfeld.
  • Das Ergebnis enthält die Antwort der KI auf die gesendete Anfrage, die Historie des Chats und extrahierte Informationen, etwa XML, JSON oder sonstigen Code.
  • Über den Parameter Ergebnisfilter kann das in die Datenvariable geschriebene Ergebnis auf einen einzelnen Inhaltstyp reduziert werden.

Für die generelle Schreibweise von Variablen im Editor oder als Expression siehe Schreibweise von Variablen.

 Siehe Datenvariable
Ergebnisfilter Bestimmt, was in die Datenvariable geschrieben wird. Dieser Parameter ist optional.
  • (leer): Schreibt die komplette Ergebnisstruktur in die Datenvariable (Standardverhalten). Volle Abwärtskompatibilität für bestehende Workflows.
  • Text: Schreibt nur den Antworttext der KI (result.text) in die Datenvariable.
  • JSON: Schreibt nur das erste in der KI-Antwort erkannte JSON-Objekt aus result.parsed.json in die Datenvariable.
  • XML: Schreibt nur das erste erkannte XML aus result.parsed.xml in die Datenvariable.
  • Code: Schreibt nur den ersten erkannten Code-Block aus result.parsed.code in die Datenvariable.

Hinweis: Wenn kein passendes Element gefunden wird (z. B. weil die KI kein JSON liefert, obwohl JSON als Filter gesetzt ist), enthält die Datenvariable undefined. Im Fehlerfall (Outlet error) wirkt der Filter nicht,  dort steht die vollständige Fehlerstruktur in der Datenvariable.

Für weitere Informationen siehe Ergebnisfilter im Detail.

 JSON
Rechte Siehe Rechte auf Knoten vergeben  

Tipp: Verwenden Sie die Variablenauswahl, um einen Überblick über alle nutzbaren Variablen zu erhalten.

Aufbau der Datenvariable

Die Datenvariable ist eine JSON-Struktur, die die Antwort der KI auf die Anfrage enthält. Sie hat folgenden Aufbau:

 {
    "finishReason": "stop",
    "tokens": {
      "output": 0,
      "input": 0,
      "total": 0
    },
    "parsed": {
      "code": [],
      "xml": [],
      "json": []
    },
    "text": "<Antwort der KI/Ergebnis>",
    "history": [
      {
        "role": "system",
        "text": "<Kontext aus der KI-Voreinstellung>"
      },
      {
        "attachmentsTexts": [
          "Filename: \nuuid: 24e790a0-6c6f-11ef-b01a-00007f000101\nContent of file:\n`` "
        ],
        "environment": "chat",
        "role": "user",
        "attachments": [
          "24e790a0-6c6f-11ef-b01a-00007f000101"
        ],
        "text": "<Pre-Text Text Post-Text aus der Konfiguration des Workflow-Knotens>"
      },
      {
        "environment": "chat",
        "role": "assistant",
        "text": "<Antwort der KI>",
        "toolCalls": []
      }
    ],
    "toolCalls": []
  }

 

Wert Beschreibung
text Der Abschnitt enthält die Antwort der KI, also das Ergebnis des KI-Chat-Knotens.
history Im Abschnitt history können Sie nachvollziehen, welche Informationen an die KI gesendet wurden und was die Rückgabe der KI war. Dazu enthält die history drei Abschnitte mit unterschiedlichen Werten für role:
  • system: Enthält ggf. einen Kontext, der in der KI-Voreinstellung angegeben ist (Beispiel: firmenweite Terminologie oder Tonalität)
  • user: Enthält den Kontext, den der Benutzer, in diesem Fall der Workflow-Knoten, angegeben hat. In der Regel ist das die Anweisung, was die KI machen soll. Der Kontext kann auch selbst direkt zu verarbeitende Daten enthalten.
  • assistant: Enthält die Antwort der KI.
  • tool: Enthält Informationen zu den Tool-Antworten, wenn Sie agorum ai agents und KI-Tools verwenden.
parsed Enthält automatisch aus der KI-Antwort extrahierte strukturierte Inhalte. Das System erkennt JSON-, XML- und Code-Blöcke in der Antwort und stellt sie als Arrays bereit:
  • parsed.json: Alle erkannten JSON-Objekte als geparste JavaScript-Objekte.
  • parsed.xml: Alle erkannten XML-Fragmente als Strings.
  • parsed.code: Alle erkannten Code-Blöcke als Strings.
tokens Enthält Informationen über die Token-Nutzung des KI-Aufrufs:
  • input: Anzahl der Eingabe-Tokens.
  • output: Anzahl der Ausgabe-Tokens.
  • total: Gesamtanzahl der Tokens.
finishReason Gibt an, warum die KI die Antwort beendet hat. Typische Werte:
  • stop: Die KI hat die Antwort regulär abgeschlossen.
  • toolCalls: Die KI hat einen Tool-Aufruf angefordert (nur mit ALBERT | AI agents).

Hinweis: Wenn Sie den Parameter Ergebnisfilter verwenden, wird nicht die vollständige Struktur, sondern nur der gefilterte Wert in die Datenvariable geschrieben. Für weitere Informationen siehe Ergebnisfilter im Detail.

Aufbau der Historienvariable

Die Historienvariable ist eine optionale Variable, die Sie mitgeben können, um eine vorhergehende Unterhaltung mit der KI zu simulieren. Dadurch erhält die KI zusätzliche Informationen, die sie bei der Antwort berücksichtigt. Die Abschnitte in der Historienvariable entsprechen denen in der Historie, siehe Ablauf und Historie.

Die Historienvariable muss folgenden Aufbau haben:

	 [
      {
        "role": "system",
        "text": "<Simulierter Kontext aus der KI-Voreinstellung>"
      },
      {
        "environment": "chat",
        "role": "user",
        "text": "<Simulierter Pre-Text Text Post-Text aus der vorhergehenden Unterhaltung>"
      },
      {
        "environment": "chat",
        "role": "assistant",
        "text": "<Simulierte vorhergehende Antwort der KI>",
        "toolCalls": []
      }
    ]

Tipp: Sie können den Inhalt des Abschnitts history aus dem Workflow-Log kopieren und für das Erstellen der Historienvariable verwenden.

Hinweis: Wenn Sie den Parameter Ergebnisfilter verwenden, wird nicht die vollständige Struktur, sondern nur der gefilterte Wert in die Datenvariable geschrieben. Für weitere Informationen siehe Ergebnisfilter im Detail.

Ergebnisfilter im Detail

Der Ergebnisfilter ist eine optionale Konfiguration, die bestimmt, welcher Teil der KI-Antwort in die Datenvariable geschrieben wird. Er vereinfacht typische Szenarien, in denen die KI gezielt strukturierte Daten liefern soll und der nachfolgende Workflow direkt damit weiterarbeiten möchte.

Ist der Ergebnisfilter nicht gesetzt (leer), wird wie bisher die komplette Ergebnisstruktur (text, history, parsed, tokens, finishReason, toolCalls) in die Datenvariable geschrieben. Bestehende Workflows sind dadurch vollständig abwärtskompatibel.

Um beispielsweise auf das erste JSON-Objekt in der KI-Antwort zuzugreifen, müssen Sie ohne Filter den Pfad result.parsed.json[0] verwenden.

Wenn Sie einen Ergebnisfilter setzen, wird nur der gefilterte Wert in die Datenvariable geschrieben:

Filterwert Was in die Datenvariable geschrieben wird Entspricht ohne Filter
(leer) Komplette Ergebnisstruktur –
Text Nur der Antworttext der KI result.text
JSON Das erste erkannte JSON-Objekt (bereits geparst) result.parsed.json[0]
XML Das erste erkannte XML-Fragment result.parsed.xml[0]
Code Der erste erkannte Code-Block result.parsed.code[0]

Bei einem Fehler des KI-Aufrufs (result.error ist gesetzt) wirkt der Ergebnisfilter nicht. Die vollständige Fehlerstruktur steht auf dem error-Outlet zur Verfügung, damit Sie den Fehler im Workflow behandeln können.

Liefert die KI kein passendes Element für den gewählten Filter (z. B. kein JSON, obwohl JSON als Filter gesetzt ist), enthält die Datenvariable undefined. Im nachfolgenden Workflow können Sie diesen Fall erkennen und behandeln.

Angenommen, Sie möchten die KI bitten, strukturierte Daten aus einem Dokument zu extrahieren und als JSON zurückzugeben.

Konfiguration des KI-Chat-Knotens:

Ergebnis: Die Datenvariable result enthält direkt das geparste JSON-Objekt, z. B.:

{
  "name": "Max Mustermann",
  "adresse": "Musterstraße 1, 12345 Musterstadt",
  "datum": "2025-06-23"
}

Ohne den Ergebnisfilter müssten Sie im nachfolgenden Workflow über result.parsed.json[0] auf das JSON-Objekt zugreifen.

Verwendung von KI-Tools im Chat

Sie können KI-Tools im Chat verwenden, wenn Sie das Plugin ALBERT | AI agents installiert und lizenziert haben. Mithilfe von Agenten und Tools können Sie etwa Operationen in agorum core ausführen, Suchen im Web durchführen oder Bildverarbeitungsfunktionen nutzen.

 

Generelle Vorgehensweise

Sie können ein KI-Tool im Chat wie folgt verwenden:

  1. Klicken Sie auf die Schaltfläche Tool hinzufügen.
  2. Wählen Sie das gewünschte KI-Tool in der Auswahlliste aus oder suchen Sie das Tool über die Lupe.
  3. Beschreiben Sie im Text, wie das Tool im Workflow-Knoten eingesetzt werden soll.
  4. Speichern Sie Ihre Änderungen.
  5. Testen Sie den geänderten Workflow.

 

Tools über KI hinzufügen

Die Liste der verfügbaren Tools ist lang. Sie können sich daher auch die Tools für Ihren Anwendungsfall von der KI vorschlagen lassen:

  1. Klicken Sie auf die Schaltfläche Tools über KI hinzufügen.

    Ergebnis: Das Fenster zum Auswählen der Tools über die KI öffnet sich.
  2. Geben Sie im Feld KI Prompt ein, wofür Sie Tools suchen. Beispiel: 
    Ich möchte Bilder bearbeiten und erstellen können sowie mir Informationen über Bildmetadaten ausgeben lassen
  3. Klicken Sie auf Ausführen.

    Ergebnis: Die KI ermittelt die relevanten Tools für den angegebenen Verwendungszweck und ergänzt die Tools in der Tools-Liste.
  4. Überprüfen Sie die hinzugefügten Tools und beschreiben Sie im Text, wie die Tools im Workflow-Knoten eingesetzt werden sollen.
  5. Speichern Sie die Änderungen.
  6. Testen Sie den geänderten Workflow.

 

Bearbeiten der Tools in der Tools-Liste

Zum Bearbeiten der einzelnen Einträge in der Tools-Liste können Sie folgende Schaltflächen verwenden:

 

Schaltfläche Beschreibung
  Lupe, Tool suchen und übernehmen Anstatt ein Tool in der Auswahlliste auszuwählen, können Sie die Suche öffnen und alle relevanten Tools gezielt über Keywords suchen. Bitte beachten Sie dabei, dass Tools Entwicklerwerkzeuge sind und daher nur englische Namen und Beschreibungen haben. Geben Sie zum Suchen einen englischen Begriff ein, etwa image, um alle Tools für die Bildverarbeitung angezeigt zu bekommen.
 Parameter des Tools überladen Diese Funktion ist abhängig vom jeweiligen KI-Tool. Wenn das ausgewählte KI-Tool Konfigurationsparameter hat, können Sie die Standardeinstellungen für die Verwendung im KI-Chat überschreiben. Außerdem können Sie die geänderten Einstellungen validieren.
 Tool-Konfiguration bearbeiten Wenn Sie die entsprechende Berechtigung haben, können Sie direkt die Tool-Konfiguration öffnen, um die Einrichtung des jeweiligen Tools zu überprüfen. Für weitere Informationen siehe ALBERT | AI tools einrichten. 
 Tool deaktivieren/reaktivieren Wenn Sie ein Tool deaktiviert haben, wird das Symbol rot angezeigt. Sie können das Tool durch einen Klick auf das rot eingefärbte Symbol wieder aktivieren. Vergessen Sie nicht, die Aufträge für die KI zu überarbeiten, wenn Sie Tools deaktivieren.
 Tool aus der Tools-Liste löschen Das entsprechende Tools wird beim Klicken auf dieses Symbol sofort aus der Tools-Liste im Workflow-Knoten gelöscht. Um es wieder hinzuzufügen, müssen Sie es erneut hinzufügen.