Mit ALBERT | AI Agents Debug-Modus im Chat arbeiten

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

Wenn Sie das Plugin ALBERT | AI Agents installiert haben und die entsprechende Berechtigung haben, können Sie die Debug-Funktionalität im Chat verwenden.

Der Debug-Modus bietet erweiterte Analyse- und Überwachungsmöglichkeiten für AI-Chat-Interaktionen. Er ermöglicht Entwicklern und Administratoren detaillierte Einblicke in die Token-Nutzung, Netzwerkstatistiken und Tool-Aufrufe.

ALBERTs Chat debuggen

Wenn Sie den Debug-Modus in ALBERTs Chat aktivieren, sehen Sie zusätzlich folgende Informationen direkt im Chat-Fenster:

Ein Debug-Info-Panel oberhalb des Chat-Verlaufs mit einer Übersicht über den Kontext-Verbrauch, die Token-Nutzung und die Kosten
Aufklappbare Debug-Informationen zu jedem einzelnen Aufruf (Zeitstempel, Token-Statistiken, Netzwerkstatistiken)
Aufklappbare Tool-Gruppen, die Tool-Aufrufe und deren Antworten als zusammengehörige Paare darstellen
System-Nachrichten, die im normalen Modus ausgeblendet sind

Das ist insbesondere dann sinnvoll, wenn Sie KI-Tools verwenden, weil Detailinformationen zum Tool-Aufruf und der Antwort des Tools über die Debug-Funktion direkt im Chatfenster im Verlauf nachvollzogen werden können.

Das folgende Beispiel zeigt, wie die Debug-Informationen in einem Chat angezeigt werden, in dem eine KI-Voreinstellung mit einem Tool-Aufruf verwendet wird.

Screencast einer KI-Anfrage im Debug-Modus

In den Debug-Modus wechseln

Der Debug-Modus kann über einen speziellen Button in der Chat-Toolbar aktiviert und auch wieder deaktiviert werden. Dieser Button ist als Bug-Symbol dargestellt und wechselt seine Farbe je nach Status: Im inaktiven Zustand erscheint das Symbol in Dunkelgrau, während es im aktivierten Zustand in Orange dargestellt wird.

Nur Benutzer mit der Berechtigung ACL_agorum.ai.agents_chat_debug können den Debug-Modus aktivieren. Diese Einschränkung stellt sicher, dass nur autorisierte Personen wie Entwickler, Administratoren oder Support-Mitarbeiter Zugriff auf die detaillierten Debug-Informationen erhalten.

Sie können den Debug-Modus jederzeit aktivieren und deaktivieren, auch während der Chat läuft. Beim Umschalten wird der gesamte Chat-Verlauf neu gerendert, um die Debug-Informationen ein- oder auszublenden.

Token-Verbrauch in der Toolbar

Unabhängig vom Debug-Modus zeigt die Chat-Toolbar eine prozentuale Anzeige des Kontext-Fenster-Verbrauchs an. Diese Anzeige ist farbcodiert:

Grün (unter 60 %): Der Kontext-Verbrauch ist unkritisch.
Orange (60–80 %): Der Kontext-Verbrauch nähert sich der Kapazitätsgrenze.
Rot (ab 80 %): Der Kontext-Verbrauch ist kritisch hoch. Das Modell kann möglicherweise nicht mehr alle Informationen verarbeiten.

Der Tooltip dieser Anzeige informiert darüber, dass bei Annäherung an 100 % das Modell die aktuellen Informationen nicht mehr verarbeiten kann.

Debug-Info-Panel

Zusätzlich zu den nachrichtenspezifischen Debug-Informationen wird im Debug-Modus ein separates Panel oberhalb des Chat-Fensters eingeblendet. Dieses Debug-Info-Panel mit dem Titel Kontext-Informationen und Verbrauch bietet eine Übersicht über den Kontext-Verbrauch im gesamten Chat-Verlauf und fasst alle wichtigen Informationen zusammen:

Beispiel für die Anzeige im Debug-Info-Panel

Information im Debug-Panel	Beschreibung
Input	Summe aller Input-Tokens über alle Nachrichten hinweg
Output	Summe aller Output-Tokens über alle Nachrichten hinweg
ALBERT-Output	Summe aller ALBERT-Output-Tokens („sichtbarer Output“ auf Basis von `result.text` inkl. Tool-Calls; ohne `reasoningText`). Dieser Wert ist unabhängig von Provider-Output-Tokens und wird nicht zum Gesamt-Token-Wert addiert, um Doppelzählungen zu vermeiden.
Gesamt	Summe aus Input-Tokens, Output-Tokens, Cache-Read-Tokens und Cache-Write-Tokens. Hinweis: ALBERT-Output-Tokens sind in diesem Wert nicht enthalten, da sie einen separaten Zähler darstellen.
Cache (lesen)	Cache-Read-Tokens. Anzahl der Tokens, die das Modell aus dem Cache liest, anstatt sie als neue Input-Tokens zu verarbeiten.
Cache (schreiben)	Cache-Write-Tokens. Anzahl der Tokens, die erstmalig in den Cache des Anbieters geschrieben werden.
Kontext-Fenster	Anzeige der aktuell verwendeten Kontext-Tokens im Verhältnis zur maximalen Kapazität des Kontext-Fensters, wobei der erste Wert die aktuell belegten Tokens und der zweite Wert die maximale Kapazität des gewählten KI-Modells angibt.
Tool-Aufrufe	Gesamtanzahl aller durchgeführten Tool-Calls im aktuellen Chat
Gesamtpreis	Wenn Preise in der verwendeten KI-Modelleinstellung eingetragen sind, wird ein berechneter Gesamtpreis für den Chat-Verlauf des ausgewählten Chats angezeigt. Der Gesamtpreis berechnet sich auf Basis folgender Provider-Daten: (Input-Tokens / 1 Mio.) × Input-Tokens pro 1Mio + (Output-Tokens / 1 Mio.) × Output-Tokens pro 1Mio + (Cache-Read-Tokens / 1 Mio.) × Cache (lesen) pro 1Mio + (Cache-Write-Tokens / 1 Mio.) × Cache (schreiben) pro 1Mio + (Tool-Aufrufe / 1.000) × Tool-Aufrufe pro 1.000 Wenn eine Währungsumrechnung erforderlich ist (z. B. USD nach EUR), wird diese zusätzlich mit dem in der KI-Voreinstellung angegebenen Umrechnungsfaktor durchgeführt. Separat (falls in der KI-Voreinstellung ein Preis für ALBERT-Output gepflegt ist): (ALBERT-Output-Tokens / 1 Mio.) × ALBERT-Output-Tokens pro 1Mio Hinweis: ALBERT-Output-Tokens werden separat berechnet, sofern ein entsprechender Preis in der KI-Voreinstellung konfiguriert ist.

Debug-Informationen im Chat-Verlauf

Während im normalen Chat-Modus bestimmte Nachrichten ausgeblendet werden, um die Bedienoberfläche übersichtlich zu halten, zeigt der Debug-Modus ausnahmslos alle Nachrichten an. Dies umfasst System-Prompts, die normalerweise versteckt bleiben, interne Steuerungsnachrichten und alle Details zu Tool-Aufrufen und deren Antworten.

Für jeden Aufruf werden folgende Informationen als aufklappbare Box dargestellt. Im eingeklappten Zustand zeigt die Box eine Zusammenfassung (Token-Anzahl, ALBERT-Output-Tokens und Verarbeitungszeit). Durch Klick auf den Pfeil lässt sich die Box aufklappen und zeigt die vollständigen Details:

Der Zeitstempel zeigt den exakten Zeitpunkt, zu dem die Nachricht verarbeitet wurde.
Die Token-Statistiken geben einen detaillierten Überblick über die Ressourcennutzung der jeweiligen Nachricht:
- Die Input-Tokens zeigen, wie viele Tokens an die AI gesendet wurden.
- Die Output-Tokens zeigen die Anzahl der von der AI generierten Tokens.
- Die ALBERT-Output-Tokens zeigen die Token-Anzahl des sichtbaren Outputs. Dieser Wert ist unabhängig von den Provider-Output-Tokens und wird nicht zum Total addiert.
- Zusätzlich werden Cache-Read-Tokens und Cache-Write-Tokens separat ausgewiesen. Cache-Read-Tokens sind bereits zwischengespeicherte Tokens, die nicht neu verarbeitet werden mussten, während Cache-Write-Tokens neu in den Cache geschrieben wurden.
- Zusätzlich werden Cache-Read-Tokens und Cache-Write-Tokens separat ausgewiesen. Cache-Read-Tokens sind bereits zwischengespeicherte Tokens, die nicht neu verarbeitet werden mussten, während Cache-Write-Tokens neu in den Cache geschrieben wurden.
- Die Total-Tokens summieren Input-, Output-, Cache-Read- und Cache-Write-Tokens und geben einen Gesamtüberblick über die Token-Nutzung dieser spezifischen Nachricht.
Die Netzwerkstatistiken ergänzen die Debug-Informationen um technische Details zur Datenübertragung:
- Die gesendeten Bytes zeigen die Größe der Request-Daten in Bytes an.
- Die empfangenen Bytes geben die Größe der Response-Daten an.
- Die Gesamtzeit gibt die Verarbeitungszeit vom Absenden der Anfrage bis zum vollständigen Empfang der Antwort in Millisekunden an.

Tool-Aufrufe im Debug-Modus

Tool-Aufrufe werden im Debug-Modus als gruppierte aufklappbare Boxen dargestellt. Jede Tool-Gruppe fasst den Tool-Aufruf und die zugehörige Antwort als zusammengehöriges Paar zusammen:

Im eingeklappten Zustand zeigt die Box den Namen des aufgerufenen Tools, die Anzahl der Tools (bei mehreren gleichzeitigen Aufrufen) sowie eine Zusammenfassung der Token-Nutzung und Verarbeitungszeit.
Im aufgeklappten Zustand werden für jedes Tool-Paar folgende Details angezeigt:
- Tool-Aufruf: Name des Tools, eindeutige ID des Aufrufs und die übergebenen Parameter als strukturiertes JSON.
- Tool-Antwort: Name des Tools und die vollständige Antwort, entweder als reiner Text oder als strukturiertes JSON-Objekt. Verschachtelte JSON-Strings in der Antwort werden automatisch formatiert dargestellt.
Unterhalb der Tool-Paare werden die kombinierten Token-Details sowohl des Aufrufs als auch der Antwort angezeigt.

Wenn die Antwort eines Tools noch nicht eingetroffen ist (z. B. während der Verarbeitung), wird ein Platzhalter mit einem Sanduhr-Symbol angezeigt.

Bei mehreren gleichzeitigen Tool-Aufrufen werden alle Aufrufe und ihre Antworten innerhalb derselben aufklappbaren Box als separate Paare dargestellt.

Anzeige des Chats mit Debug-Informationen bei Verwendung eines KI-Tools

System-Nachrichten im Debug-Modus

System-Nachrichten (z. B. System-Prompts) sind im normalen Chat-Modus ausgeblendet und werden nur im Debug-Modus angezeigt. Sie werden als aufklappbare Boxen dargestellt:

Im eingeklappten Zustand wird eine Vorschau der ersten 80 Zeichen des System-Textes angezeigt.
Im aufgeklappten Zustand wird der vollständige System-Text sichtbar.

Best Practices

Normaler Modus

Im Produktivbetrieb für Endanwender sollte der Debug-Modus deaktiviert bleiben. Die umfangreichen technischen Informationen würden normale Benutzer eher verwirren als helfen und die Bedienoberfläche unnötig überladen.

Bei sehr langen Chat-Verläufen kann der Debug-Modus die Übersichtlichkeit beeinträchtigen. Die Anzeige aller Nachrichten und aller Debug-Informationen führt zu einer sehr langen, scrollbaren Liste, in der es schwierig werden kann, spezifische Informationen zu finden. Die aufklappbaren Boxen helfen dabei, die Übersichtlichkeit zu wahren, da Details nur bei Bedarf eingeblendet werden.

Zugriffssteuerung und Berechtigungen

Die Zugriffssteuerung für den Debug-Modus sollte sorgfältig konfiguriert werden. Der Zugriff auf den Debug-Modus ist insbesondere für folgende Zielgruppen sinnvoll:

Entwickler, die aktiv an der Entwicklung und Optimierung von KI-Features arbeiten.
Administratoren, um bei Problemen oder Anfragen von Benutzern eine fundierte Analyse durchführen zu können. Sie benötigen die Debug-Informationen zur Systemüberwachung und zur Identifizierung von Konfigurationsproblemen.

Die Berechtigung wird über die ACL ACL_agorum.ai.agents_chat_debug gesteuert.

Einsatzszenarien

Der Debug-Modus ist besonders wertvoll bei der Entwicklung neuer KI-Features, da er vollständige Transparenz über alle Aspekte der KI-Kommunikation bietet.

Bei der Optimierung von Prompts empfiehlt sich die Aktivierung des Debug-Modus. Durch die detaillierte Sichtbarkeit der Token-Nutzung und der KI-Antworten können verschiedene Prompt-Varianten objektiv verglichen werden. Die Statistiken zeigen nicht nur, welcher Prompt effizienter ist, sondern auch, warum er effizienter ist.

Bei der Fehlersuche ist der Debug-Modus oft der Schlüssel zur schnellen Problemlösung. Der Debug-Modus liefert konkrete Daten, die zur Ursachenanalyse verwendet werden können. Die Kombination aus vollständiger Nachrichtensichtbarkeit und detaillierten Statistiken deckt die meisten Fehlerquellen auf.

Bei Performance-Problemen hilft der Debug-Modus, den Engpass zu identifizieren. Ob das Problem in zu großen Requests, ineffizienten Prompts, übermäßiger Tool-Nutzung oder Netzwerklatenz liegt, wird durch die verschiedenen Metriken schnell ersichtlich.