AI-Agent-Monitoring: LLM- und MCP-Aufrufe mit OpenTelemetry verfolgen

Ein produktiver KI-Agent erzeugt während einer Aufgabe mehrere Modellaufrufe, wählt Tools aus und greift über MCP auf externe Systeme zu. Der Chat-Log zeigt meist nur Prompts und Antworten, während Timeouts, Wiederholungen und abgewiesene Berechtigungen in anderen Systemen liegen. Der Zusammenhang fehlt. Chat-Logs sind deshalb für produktive KI-Agenten kein Monitoring, weil sie weder die zeitliche Abfolge noch die Abhängigkeiten eines Agentenlaufs vollständig abbilden.

OpenTelemetry verbindet die beteiligten Komponenten durch Trace-Kontext, gemeinsame Attribute und korrelierte Logs. Teams betrachten bei LLM Observability den Modellaufruf, bei AI Agent Tracing die Entscheidungen und Tool-Kette und bei MCP Tracing den Pfad bis zum externen Server. Wer Agentenarchitekturen zunächst fachlich abgrenzen möchte, findet unter AI Agents & Multi-Agent Systems ergänzende Themen zu Orchestrierung, Tool-Nutzung und kontrollierter Automatisierung.

Warum Chat-Logs für KI-Agenten nicht ausreichen

Ein Prompt und die zugehörige Antwort erklären nicht, warum ein Agent zwölf Schritte statt drei benötigt hat oder welcher Aufruf die Verzögerung auslöste. Der Pfad bleibt im Chat-Log unsichtbar. Das Modell kann dasselbe Tool wiederholt aufrufen, eine fehlerhafte Antwort erneut verarbeiten oder nach einem MCP-Timeout auf einen anderen Pfad wechseln. Wenn jede Komponente nur ihr eigenes Protokoll schreibt, lassen sich Drift, Berechtigungsfehler und wiederholte Tool-Aufrufe nicht demselben Agentenlauf zuweisen.

Was ist AI-Agent-Monitoring mit OpenTelemetry?

OpenTelemetry bildet den vollständigen Lauf eines KI-Agenten als verteilten Trace ab. Untergeordnete Spans zeigen Modellaufrufe, Tool-Ausführungen, MCP-Verbindungen und Zugriffe auf Fachanwendungen. Korrelierte Metriken und Logs ergänzen den Trace um Token-Verbrauch, Fehlerraten und Ereignisdetails für die betroffene Trace-ID, ohne vollständige Prompts speichern zu müssen.

• Traces zeigen, welcher Modell- oder Tool-Aufruf die Ende-zu-Ende-Laufzeit bestimmt
• Metriken erfassen Token-Verbrauch, Kostenschätzungen, Fehlerraten und die Anzahl der Agentenschritte über viele Läufe
• Korrelierte Logs liefern bereinigte Fehlermeldungen und fachliche Ereignisse zur betroffenen Trace-ID

Die Rekonstruktion beginnt mit einer Span-Hierarchie, die alle Aufrufe einer Agentenaufgabe unter derselben Trace-ID zusammenführt.

Agentenlauf, LLM-Aufrufe und Tools als Trace modellieren

Ein mögliches Schema verwendet den Root-Span invoke_agent für die komplette Aufgabe vom Eingang bis zum Ergebnis oder Abbruch. Jeder Modellaufruf erhält einen untergeordneten chat-Span. Tool-Ausführungen erscheinen als execute_tool-Spans, unter denen die Transportaufrufe liegen.

invoke_agent
├── chat
├── execute_tool
│   └── HTTP client
│       └── HTTP server
├── chat
└── execute_tool

Die Zeitstempel bilden die Reihenfolge ab, während Eltern-Kind-Beziehungen den ursächlichen Aufrufpfad zeigen. Ein zweiter chat-Span ist daher gewöhnlich ein weiteres Kind des Root-Spans und kein Kind des vorherigen Tool-Spans. Bei einem instrumentierten HTTP-Transport erzeugen Client und Server eigene Spans innerhalb desselben Traces, sofern der Trace-Kontext die Dienstgrenze passiert.

Die Client-Instrumentierung schreibt den W3C-Trace-Kontext in traceparent und bei Bedarf in tracestate. Instrumentierungen für Nachrichtenwarteschlangen übernehmen den Kontext in die jeweiligen Nachrichten-Header, während Datenbank-Spans den aktiven Elternkontext verwenden. Eine Korrelations-ID verknüpft Datensätze aus Systemen ohne OpenTelemetry-Unterstützung, erzeugt aber keine gemeinsame Trace-Hierarchie. Vertrauliche Werte gehören nicht in baggage, weil nachgelagerte Dienste diese Felder weiterreichen.

Wenn das Team die freigegebenen Tools begrenzt und Ausführungsrechte trennt, lassen sich unerwartete Spans schneller einer fehlerhaften Auswahl oder Berechtigung zuordnen. Das Training Hermes Bot: Eigener KI-Agent mit festen Grenzen behandelt einen selbst betriebenen Agenten mit freigegebenen Tools und beschränkten Berechtigungen. Auf dieser Basis liefern die Span-Attribute die Daten für Kostenanalyse und Fehlersuche.

Die wichtigsten gen_ai.*-Attribute

OpenTelemetry GenAI verwendet gemeinsame Attributnamen, damit Traces aus verschiedenen Instrumentierungen vergleichbar bleiben. Die folgenden Felder erfassen Modellidentität, Operation, Token-Verbrauch und Abschlussgrund.

Ein lokal abgebrochener Aufruf besitzt unter Umständen keine Modellantwort und damit keinen Wert für gen_ai.response.finish_reasons. Ein internes Feld wie app.run.outcome=cancelled hält diesen Zustand fest. Interne Attribute ergänzen die Standardfelder um projektspezifische Angaben:

• Versionen von Agent, Prompt und Workflow
• Die Umgebung als Resource-Attribut
• Die Anzahl der Wiederholungen
• Die Kostenschätzung mit der verwendeten Preisversion
• Eine pseudonymisierte Mandanten-ID in zugriffsbeschränkten Traces

Die Kostenschätzung entsteht aus den Token-Feldern und einer versionierten Preistabelle, die Modell, Anbieter und Gültigkeitszeitraum berücksichtigt. OpenTelemetry entwickelt die GenAI Semantic Conventions weiter, weshalb Instrumentierung, Collector-Konfiguration und verwendete Conventions-Version gemeinsam versioniert werden sollten. Dashboards und Alarmregeln ändern ihr Verhalten dann nicht unbemerkt, wenn neue Attributnamen oder Operationen eingeführt werden. An der MCP-Grenze muss derselbe Trace-Kontext erhalten bleiben.

MCP-Server und externe APIs ohne Trace-Lücken integrieren

Streamable HTTP kann den W3C-Trace-Kontext direkt in HTTP-Headern übertragen. Beim Transport über Standardeingabe und Standardausgabe fehlen diese Header; soll der Server-Span zum selben Trace gehören, müssen Client und Server den Kontext über Metadaten transportieren, die das eingesetzte MCP-SDK unterstützt. Reicht das SDK keine solchen Metadaten durch, entstehen separate Traces, die sich über eine gemeinsame Korrelations-ID suchen lassen, aber keine verteilte Eltern-Kind-Beziehung besitzen.

• Der execute_tool-Span speichert den gewählten Tool-Namen und das Ergebnis der Auswahl
• Ein untergeordneter Span erfasst Argumentvalidierung und Schemafehler
• Jeder Netzwerkversuch erhält einen Span mit Zielsystem, Dauer und Timeout-Status
• Ein weiterer Span misst die Prüfung und Verarbeitung des zurückgegebenen Ergebnisses

Frameworks benennen dieselben Vorgänge oft unterschiedlich. Der Transform Processor des OpenTelemetry Collectors bildet solche Attribute mit OTTL-Regeln auf die Felder der festgelegten gen_ai.*-Version ab. Native Tools und MCP-Tools erscheinen danach in denselben Dashboards.

Fehler benötigen eine maschinenlesbare Kategorie. app.error.category kann beispielsweise zwischen model_failure, permission_denied, timeout und validation_error unterscheiden. Für abgelehnte fachliche Vorgänge ergänzt business_error die Liste. Bevor diese Telemetrie das System verlässt, begrenzt eine Inhaltsrichtlinie die erfassten Daten.

Prompts erfassen, ohne vertrauliche Daten offenzulegen

Prompts, Antworten, Tool-Argumente und Tool-Ergebnisse gehören nur bei ausdrücklich aktivierter Inhaltserfassung in die Telemetrie. Für die meisten Betriebsfragen benötigt ein Trace diese Inhalte nicht. Modellname, Token-Zahlen, Dauer, Tool-Name, Ergebnisgröße und Fehlerkategorie reichen für Kosten-, Latenz- und Verfügbarkeitsanalysen häufig aus.

Die Instrumentierung sollte vertrauliche Inhalte vor dem ersten Export verwerfen. Konfigurierte Collector-Prozessoren bilden eine zweite Sperre und entfernen bekannte Muster für Zugangsdaten, API-Schlüssel oder personenbezogene Kennungen. Freitext bleibt schwieriger. Wenn Dokumentinhalte verarbeitet werden, benötigt die Pipeline dafür eigene Erkennungsregeln oder eine vorgeschaltete Klassifizierung, statt sich auf allgemeine reguläre Ausdrücke zu verlassen. Für Vergleiche eignen sich Template-IDs, Inhaltsklassen, Größenangaben oder ein HMAC mit geheimem Schlüssel besser als vollständige Texte oder ungesalzene Hashes.

Traces, Metriken und inhaltstragende Logs benötigen getrennte Aufbewahrungsfristen und Zugriffsrechte. Metriken verwenden bevorzugt Attribute mit niedriger Kardinalität, während Mandanten- oder Benutzerkennungen nicht als frei durchsuchbare Metrikattribute erscheinen. Auf dieser Datengrundlage lassen sich Alarme konfigurieren, ohne sensible Nutzdaten in Benachrichtigungen zu kopieren.

Fünf nützliche Alarme für produktive KI-Agenten

Der Root-Span sollte aggregierte Felder für Schrittzahl, Tool-Aufrufe, Token-Summen und geschätzte Kosten enthalten. Alarmregeln bewerten dadurch einen vollständigen Agentenlauf, statt einzelne Modellaufrufe isoliert zu betrachten.

1. Ein Alarm meldet das Überschreiten der festgelegten Schrittgrenze oder wiederholte Kombinationen aus Tool-Name und normalisiertem Argument-HMAC
2. Ein Alarm vergleicht die Tool-Aufrufe je Agentenlauf mit der rollierenden Baseline derselben Agenten- und Workflow-Version
3. Ein Alarm erkennt sprunghaft steigende Eingabe-Token, Ausgabe-Token oder geschätzte Kosten pro erfolgreicher Aufgabe
4. Ein Alarm überwacht erhöhte Tool-Fehlerraten, verweigerte Berechtigungen und MCP-Timeouts getrennt nach Fehlerkategorie
5. Ein Alarm vergleicht die Ende-zu-Ende-Dauer mit dem vereinbarten Service-Level-Objective (SLO) und nennt den langsamsten untergeordneten Span für die weitere Analyse

Eine verwertbare Benachrichtigung enthält:

• Die Trace-ID und die Umgebung
• Die Agenten-, Prompt- und Modellversion
• Den betroffenen Span
• Die Fehlerkategorie

Prompt-Inhalte bleiben außerhalb des Alarmtextes. Nach Änderungen an Modell oder Prompt zeigen wiederholbare Referenzaufgaben, ob die Grenzwerte weiterhin zum Agentenverhalten passen. Solche Referenzaufgaben bilden den Ausgangspunkt für Regressionstests.

Golden Tasks und Regressionstests nach Änderungen

Ein Golden Task beschreibt eine wiederholbare Agentenaufgabe mit erwarteten Tool-Berechtigungen, zulässigen Seiteneffekten und einem prüfbaren Ergebnisformat. Die Prüfung bewertet mehr als den Antworttext. Sie betrachtet den vollständigen Trace und zeigt, an welchem Modellaufruf, Tool oder MCP-Server das Verhalten von der freigegebenen Referenz abweicht.

• Der Test bewertet Aufgabenerfolg, Tool-Auswahl und die Zahl der Agentenschritte
• Der Test vergleicht Latenz, Token-Verbrauch und geschätzte Kosten mit der freigegebenen Baseline
• Der Test erkennt unzulässige Tool-Aufrufe, Berechtigungsverstöße und verletzte Inhaltsregeln
• Der Test läuft nach Änderungen an Modell, Prompt, Retrieval, Tool, MCP-Server oder Guardrail

Rollout-Gates legen vor der Bereitstellung fest, welche Abweichungen einen Canary-Rollout stoppen oder ein Rollback auslösen. Der Vergleich berücksichtigt Span-Reihenfolge, Dauer, Status und versionierte Attribute. Das Team übernimmt die Ergebnisse in die Rollout-Checkliste.

Checkliste für den Produktions-Rollout

• Das Team definiert Trace-Hierarchie, Span-Namen, Pflichtattribute und die Strategie für Korrelations-IDs
• Die Instrumentierung umfasst den Agentenlauf, Modell-Clients, Tools, MCP-Verbindungen und nachgelagerte Dienste
• Tail-Sampling-Regeln behalten Fehler, teure Läufe, langsame Traces und sicherheitsrelevante Ereignisse
• Die Telemetrie-Pipeline setzt die Opt-in-Erfassung, die Filterung vertraulicher Inhalte, Zugriffsrechte und getrennte Aufbewahrungsfristen um
• Dashboards zeigen Latenz, Token-Verbrauch, Kostenschätzungen, Tool-Erfolgsraten, Schrittzahlen und SLO-Erfüllung
• Tests mit kontrolliert ausgelösten Fehlern prüfen Alarmwege, Eskalation und dokumentierte Incident-Response-Abläufe
• Ein Upgrade erfolgt erst nach dem Vergleich der Semantic Conventions, Instrumentierungsbibliotheken und Collector-Regeln

Das Seminar Monitoring von KI-Agenten: Kontrolle & Sicherheit behandelt Tracing, Tool-Call-Monitoring, Kostenkontrolle, Regressionstests und Incident Response anhand instrumentierter Agentenabläufe.

Ein vollständiger Trace führt technische Fehler, Token-Kosten und fachliche Seiteneffekte für dieselbe Ausführung zusammen. Beginne mit einem vollständig instrumentierten Golden Task, dessen Trace vom invoke_agent-Span bis zum letzten Tool-Ergebnis reicht. Der daraus entstehende Referenz-Trace liefert die erste Baseline für Dashboards, Alarme und spätere Modelländerungen.