Usage Protocol/Nutzungsstatistiken protokollieren

Technischer Name: agorum_ai_usage_protocol

Anzeigename: Nutzungsstatistiken protokollieren

Was macht der Handler?

Der Handler agorum_ai_usage_protocol erfasst und sendet Nutzungsstatistiken per HTTP POST an einen externen Endpunkt, sobald ein Chat abgeschlossen ist. Ein Chat gilt als abgeschlossen, wenn die letzte Antwort des KI-Assistenten keine weiteren Tool-Aufrufe enthält.

Voraussetzung:

Um die Kostenberechnung zu nutzen, müssen in der KI-Voreinstellung die Token-Preise konfiguriert sein. Die Preise werden automatisch aus der Voreinstellung ausgelesen und für die Berechnung verwendet.

Erfasste Daten:

• Token-Verbrauch (Input, Output, Cache-Read, Cache-Write)
• 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 (keine weiteren Tool-Aufrufe).
2. Ist der Chat abgeschlossen, werden alle relevanten Nutzungsdaten aus der Chat-Historie aggregiert.
3. Die Daten werden als JSON-Payload per HTTP POST an die konfigurierte URL gesendet.
4. Optional kann ein Bearer-Token zur Authentifizierung verwendet werden.

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": "UUID des Protokolls",
  "used_preset": "Name der verwendeten KI-Voreinstellung",
  "model_preset": "Name des aufgelösten Modell-Presets",
  "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"
}