Usage Protocol/Nutzungsstatistiken protokollieren

Technischer Name: agorum.ai.usage_protocol

Anzeigename: Nutzungsstatistiken protokollieren

Was macht der Handler?

Der Handler agorum_ai_usage_protocol protokolliert die Nutzung des KI-Assistenten und sendet Nutzungsstatistiken als JSON per HTTP POST an einen externen Endpunkt.

Voraussetzungen

• URL-Konfiguration: Es muss mindestens der Parameter url gesetzt sein.
• Kostenberechnung (optional): Damit Kosten berechnet werden können, müssen in der verwendeten KI-Voreinstellung (Preset) Preise hinterlegt sein. Sind keine Preise konfiguriert oder kann das Preset nicht aufgelöst werden, wird cost mit 0 gesendet und currency bleibt leer.

Wann wird gesendet?

• Chat-Start / Resume (Running-Ping): Sobald ein Chat startet oder nach einem Stopp mit einer neuen Benutzer-Nachricht wieder anläuft, sendet der Handler einen kompakten POST mit running:true. 
• Chat-Ende (Final-POST): Ein Chat gilt als abgeschlossen, wenn der letzte Verlaufseintrag mit Rolle assistant keine Tool-Calls enthält (toolCalls leer oder nicht vorhanden). Dann sendet der Handler den Abschluss-POST mit running:false.
• Fehlerfall: Wenn ein KI-Aufruf endgültig scheitert (z. B. Timeout, ungültiges Preset, API-Fehler), sendet der Handler ebenfalls einen Final-POST mit running:false und zusätzlichen Fehlerfeldern. Der Running-Marker wird dabei zurückgesetzt, damit im Backend kein Eintrag auf running:true hängen bleibt.

Sub-Agent-Erkennung / Tracing

Aufrufe, die als Sub-Agent laufen (z. B. über das Tool call_preset oder interne Sub-Chats wie Titel-Generierung, Fehlerübersetzung oder History-Compaction), werden erkannt. Beide POST-Varianten enthalten zusätzlich Felder, um einen Tracing-Baum über mehrere Chats rekonstruieren zu können:

• sub_agent (true/false)
• parent_chat_id (Chat-ID des Parents; zeigt konsistent auf eine existierende chat_id)
• parent_preset (Preset des Parent-Chats)
• chat_kind zur Differenzierung der Art des Aufrufs

Provider/Modell, Fallback und Kosten

• Zusätzlich zu used_preset und model_preset werden in beiden POSTs auch provider (Provider-Name) und model (tatsächlich verwendetes Modell) übertragen.
• Ist im Chat ein Sticky-Fallback aktiv, werden model_preset, provider, model sowie die Preisermittlung (Kosten) aus dem tatsächlich verwendeten Fallback-Preset abgeleitet.

Erfasste Daten

• Token-Verbrauch (Input, Output, Cache-Read, Cache-Write) - Summe über die Chat-History
• ALBERT-Output-Tokens (sichtbarer KI-Output auf Basis von result.text inkl. Tool-Calls; ohne reasoningText). Dieser Wert wird separat gezählt und nicht in die Provider-Output-Tokens eingerechnet, um Doppelzählungen zu vermeiden.
• Anzahl der Tool-Aufrufe
• Berechnete Kosten (falls in der KI-Voreinstellung Preise konfiguriert sind)
• Benutzerinformationen (Benutzername, Benutzer-UUID)
• Zeitstempel (Start- und Endzeit des Chats)
• Verwendete KI-Voreinstellung (used_preset) und tatsächlich verwendetes Modell-Preset (model_preset)
• Provider und Modell (provider, model)
• Optionaler Identifikator zur Kategorisierung
• Anfangstext der Benutzeranfrage (gekürzt)
• Chat-Titel (chat_title)

Chat-Titel

Beide POST-Varianten enthalten den chat_title. Der Wert wird aus der Information in der Chat-Historie gelesen, die bei der Titelgenerierung angelegt wird. Im Before-Hook liegt dieser Eintrag typischerweise noch nicht vor,  dann ist chat_title null. 

chat_kind

Beide POST-Varianten enthalten chat_kind, um die Art des Chat-Aufrufs zu unterscheiden. Mögliche Werte:

• mainAgent – Haupt-Chat (kein Sub-Agent-Marker in der History)
• titleGeneration – Sub-Chat zur Titel-Generierung
• errorTranslation – Sub-Chat zur Fehlerübersetzung
• historyCompaction – Sub-Chat zur History-Compaction
• subAgentCall – Sub-Chat durch das Tool call_preset

Empfohlener Einsatzzweck

Der Handler eignet sich ideal für:

• Kostenüberwachung: Erfassung des Token-Verbrauchs und der daraus resultierenden Kosten pro Benutzer, pro KI-Voreinstellung oder pro Chat.
• Nutzungsanalyse: Auswertung, welche KI-Voreinstellungen wie häufig verwendet werden und welche Modelle/Provider tatsächlich genutzt wurden (inkl. Fallback).
• Reporting: Übermittlung der Nutzungsdaten an externe Systeme wie Data Warehouses, BI-Tools oder eigene Dashboards.
• Abrechnung/Verrechnung: Integration in interne Verrechnungssysteme.
• Compliance/Audit: Protokollierung von KI-Nutzung inkl. Tracing über Sub-Agent-Aufrufe und Fehlerfälle..

Einstellungen

Parameter	Beschreibung
url (Pflicht)	Die Endpunkt-URL, an die die Nutzungsdaten per HTTP POST gesendet werden. Beispiel: https://api.example.com/usage
apiKey (Optional)	API-Key (Bearer Token) zur Authentifizierung gegenüber dem Endpunkt. Falls angegeben, wird der Header Authorization: Bearer <apiKey> mitgesendet. Das Feld wird verschlüsselt gespeichert.
identifier (Optional)	String-Identifikator, der in beiden POSTs mitgesendet wird. Kann zur Kategorisierung oder Kennzeichnung der Protokolleinträge verwendet werden. Beispiele: Abteilung-Vertrieb oder Projekt-X
initialTextLength (Optional)	Maximale Anzahl an Zeichen, die vom ersten Benutzertext erfasst und mitgesendet werden sollen. Längere Texte werden abgeschnitten und mit "..." gekennzeichnet. Standard: 100

Gesendete Datenstruktur

Der Handler sendet folgende JSON-Struktur an den konfigurierten Endpunkt.

Running-Ping (Chat-Start/Resume)

Beispielhafte Struktur (kompakt, ohne Token-/Kosten-Aggregate):

{
  "running": true,
  "chat_id": "UUID des Chats",
  "chat_title": null,
  "chat_kind": "mainAgent",
  "sub_agent": false,
  "parent_chat_id": null,
  "parent_preset": null,
  "used_preset": "Name der verwendeten KI-Voreinstellung (Preset)",
  "model_preset": "Name des aufgelösten Modell-Presets (inkl. Fallback)",
  "provider": "Provider-Name (tatsächlich verwendet)",
  "model": "Modellname (tatsächlich verwendet)",
  "identifier": "Konfigurierter Identifikator",
  "initial_text": "Anfang der Benutzeranfrage...",
  "start": "2026-02-12T10:00:00.000Z",
  "user_name": "benutzername",
  "user_id": "UUID des Benutzers"
}
  

Final-POST (Chat-Ende oder Fehlerfall)

Der Final-POST enthält die aggregierten Nutzungsdaten. Bei Fehlern kommen zusätzlich error_type und error_text hinzu.

{
  "running": false,
  "protocol_id": "(optional) Protokoll-ID, falls im Verlauf gesetzt",
  "used_preset": "Name der verwendeten KI-Voreinstellung (Preset)",
  "model_preset": "Name des aufgelösten, tatsächlich verwendeten Modell-Presets (inkl. Fallback)",
  "provider": "Provider-Name (tatsächlich verwendet)",
  "model": "Modellname (tatsächlich verwendet)",
  "tokens_input": 1234,
  "tokens_output": 567,
 "tokens_albert_output": 890,
  "tokens_cache_read": 100,
  "tokens_cache_write": 50,
  "tool_call_count": 3,
  "cost": 0.0045,
  "currency": "EUR",
  "cost_conversion_factor": 1,
  "identifier": "Konfigurierter Identifikator",
  "initial_text": "Anfang der Benutzeranfrage...",
  "id": "Eindeutige ID des Nutzungsprotokolls",
  "start": "2026-02-12T10:00:00.000Z",
  "end": "2026-02-12T10:01:30.000Z",
  "user_name": "benutzername",
  "user_id": "UUID des Benutzers",
  "chat_id": "UUID des Chats",
  "chat_title": "Generierter Chat-Titel",
  "chat_kind": "mainAgent",
  "sub_agent": false,
  "parent_chat_id": null,
  "parent_preset": null,
  "error_type": "(optional) result.error.type",
  "error_text": "(optional) result.error.text"
}