KI-Agenten mit OpenTelemetry tracen
Wie man autonome Agenten mit den GenAI-Konventionen von OpenTelemetry instrumentiert, sodass jeder Reasoning-Schritt, Tool-Aufruf und jede Kostenposition in einem portablen Trace landet.
Definition
Agenten-Tracing zeichnet den vollständigen Ausführungspfad eines Agentenlaufs als Span-Baum auf — Prompts, Modellaufrufe, Tool-Aufrufe und Sub-Agenten-Schritte — jeweils mit Timing, Tokens und Ergebnis. Die GenAI-Konventionen von OpenTelemetry werden zum De-facto-Standard, diese Spans portabel darzustellen.
Wenn ein Agent versagt, ist die Frage immer dieselbe: Was hat er eigentlich getan? Tracing beantwortet sie. Ein Trace macht aus einem dreißig Sekunden langen Lauf mit fünf Tools einen lesbaren Baum, den man Schritt für Schritt prüfen kann.
Was ein Trace erfasst
Ein Trace ist der vollständige Baum eines Agentenlaufs. Jeder Knoten ist ein Span: ein Prompt, ein Modellaufruf, ein Tool-Aufruf, ein Sub-Agenten-Schritt. Ein guter Span hält Operationstyp, Ein- und Ausgaben, Token-Zahlen, Kosten, Latenz und Status fest. Von oben nach unten gelesen, rekonstruieren die Spans genau, wie der Agent dachte und handelte.
Das ist die Einheit für drei Dinge zugleich: Debugging (wo lief es schief), Bepreisung (welcher Schritt verbrannte Tokens) und Audit (welche Entscheidung führte zu welcher Aktion).
| Span-Attribut | Was es aufzeichnet | Wofür |
|---|---|---|
| Operationstyp | Modellaufruf, Tool-Aufruf, Retrieval, Sub-Agent | Den Lauf als Baum lesen |
| Ein-/Ausgaben | Prompt und Ergebnis, eingegrenzt | Debugging |
| Tokens | Prompt- und Completion-Tokens | Bepreisung |
| Kosten | Auf den Schritt entfallendes Geld | FinOps und Budgets |
| Latenz | Wie lange der Schritt dauerte | Performance |
| Status | Erfolg oder Fehler | Fehler lokalisieren |
Warum die GenAI-Konventionen von OpenTelemetry?
Die wichtige Verschiebung 2025 war die Konvergenz auf die GenAI-Konventionen von OpenTelemetry. Statt dass jede Plattform ihr eigenes Trace-Format erfindet, folgen Agenten-Spans einem gemeinsamen Schema. Zwei praktische Gewinne:
- Portabilität. Ihre Traces sind nicht an einen Anbieter gebunden; jedes kompatible Backend kann sie lesen.
- Vereinheitlichung. Agenten-Spans liegen neben Ihren bestehenden Service-Traces, sodass ein Backend den ganzen Stack abdeckt.
Dedizierte Agenten-Observability-Plattformen liefern Mehrwert obendrauf — Session Replay, Time-Travel-Debugging, Agenten-Dashboards — doch der Standard schützt Sie, während die Tools wechseln.
Einen Agenten instrumentieren
- Modellaufrufe umhüllen. Pro Inferenz einen Span mit Token- und Kostenattributen ausgeben.
- Jedes Tool umhüllen. Ein Span pro Tool-Aufruf mit Ein-, Ausgaben und Status — hier verstecken sich die meisten Fehler.
- Sub-Agenten verschachteln. Kind-Spans unter dem Eltern-Lauf bewahren den Baum.
- Kontext propagieren. Tragen Sie den Trace-Kontext über asynchrone Schritte, damit der Baum verbunden bleibt.
- Asynchron exportieren. Sampeln und exportieren Sie abseits des Hot Paths, damit der Overhead vernachlässigbar bleibt.
Von Traces zum Betrieb
Sobald Traces existieren, folgt der Rest der Observability von selbst: Completion-Rate, Kosten pro Aufgabe und Latenz sind Aggregationen über Spans; Loop-Detection ist ein Muster über ihnen; und die Audit-Logs, die Governance erwartet, sind Ihre manipulationssicher gemachten Traces. Beginnen Sie damit, einen Agenten end-to-end zu tracen — alles andere baut darauf auf. Begriffe stehen im Glossar.
Häufige Fragen
Warum OpenTelemetry statt eines Anbieter-SDK?
Weil es Ihre Traces genau dann portabel hält, wenn sich das Tooling rund um Agenten am schnellsten ändert. Mit den GenAI-Konventionen von OpenTelemetry folgen Agenten-Spans einem gemeinsamen, offenen Schema und landen im selben Backend wie der Rest Ihrer Dienste, sodass Sie eine Sicht auf Ihren ganzen Stack erhalten statt eines isolierten Agenten-Silos. Ein Anbieter-SDK kann durchaus reiche Traces erfassen, und die guten emittieren oder lesen den Standard, doch nur auf einem proprietären Format zu bauen heißt, dass Ihre Historie und Ihre Dashboards der Roadmap und Preisgestaltung eines einzigen Lieferanten ausgeliefert sind. Die pragmatische Haltung ist, zuerst gegen die offene Konvention zu instrumentieren und dedizierte Plattformen als Mehrwert obendrauf zu behandeln — Session Replay, Agenten-Dashboards, Time-Travel-Debugging — statt als Fundament. So können Sie später Tools wechseln oder ergänzen, ohne Ihre Agenten neu zu instrumentieren, ein reales Risiko in einem Feld, in dem die heute führende Plattform nicht die des nächsten Jahres sein muss. Portabilität ist jetzt billig zu wählen und später teuer nachzurüsten.
Was sollte ein Span für einen Agenten erfassen?
Jeder Span sollte genug festhalten, um einen Schritt des Laufs zu rekonstruieren und abzurechnen, also mindestens sechs Dinge: den Operationstyp (Modellaufruf, Tool-Aufruf, Retrieval oder Sub-Agenten-Schritt), die Ein- und Ausgaben auf passender Detailebene, Token-Zahlen, monetäre Kosten, Latenz und einen Status, der sagt, ob es gelang. Das Erfassen von Ein- und Ausgaben verlangt Augenmaß — Sie wollen genug zum Debuggen, ohne Geheimnisse oder riesige Blobs zu loggen, also grenzen oder redigieren Sie sensible Felder und kürzen, wo nötig. Der Operationstyp lässt einen Betrachter den Lauf als lesbaren Baum darstellen; Tokens und Kosten machen denselben Span zu einem FinOps-Datensatz; Latenz und Status machen ihn zum Performance- und Fehlersignal. Von oben nach unten gelesen, rekonstruieren wohlgeformte Spans genau, wie der Agent dachte und handelte, weshalb die Disziplin, diese Attribute konsistent anzuhängen, mehr zählt als ein bestimmtes Tool. Ein Span ohne Tokens lässt sich nicht bepreisen; einer ohne Status nicht triagieren.
Verursacht Tracing nicht zu viel Overhead?
In der Praxis nein, denn Tracing ist günstig im Vergleich zu dem, was Latenz und Kosten eines Agenten dominiert: der Modell-Inferenz. Ein Span ist eine kleine Menge strukturierter Metadaten; eine Inferenz sind Hunderte Millisekunden und echtes Geld, sodass der relative Overhead, den Schritt aufzuzeichnen, vernachlässigbar ist. Zwei Standardtechniken halten das so. Asynchroner Export verlagert die Arbeit des Span-Versands vom Hot Path, sodass Ihr Agent nicht auf das Telemetrie-Backend wartet, und Sampling erlaubt, vollen Detailgrad auf einem repräsentativen Bruchteil der Läufe aufzuzeichnen und dennoch jeden Lauf für Aggregatmetriken zu zählen. Der Fehler ist, Tracing zur Overhead-Ersparnis wegzulassen und dann blind zu fliegen, wenn ein Agent schleift, versagt oder das Budget überzieht — die Kosten, nicht zu sehen, was geschah, übersteigen die Kosten der Aufzeichnung bei Weitem. Behandeln Sie Tracing als Teil des Agenten, nicht als optionalen Zusatz, und stimmen Sie Sampling und Aufbewahrung auf Ihr Volumen ab, statt es abzuschalten.
Was ist der Unterschied zwischen Trace, Span und Log?
Ein Span ist die Aufzeichnung einer einzelnen Operation — eines Modellaufrufs, eines Tool-Aufrufs — mit Startzeit, Dauer, Attributen und Status. Ein Trace ist der Baum aus Spans, die zusammen einen vollständigen Agentenlauf darstellen, über Eltern-Kind-Beziehungen verknüpft, sodass Sie sehen, dass dieser Tool-Aufruf innerhalb jenes Planungsschritts innerhalb jenes Sub-Agenten geschah. Ein Log hingegen ist eine einzelne Nachricht mit Zeitstempel, nützlich für punktuelle Details, aber flach: ein Strom von Zeilen ohne die Struktur, die zeigt, wie Schritte sich verschachteln und zueinander stehen. Für Agenten ist der Trace die Einheit, die zählt, denn die interessanten Fehler betreffen Reihenfolge und Kausalität — der Agent rief ein vergiftetes Dokument ab, dann tätigte er einen ungewöhnlichen Tool-Aufruf —, was ein Baum erfasst und ein Log-Strom verschleiert. In der Praxis emittieren Sie weiterhin Logs, hängen sie aber an den passenden Span, damit sie dessen Kontext erben. Denken Sie an Spans als die Schritte, an den Trace als die ganze Geschichte und an Logs als Anmerkungen an einzelnen Schritten.