Durchsuchbare Dokumentation aufrufen | Zurück zur Dokumentationsübersicht
Navigation: Dokumentationen agorum core > agorum core Module und Plugins > ALBERT | AI Suite
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.
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:
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. |
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 |
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.
Ergebnis: Sie haben die KI-Handler-Einstellung geändert.
Im Konfigurationsfenster können Sie folgende Einstellungen vornehmen:
| 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. |
Um einen KI-Handler zu verwenden, richten Sie die Nutzung des Handlers in einer oder mehreren KI-Voreinstellungen ein:
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.
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:
/agorum/roi/customers/<configuration project>/js/ai-handlers/Für die Grundstruktur der JavaScript-Datei siehe Grundstruktur eines KI-Handlers.
/agorum/roi/customers/agorum.doc.test/js/ai-handlers/my-test-handler.js
MAIN_MODULE_MANAGEMENT/customers/agorum.ai/handlers
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
/**
* 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
},
});
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:
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.
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 |
| 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 |
Die Ausführungsreihenfolge der Handler ist wie folgt:
Hinweis: Globale Handler verwenden dieselbe Struktur wie preset-spezifische Handler. Sie können daher bestehende Handler-Implementierungen auch als globale Handler registrieren.
Gehen Sie wie folgt vor, um einen globalen KI-Handler einzurichten:
/agorum/roi/customers/<konfigurationsprojekt>/js/ai-handlers/MAIN_MODULE_MANAGEMENT/customers/agorum.ai/global-handlers/[projektname]0010 audit-logger/agorum/roi/customers/mein-projekt/js/ai-handlers/audit-logger.js