Durchsuchbare Dokumentation aufrufen | Zurück zur Dokumentationsübersicht

Navigation: Dokumentationen agorum core > agorum core Module und Plugins > ALBERT | AI Suite


ALBERT | AI KI-Handler einrichten

Hinweis: Diese Dokumentation bezieht sich auf die aktuellste Version des Plugins ALBERT | AI. Aktualisieren Sie das hier beschriebene Plugin, um die Dokumentation verwenden zu können.

Was sind KI-Handler?

KI-Handler erweitern den KI-Verarbeitungsprozess in ALBERT | AI. Sie ermöglichen es, Daten vor und nach der Verarbeitung durch das KI-Sprachmodell zu modifizieren.
KI-Handler werden in KI-Voreinstellungen eingebunden und können verschiedene Aufgaben übernehmen:

Funktionsweise von KI-Handlern

KI-Handler können an folgenden Stellen in den KI-Verarbeitungsprozess eingreifen:

Hook Beschreibung Typische Verwendung
before Wird vor dem KI-Aufruf ausgeführt. Ermöglicht die Modifikation von Eingabedaten, Historie und Parametern. Filtern sensibler Daten, Anreichern von Kontextinformationen
callAi Wird unmittelbar vor dem Senden an das Sprachmodell ausgeführt. Ermöglicht die Inspektion des rohen Request-Bodys. Debugging, Protokollierung des exakten Requests
after Wird nach dem KI-Aufruf ausgeführt. Ermöglicht die Modifikation des Ergebnisses. Wiederherstellen gefilterter Daten, Protokollierung der Antwort
error Wird bei finalem Fehler (nach allen Fallbacks) statt after aufgerufen; für Cleanup/Logging im Fehlerfall. Running-Marker entfernen, Fehler protokollieren, Maskierungen zurücksetzen, Monitoring/Compliance-Logging.
stop Wird statt after aufgerufen, wenn der Chat angehalten wurde; für Aufräumarbeiten nach dem Anhalten. Für die abgebrochene Anfrage vorbereitete Zustände verwerfen, Anhalten protokollieren.

Ausgelieferte KI-Handler

ALBERT | AI wird mit folgenden vordefinierten KI-Handlern ausgeliefert. Diese KI-Handler können Sie direkt in Ihren KI-Voreinstellungen verwenden. Wenn Handler-Einstellungen konfiguriert werden können, können Sie diese bei Bedarf in der KI-Handler-Konfiguration anpassen. Die Tabelle ist nach Zweck gegliedert. Die Spalte Standardmäßig aktiv nennt, ob die ausgelieferte KI-Handler-Konfiguration aktiv ist und damit in KI-Voreinstellungen gewählt werden kann. Ausgeführt wird ein Handler erst, wenn er einer KI-Voreinstellung hinzugefügt oder global zugewiesen ist.

Anzeigename Beschreibung Standardmäßig aktiv Link
Datenschutz und Filter
Simple String Array Filter Ersetzt sensible Zeichenketten in KI-Anfragen durch Platzhalter, anhand von exaktem Text oder regulären Ausdrücken, und stellt sie in den KI-Antworten wieder her. nein, es wird keine KI-Handler-Konfiguration mitgeliefert, siehe Eine neue KI-Handler-Einstellung hinzufügen Simple String Array Filter
PII: Filter personal information with AI Erkennt personenbezogene Daten in KI-Anfragen mithilfe einer KI-Voreinstellung, ersetzt sie durch Platzhalter und stellt sie in den KI-Antworten wieder her. ja PII: Filter personal information with AI
PII: Filter personal information with CSV Ersetzt Begriffe aus einer CSV-Datei, auch als reguläre Ausdrücke, in KI-Anfragen durch Platzhalter und stellt sie in den KI-Antworten wieder her. ja PII: Filter personal information with CSV
Kontext und Historie
Compact history on demand Komprimiert die Chat-Historie automatisch, wenn das Kontextfenster einen konfigurierbaren Schwellenwert überschreitet. ja Compact history on demand
Inactivity Memorize: Mark prior tool entries as memorized after inactivity Markiert nach einer konfigurierbaren Inaktivitätsdauer ältere Tool-Calls und Tool-Response-Einträge in der Chat-History, sodass deren Inhalte bei der Nachrichtenerstellung an die KI automatisch komprimiert werden. ja Inactivity Memorize: Mark prior tool entries as memorized after inactivity
Steuerung
Agent Mode: Switch preset into agent mode Schaltet eine KI-Voreinstellung zwischen normalem Chat und werkzeuggetriebenem Arbeitsmodus um. ja Agent Mode: Switch preset into agent mode
Goal: Keep the model working until the goal is reached Hält das Modell über mehrere Runden bei der Arbeit, bis es das Ziel mit dem Tool update_goal abschließt, eine Rückfrage stellt oder eine Blockade meldet, oder bis eine Rundengrenze erreicht ist. ja Goal: Keep the model working until the goal is reached
Finish check: Verify AI task completion Fordert das Modell zum Weiterarbeiten auf, wenn es ohne Tool-Aufruf antwortet. nein Finish check: Verify AI task completion
Protokoll und Debug
Debug: Print AI input and output to console Protokolliert alle Ein- und Ausgaben der KI-Verarbeitung in der Konsole. ja Debug: Print AI input and output to console
Log AI calls (protocol) Protokolliert alle KI-Anfragen und -Antworten als JSON-Dateien im Workspace-Bereich von agorum core. ja Log AI calls (protocol)
Coding Agents: Record sessions Protokolliert die Sitzungen von Coding Agents wie Claude Code: ordnet die MCP-Aufrufe den Sitzungen zu und schreibt Sitzungsprotokolle und Einträge für die Kostenkontrolle. Wird mit ALBERT | AI Coding Agents ausgeliefert. ja, protokolliert wird aber erst nach dem Einschalten in der Maske Coding Agents ALBERT | AI Coding Agents einrichten
AI Usage & Cost Analysis: Log usage and costs Protokolliert die Nutzung des KI-Assistenten und sendet Nutzungsstatistiken als JSON per HTTP POST an einen externen Endpunkt. ja, gezählt wird aber erst nach dem Einschalten über Lokale Zählung, siehe ALBERT | AI Kostenkontrolle einrichten AI Usage & Cost Analysis: Log usage and costs

KI-Handler-Einstellungen

KI-Handler-Einstellungen öffnen

Nach dem Installieren des Plugins können Sie die KI-Handler-Einstellungen in der Administration des Plugins in der Kopfleiste unter  > Administration > Konfiguration > KI-Handler vornehmen.

KI-Handler-Einstellungen anpassen

  1. Öffnen Sie die gewünschte KI-Handler-Einstellung, indem Sie  > Administration > Konfiguration > KI-Handler öffnen, die Voreinstellung in der Auswahlliste wählen und Bearbeiten klicken.
  2. Ändern Sie bei Bedarf die vorhandenen Einstellungen.
  3. Speichern Sie die geänderte Konfiguration.

    Ergebnis: Sie haben die KI-Handler-Einstellung geändert.

Allgemeine KI-Handler-Einstellungen

Im Konfigurationsfenster können Sie folgende Einstellungen vornehmen:

Allgemeine KI-Handler-Einstellungen
Einstellung Beschreibung
Konfiguration Der technische Name der Handler-Konfiguration. Dieser Name wird verwendet, um den Handler in KI-Voreinstellungen zu referenzieren.
Anzeigename Der für Benutzer sichtbare Name des Handlers.
Beschreibung Eine optionale Beschreibung, die den Zweck des Handlers erläutert.
Angezeigte Beschreibung Erscheint unter dem Feld Beschreibung, wenn dort ein Übersetzungsschlüssel mit führendem Unterstrich steht, etwa _agorum.ai.usage.protocol.config.handler.default.description, und zeigt den Text in der Sprache des angemeldeten Benutzers. Die mitgelieferten KI-Handler verwenden solche Schlüssel.
Aktiv Aktiviert oder deaktiviert den Handler. Nur aktive Handler können in KI-Voreinstellungen verwendet werden.
KI-Handler Wählen Sie den Handler-Typ aus der Liste der verfügbaren Handler aus. Je nach gewähltem Handler werden unterschiedliche oder auch keine weiteren Konfigurationsoptionen angezeigt, abhängig davon, ob und wie der Handler konfiguriert werden kann.
Benutzergruppe Wählen Sie die Benutzergruppe aus, die Zugriff auf diese Handler-Konfiguration haben soll.

KI-Handler in KI-Voreinstellungen verwenden

Um einen KI-Handler zu verwenden, richten Sie die Nutzung des Handlers in einer oder mehreren KI-Voreinstellungen ein:

  1. Öffnen Sie ☰ > Administration > Konfiguration > KI-Voreinstellungen.
  2. Wählen Sie die gewünschte KI-Voreinstellung aus und klicken Sie Bearbeiten.
  3. Scrollen Sie zum Bereich KI-Handler.
  4. Klicken Sie auf KI-Handler hinzufügen.
  5. Wählen Sie den gewünschten KI-Handler in der Liste aus.
  6. Speichern Sie die KI-Voreinstellung.

Hinweis: Die Reihenfolge der Handler ist wichtig. Wenn Sie mehrere KI-Handler in einer KI-Voreinstellung verwenden, werden die Handler in der angegebenen Reihenfolge ausgeführt.

Eigene KI-Handler erstellen

Sie können eigene KI-Handler entwickeln, um spezifische Anforderungen zu erfüllen. Ein KI-Handler besteht aus einer JavaScript-Datei mit einer definierten Struktur.

Die Erstellung und Verwendung eines neuen KI-Handlers besteht aus folgenden Schritten:

  1. Erstellen Sie die JavaScript-Datei im Verzeichnis:
    /agorum/roi/customers/<configuration project>/js/ai-handlers/
    Für die Grundstruktur der JavaScript-Datei siehe Grundstruktur eines KI-Handlers.

    Beispiel: 
    /agorum/roi/customers/agorum.doc.test/js/ai-handlers/my-test-handler.js
  2. Registrieren Sie den Handler in der MetaDB unter folgendem Pfad:
    MAIN_MODULE_MANAGEMENT/customers/agorum.ai/handlers

    Beispiel für den Pfad des neuen MetaDB-Eintrags:
    MAIN_MODULE_MANAGEMENT/customers/agorum.ai/handlers/[ agorum.doc.test ]/agorum.doc.test.my-test-handler


    Erstellen Sie dort ein neues Property-Entry mit:

    Name: Name des KI-Handlers, am besten bestehend aus Konfigurationsprojekt und Name der JavaScript-Datei, Beispiel: agorum.doc.test.my-test-handler

    Datentyp: Zeichenkette (String)

    Wert: Pfad zur JavaScript-Datei, Beispiel:

     /agorum/roi/customers/agorum.doc.test/js/ai-handlers/my-test-handler.js
  3. Erstellen Sie eine neue KI-Handler-Konfiguration über den Konfigurationsdialog, siehe Eine neue KI-Handler-Einstellung hinzufügen, und wählen Sie dort den von Ihnen neu entwickelten und registrierten Handler aus. Setzen Sie die Konfiguration aktiv, um den Handler in KI-Voreinstellungen verwenden zu können. 

Grundstruktur eines KI-Handlers

/**
 * handler name: my-test-handler
 *
 * handler description
 */
let i18n = require('common/i18n');

({
  /**
   * Information about this handler
   */
  info: () => {
    return {
      description: 'Doc Test Handler', //name used in UI
      runAlways: false, // true = runs even when the handler is disabled
      encryptedFields: [], // fields with values that need to be encrypted
      configAon: {
        type: 'agorum.composite.form.basic',
        elements: [
          // configuration elements are defined here
        ],
      },
    };
  },

  /**
   * hook before the AI call 
   * @param {Object} data - input data (input, history, parameters)
   * @param {Object} parameters - handler parameter
   * @param {Object} context - context for data exchange with after hook
   */
  before: (data, parameters, context) => {
    // modify data before the AI call 
    // IMPORTANT: no return value, data is modified directly
  },

  /**
   * hook for the raw request body (optional)
   * @param {Object} requestBody - request to the language model
   * @param {Object} parameters - handler parameters
   * @param {Object} context - context
   */
  callAi: (requestBody, parameters, context) => {
    // inspire or modify requests
  },

  /**
   * hook after the ai call
   * @param {Object} result - the ai result
   * @param {Object} parameters - handler parameters
   * @param {Object} context - context from before hook
   */
  after: (result, parameters, context) => {
    // modify the result after the ai call
    // IMPORTANT: no return value, data is modified directly
  },  

  /**
   * hook on final error (optional)
   * will be called instead of after() if the AI call fails after all fallbacks
   * @param {Object} result - the ai result containing error information
   * @param {Object} parameters - handler parameters
   * @param {Object} context - context from before hook
   */
  error: (result, parameters, context) => {
    // cleanup / logging in error case
    // IMPORTANT: no return value, result is modified directly if needed
  },

  /**
   * hook when the chat was stopped (optional)
   * will be called instead of after() if the chat was stopped
   * @param {Object} result - the ai result with stopped set
   * @param {Object} parameters - handler parameters
   * @param {Object} context - context from before hook
   */
  stop: (result, parameters, context) => {
    // cleanup / logging when the chat was stopped
    // IMPORTANT: no return value, result is modified directly if needed
  },
});

Eine neue KI-Handler-Einstellung hinzufügen

  1. Öffnen Sie  > Administration > Konfiguration > KI-Handler.

    Ergebnis: Das Fenster KI-Handler einrichten öffnet sich.
  2. Klicken Sie auf die Schaltfläche (Plus), um eine neue Konfiguration zu erstellen.

    Ergebnis: Das Fenster Anlage eines neuen KI-Handlers öffnet sich.
  3. Geben Sie den Namen ein, den Sie dem neuen KI-Handler geben wollen, und optional ein Konfigurationsprojekt und klicken Sie Speichern.

    Ergebnis: Die neue Konfiguration wird in der Liste der Konfigurationen angezeigt.
  4. Klicken Sie auf Bearbeiten.

    Ergebnis: Das Fenster KI-Handler einrichten öffnet sich.
  5. Geben Sie den Anzeigenamen an und wählen Sie die von Ihnen neu eingerichteten KI-Handler in der Auswahlliste aus. 
  6. Geben Sie optional weitere Einstellungen an. Wenn Sie den KI-Handler in KI-Voreinstellungen verwenden wollen, müssen Sie den Handler aktiv setzen.
  7. Speichern Sie die KI-Handler-Konfiguration.

Globale KI-Handler

Zusätzlich zu den preset-spezifischen KI-Handlern unterstützt ALBERT | AI auch globale KI-Handler. Globale Handler werden bei allen KI-Aufrufen ausgeführt, unabhängig davon, welche KI-Voreinstellung verwendet wird. Sie eignen sich besonders für systemweite Anforderungen wie:

Registrierung globaler KI-Handler

Globale Handler werden in der MetaDB unter folgendem Pfad registriert:

MAIN_MODULE_MANAGEMENT/customers/agorum.ai/global-handlers/[ <projektname> ]

Dabei ist <projektname> der Name Ihres Konfigurationsprojekts.

Namensschema und Sortierung

Die Sortierung und Aktivierung der globalen Handler erfolgt über ein spezielles Namensschema:

[#]NNNN handler.name
Element Beschreibung Beispiel
# Optional. Wenn vorhanden, ist der Handler deaktiviert. #0010 my-handler (deaktiviert)
NNNN Vierstellige Zahl, die die Sortierreihenfolge bestimmt. Handler mit niedrigeren Zahlen werden zuerst ausgeführt. 0010, 0020, 0100
handler.name Der Name des Handlers (frei wählbar). audit-logger, pii-filter

Beispiele für Handler-Namen

Name Status Reihenfolge
0010 audit-logger Aktiv Wird als erstes ausgeführt
0020 pii-filter Aktiv Wird als zweites ausgeführt
#0030 debug-handler Deaktiviert Wird nicht ausgeführt
0100 compliance-check Aktiv Wird als drittes ausgeführt

Ausführungsreihenfolge

Die Ausführungsreihenfolge der Handler ist wie folgt:

  1. Preset-spezifische Handler werden zuerst ausgeführt (in der Reihenfolge, wie sie in der KI-Voreinstellung konfiguriert sind)
  2. Globale Handler werden danach ausgeführt (sortiert nach der Nummer im Namen)

Hinweis: Globale Handler verwenden dieselbe Struktur wie preset-spezifische Handler. Sie können daher bestehende Handler-Implementierungen auch als globale Handler registrieren.

Globalen KI-Handler einrichten

Gehen Sie wie folgt vor, um einen globalen KI-Handler einzurichten:

  1. Erstellen Sie die JavaScript-Datei für den Handler im Verzeichnis:
    /agorum/roi/customers/<konfigurationsprojekt>/js/ai-handlers/
  2. Öffnen Sie links in der Seitenleiste Administration und dann MetaDB.
  3. Navigieren Sie zum Pfad:
    MAIN_MODULE_MANAGEMENT/customers/agorum.ai/global-handlers/[projektname]
    Erstellen Sie die Ordner bei Bedarf.
  4. Erstellen Sie einen neuen MetaDB-Eintrag (Property Entry) mit:
    • Name: Nach dem Namensschema, z. B. 0010 audit-logger
    • Datentyp: Zeichenkette (String)
    • Wert: Pfad zur JavaScript-Datei, z. B.
    /agorum/roi/customers/mein-projekt/js/ai-handlers/audit-logger.js