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.

Ein Chat gilt als abgeschlossen, wenn der letzte Verlaufseintrag mit Rolle assistant keine Tool-Calls enthält (toolCalls leer oder nicht vorhanden). Erst dann wird gesendet.

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.

Erfasste Daten

• Token-Verbrauch (Input, Output, Cache-Read, Cache-Write) - Summe über die Chat-History
• 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 und Modell-Preset
• Optionaler Identifikator zur Kategorisierung
• Anfangstext der Benutzeranfrage (gekürzt)

Funktionsweise

1. Nach jedem KI-Aufruf prüft der Handler, ob der Chat abgeschlossen ist (letzte Assistant-Antwort ohne Tool-Calls).
2. Ist der Chat abgeschlossen, werden alle relevanten Nutzungsdaten aus der Chat-Historie aggregiert.
3. Das verwendete Preset wird ausgewertet, inkl. Auflösung von Preset-Referenzen.
4. Wenn ein aktives Fallback im Verlauf markiert ist, wird das tatsächlich verwendete Fallback-Preset für model_preset und die Preisermittlung genutzt.
5. Die Daten werden als JSON-Payload per HTTP POST an url gesendet, optional mit Bearer-Token.

Fallback-Modell und Kosten

Ist im Chat ein Sticky Fallback aktiv, protokolliert der Handler:

• model_preset basierend auf dem tatsächlich verwendeten Fallback-Preset.
• Preise für die Kostenberechnung aus dem tatsächlich verwendeten Fallback-Preset (sofern dort konfiguriert).

Empfohlener Einsatzzweck

Der Handler eignet sich ideal für:

• Kostenüberwachung: Erfassung des Token-Verbrauchs und der daraus resultierenden Kosten pro Benutzer oder pro Chat.
• Nutzungsanalyse: Auswertung, welche KI-Voreinstellungen wie häufig verwendet werden.
• Reporting: Übermittlung der Nutzungsdaten an externe Systeme wie Data Warehouses, BI-Tools oder eigene Dashboards.
• Abrechnungssysteme: Integration in interne Verrechnungssysteme für die KI-Nutzung.
• Compliance: Protokollierung der KI-Nutzung für Audit-Zwecke.

Einstellungen

Parameter	Beschreibung
url (Pflicht)	Die Endpunkt-URL, an die die Nutzungsdaten per HTTP POST gesendet werden sollen. Beispiel: https://api.example.com/usage
apiKey (Optional)	Ein API-Key (Bearer Token) zur Authentifizierung gegenüber dem Endpunkt. Falls angegeben, wird der Key als Authorization: Bearer <apiKey> Header mitgesendet. Das Feld wird verschlüsselt gespeichert.
identifier (Optional)	Ein String-Identifikator, der im Nutzungsprotokoll mitgesendet wird. Kann zur Kategorisierung oder Kennzeichnung der Protokolleinträge verwendet werden. Beispiel: Abteilung-Vertrieb oder Projekt-X
initialTextLength (Optional)	Die 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:

{
  "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)",
  "tokens_input": 1234,
  "tokens_output": 567,
  "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"
}