KI-Handler Usage Protocol

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

Eine allgemeine Beschreibung von KI-Handlern finden Sie unter ALBERT | AI KI-Handler einrichten.

Wie die gesendeten Daten anschließend ausgewertet werden – mit Filtern, Kosten-Diagramm und Anomalie-Erkennung –, beschreibt ALBERT | AI Kostenkontrolle verwenden.

Eigenschaft	Wert
Anzeigename in der Oberfläche	KI Nutzungs- & Kostenanalyse: Nutzung und Kosten protokollieren
Technischer Handler-Name	agorum.ai.usage.protocol (Name der mitgelieferten Konfiguration: agorum_ai_usage_protocol_default)
Standardmäßig aktiv	ja
Eingriffspunkte (Hooks)	before, after, error, stop

Wann verwenden

• 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..

Funktionsweise

Der Handler agorum_ai_usage_protocol sendet in folgenden Situationen Nutzungsstatistiken:

1. 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. 
2. 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.
3. 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.

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.

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.
• Der Final-POST (Abschluss und Fehlerfall) enthält zusätzlich das Objekt prices mit den im Preset eingestellten Einzelpreisen.

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)
• Eingestellte Einzelpreise aus dem Preset als Objekt prices (nur im Final-POST).
• 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

Einzelpreise im Final-POST (prices)

Der Final-POST enthält zusätzlich das Objekt prices mit den in der KI-Voreinstellung eingestellten Einzelpreisen. So kann der empfangende Endpunkt eigene Kostenberechnungen anstellen und die bereits gelieferte Summe cost nachvollziehen.

Das Objekt prices enthält folgende Felder:

Feld	Beschreibung
input	Preis pro 1 Million Input-Tokens (Tokens, die an das Modell gesendet werden).
output	Preis pro 1 Million Output-Tokens (Tokens, die vom Modell generiert werden).
cacheRead	Preis pro 1 Million Tokens beim Lesen aus dem Cache.
cacheWrite	Preis pro 1 Million Tokens beim Schreiben in den Cache.
albertOutput	Preis pro 1 Million ALBERT-Output-Tokens (sichtbarer KI-Output auf Basis von result.text inkl. Tool-Calls; ohne reasoningText).
toolCalls	Preis pro 1.000 Tool-Aufrufe.
conversionFactor	Umrechnungsfaktor, falls die Preise in eine andere Währung umgerechnet werden sollen. Entspricht dem Feld cost_conversion_factor.
currency	Währung, in der die Preise angegeben sind (z. B. EUR, USD).

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,
  "prices": {
    "input": 3.00,
    "output": 15.00,
    "cacheRead": 0.30,
    "cacheWrite": 3.75,
    "albertOutput": 0,
    "toolCalls": 0,
    "conversionFactor": 1,
    "currency": "EUR"
  },
  "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"
}

Zusätzliche Nutzungsaufzeichnung für Werkzeugaufrufe über MCP

Ist dieser Handler global hinterlegt und aktiv, empfängt der konfigurierte Endpunkt zusätzlich eine eigene Nutzungsaufzeichnung für Werkzeugaufrufe, die über die MCP-Schnittstelle bei agorum core eingehen (wenn agorum core selbst als MCP-Server verwendet wird). 

• Sind mehrere usage-protocol-Konfigurationen global aktiv, wird die Aufzeichnung an alle dort hinterlegten Endpunkte gesendet.
• Der Handler selbst bleibt dabei unverändert. Die Aufzeichnung folgt lediglich seinem Format und verwendet dieselbe URL, denselben API-Key und denselben identifier der jeweiligen Konfiguration.
• Übertragen wird der Tagesstand des MCP-Anteils. id und chat_id entsprechen der UUID des Tagesobjekts und sind je Tag stabil, sodass der Endpunkt dieselbe Aufzeichnung fortschreibt.
• Erfasst werden ausschließlich ALBERT-Output-Tokens aus den MCP-Werkzeugaufrufen (tokens_albert_output); alle übrigen Token-Felder und tool_call_count sind 0. 
• Werkzeugaufrufe aus dem ALBERT-Chat und aus Agenten sind hiervon nicht betroffen; eine Doppelmeldung findet nicht statt.

Einstellungen

Einstellung	Parameter	Standard	Beschreibung
Endpunkt-URL	url	keiner	Pflichtangabe. Die Endpunkt-URL, an die die Nutzungsdaten per HTTP POST gesendet werden. Beispiel: https://api.example.com/usage
API-Key (Bearer Token)	apiKey	keiner	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.
Identifikator	identifier	keiner	String-Identifikator, der in beiden POSTs mitgesendet wird. Kann zur Kategorisierung oder Kennzeichnung der Protokolleinträge verwendet werden. Beispiele: Abteilung-Vertrieb oder Projekt-X
Max. Zeichen für Anfangstext	initialTextLength	100	Maximale Anzahl an Zeichen, die vom ersten Benutzertext erfasst und mitgesendet werden sollen. Längere Texte werden abgeschnitten und mit "..." gekennzeichnet.

In einer KI-Voreinstellung verwenden

1. Öffnen Sie ☰ > Administration > Konfiguration > KI-Voreinstellungen.
2. Wählen Sie die gewünschte KI-Voreinstellung aus und klicken Sie Bearbeiten.
3. Scrollen Sie zum Bereich KI-Handler und klicken Sie auf KI-Handler hinzufügen.
4. Wählen Sie den KI-Handler KI Nutzungs- & Kostenanalyse: Nutzung und Kosten protokollieren in der Liste aus.
5. Speichern Sie die KI-Voreinstellung.

   Ergebnis: Der Handler sendet Nutzungsstatistiken der Chats mit dieser KI-Voreinstellung als JSON per HTTP POST an den konfigurierten Endpunkt.

Kombination mit anderen Handlern

Frage	Antwort
Reihenfolge	Keine Besonderheiten bekannt.
Geeignete Kombinationen	Keine Besonderheiten bekannt.
Nicht kombinieren mit	Keine Besonderheiten bekannt.