ALBERT | AI Chat-Widget

Das aguila-Widget agorum.ai.chatMain ist die zentrale Chat-Komponente von ALBERT | AI. Es stellt die vollständige Chat-Oberfläche bereit, einschließlich Nachrichtenanzeige, Eingabefeld, Seitenpanel mit Chat-Historie und Vorlagen sowie Debug-Modus.

Entwickler können dieses Widget in eigene aguila-Oberflächen einbetten, um kontextbezogene KI-Chat-Funktionalität bereitzustellen, etwa in Detailfenstern, eigenen Dialogen oder spezialisierten Anwendungen.

Verwendung

Das Widget wird als aguila-Komponente eingebunden:

let aguila = require('common/aguila');

let chatTest = aguila.create({
  type: 'agorum.ai.chatMain',
  hideSidePanel: true,
  flexible: true,
});

chatTest;

 

Oder eingebettet in einen Container:

let aguila = require('common/aguila');

let chatContext = aguila.create({
  type: 'agorum.vbox',
  width: 1100,
  height: 800,
  items: [
    {
      type: 'agorum.ai.chatMain',
      hideSidePanel: false,
      flexible: true,
      name: 'chat',
    },
  ],
});

let chat = chatContext.down('chat');

// Open a specific chat
chat.id = '8115311a-8b06-4d45-9a1f-c0437e303809';

// Set context
chat.context = 'Du bist ein Experte für agorum core.';

chatContext;

 

Properties

Property	Typ	Beschreibung	Pflicht
id	string	UUID eines bestehenden Chats. Wenn gesetzt, wird dieser Chat geöffnet und angezeigt. Wird keine id angegeben, wird ein neuer Chat erstellt.	nein
ids	array	Array von UUIDs. Kann verwendet werden, um mehrere Objekt-IDs als Kontext zu übergeben (z. B. markierte Suchergebnisse).	nein
hideSidePanel	boolean	Wenn true, wird das Seitenpanel (Chat-Historie und Vorlagen) ausgeblendet. Nützlich, wenn das Widget in einem kompakten Bereich eingebettet wird, z. B. im Detailfenster.	nein
context	string	Ein zusätzlicher Kontext-Text, der bei der nächsten KI-Anfrage mitgesendet wird. Dieser Kontext wird im Chat-Objekt gespeichert und bleibt auch beim Wechsel zwischen Chats erhalten. Der Kontext wird zum Kontext aus der KI-Voreinstellung hinzugefügt.	nein
chatTitle	string	Ein Titel, der in der Toolbar des Chat-Widgets oben angezeigt wird. Nützlich, um dem Benutzer den aktuellen Kontext anzuzeigen (z. B. Ordnername, Suchergebnis).	nein
ignorePresetErrors	boolean	Wenn true, werden Fehler beim Laden von KI-Voreinstellungen (Presets) nicht als Fehlerdialog angezeigt, sondern still ignoriert. Nützlich für eingebettete Widgets, die robust auf fehlende Konfigurationen reagieren sollen.	nein
toolParameters	object	Ein Objekt mit Schlüssel-Wert-Paaren, die auf alle vom Preset geladenen KI-Tools angewendet werden (nur bei Verwendung von ALBERT | AI Agents).	nein

Property toolParameters im Detail

Mit der Property toolParameters können Entwickler Standardwerte für Tool-Parameter widget-weit vorgeben. Die Werte werden auf alle vom Preset geladenen Tools angewendet, als wären sie in der jeweiligen Tool-Konfiguration vorbelegt.

• Die KI sieht die über toolParameters gesetzten Schlüssel nicht im Tool-Schema. Beim Tool-Run werden sie automatisch in die Argumente gemerged.
• Wirkt sowohl für jsHandler-Tools als auch für MCP-Tools.
• Werte werden bei jedem Submit aus dem Widget in das Chat-Objekt geschrieben und sind im chatCache persistent.

Ein konkretes Anwendungsbeispiel für toolParameters ist der Reiter ALBERT | AI im Detailfenster. Dort werden Tools, die in ihrem Schema allowedBasePathIds deklarieren, automatisch auf den aktuellen Kontext-Pfad eingeschränkt:

Kontext	Erlaubte Pfade
Ordner-Kontext	Der ausgewählte Ordner selbst + persönlicher Workspace
Datei-Kontext	Alle sichtbaren Eltern-Ordner der Datei + persönlicher Workspace
Such-Kontext (oder kein Kontext)	Nur der persönliche Workspace (home:ai/workspace)

Beim Einbetten des Details-Chat-Widgets lassen sich weitere Ordner zusätzlich zum Kontext freigeben, siehe Zusätzliche Schreib-Ordner freigeben (additionalAllowedIds).

Persönlicher Workspace-Ordner als Schreib-Fallback

Im Home-Verzeichnis jedes Benutzers wird beim ersten Öffnen des Details-Chats automatisch der Ordner home:ai/workspace angelegt (sofern noch nicht vorhanden). Dieser Ordner ist dauerhaft als zulässiger Schreib-Ordner für KI-Tools verfügbar:

• Such-Modus: Der Workspace wird als Fallback-Zielordner verwendet, statt alle Schreib-Operationen pauschal zu blockieren.
• Ordner-/Datei-Modus: Der Workspace wird als zusätzlicher Eintrag am Ende der Liste der erlaubten Pfade geführt, sodass die KI auch dann ein Ziel hat, wenn der Kontext-Ordner schreibgeschützt ist.
• Der KI-Prompt nennt explizit alle erlaubten Schreib-Ordner inklusive Hinweis, dass der Workspace nur als Fallback verwendet werden soll und primär die kontextuellen Ordner zu bevorzugen sind.

Details-Chat-Widget einbetten

Der Reiter ALBERT | AI im Detailfenster verwendet das aguila-Widget agorum.ai.agents.details.chat (nur bei Verwendung von ALBERT | AI Agents). Es baut auf agorum.ai.chatMain auf und bringt den Kontext eines Ordners, einer Datei oder einer Suche mit: Es merkt sich den Chat je Objekt und schränkt schreibende KI-Tools über allowedBasePathIds auf den Kontext ein (siehe Tabelle oben).

Entwickler können dieses Widget auch selbst einbetten, etwa in einer eigenen Oberfläche für einen Vorgang.

Zusätzliche Schreib-Ordner freigeben (additionalAllowedIds)

Mit der Property additionalAllowedIds geben Sie beim Einbetten weitere Ordner frei, in die die KI zusätzlich zum Kontext schreiben darf – etwa die übergeordnete Kundenakte, wenn der Chat in einem Vorgang geöffnet wird.

let aguila = require('common/aguila');

let chat = aguila.create({
  type: 'agorum.ai.agents.details.chat',
  id: processFolderUuid,
  additionalAllowedIds: [customerFileUuid],
});

chat;

Property	Typ	Beschreibung	Pflicht
id	string	Ordner oder Datei, die den Kontext des Chats bildet. Der Chat wird diesem Objekt zugeordnet.	nein
additionalAllowedIds	array oder string	Weitere Ordner (UUID, ID oder Pfad), die zusätzlich zum Kontext als Schreibziel der KI erlaubt sind. Ein einzelner Wert wird wie eine Liste mit einem Eintrag behandelt. Die Property lässt sich zur Laufzeit ändern; Tool-Parameter und Prompt werden dann neu berechnet.	nein

Verhalten im Detail:

• Die erlaubten Schreib-Ordner werden in dieser Reihenfolge gebildet: Kontext-Ordner, zusätzliche Ordner, persönlicher Workspace home:ai/workspace. Kein Ordner erscheint doppelt.
• Die zusätzlichen Ordner gelten im Objekt- wie im Such-Kontext.
• Im Prompt sind die zusätzlichen Ordner als ZUSÄTZLICH gekennzeichnet. Die KI legt weiterhin bevorzugt im Kontext-Ordner ab und nutzt einen zusätzlichen Ordner, wenn der Inhalt dorthin gehört oder der Benutzer es verlangt.
• Nur Ordner werden berücksichtigt. Einträge, die nicht auffindbar sind, und Dateien werden ignoriert und protokolliert; der Chat läuft weiter.
• Ohne additionalAllowedIds bleibt alles wie bisher, auch im Reiter ALBERT | AI des Detailfensters, der die Property nicht setzt.

Auf Chat-Ereignisse reagieren (Entwickler)

Der Chat-Cache hält geöffnete Chats im Speicher und meldet jede Änderung an die geöffneten Chat-Fenster. Eigene aguila-Widgets können diese Meldungen abonnieren, etwa um eine Liste von Chats aktuell zu halten.

let chatCache = require('/agorum/roi/customers/agorum.ai/js/utils/chat-cache');

// im Widget: auf Ereignisse des angemeldeten Benutzers reagieren
chatCache.subscribe(widget, event => {
  if (event.removedChat) {
    // der Chat mit dieser ID wurde gelöscht
  } else {
    // der Chat event.chatId hat sich geändert
  }
});

Das Widget wird beim Schließen automatisch abgemeldet. Die Funktion subscribe übergibt das Ereignis als Objekt mit diesen Feldern:

Feld	Typ	Beschreibung
userId	string	UUID des Benutzers, dem der Chat gehört.
chatId	string	ID des geänderten Chats. Fehlt, wenn ein Chat entfernt wurde.
widgetId	string	Optional: Instanz des Widgets, das die Änderung ausgelöst hat.
appendedNewChat	boolean	true, wenn ein neuer Chat angelegt wurde.
removedChat	string	ID des Chats, der entfernt wurde. Nur bei einem Entfernen vorhanden.

Kanal je Benutzer

Jeder Benutzer hat einen eigenen Kanal. Sein Name entsteht aus agorum-ai-chats: und der UUID des Benutzers. Die Funktion chatCache.channelFor(benutzerUuid) liefert ihn. Ein geöffnetes Chat-Fenster erhält so nur die Ereignisse seines Benutzers und sammelt nicht die Ereignisse aller anderen Benutzer.

Die Ereignisse werden als JSON-Text veröffentlicht. chatCache.subscribe wandelt den Text in ein Objekt um und ignoriert ungültige Ereignisse. Ein Objekt würde die Skript-Engine des Absenders so lange festhalten, bis alle Abonnenten es verarbeitet haben.

Häufigkeit der Aktualisierung

Beim Streamen einer Antwort veröffentlicht ALBERT | AI die Ereignisse zu neuen Textstücken (Text und Reasoning) höchstens alle 250 Millisekunden statt bei jedem Textstück. Der Chat-Cache erhält dabei jedes Textstück, nur das Ereignis wird gedrosselt. Das erste Textstück jedes Modellaufrufs geht sofort hinaus.

Alle anderen Änderungen werden sofort veröffentlicht: Werkzeugaufrufe und ihr Status, Abschluss, Stopp, Fehler und das regelmäßige Speichern des Chats alle 5 Sekunden. Ein Chat-Fenster kann deshalb auch in kürzerem Abstand als 250 Millisekunden ein Ereignis erhalten.