Debugging von KI-Agenten mit NVIDIA NeMo Relay und OpenTelemetry

NVIDIA hat ein technisches Tutorial veröffentlicht, das zeigt, wie sich das Verhalten von KI-Agenten mithilfe von NeMo Relay nachverfolgen und debuggen lässt. Der Leitfaden konzentriert sich auf das Framework Hermes Agent und demonstriert Entwicklern, wie sie strukturierte Lifecycle-Ereignisse erfassen und diese in Tools wie Arize Phoenix visualisieren können. Die im September 2026 veröffentlichte Ressource zielt darauf ab, das Black-Box-Problem zu lösen, das inhärent in komplexen autonomen Systemen besteht.

Was passiert ist

Der NVIDIA Technical Blog hat eine praktische Anleitung zur Implementierung von Observability in KI-Agenten veröffentlicht. Im Mittelpunkt steht NeMo Relay, eine Schicht, die geordnete Ereignisse und Trajektorien während der Agentenausführung aufzeichnet. Das Tutorial nutzt Hermes Agent, der native Unterstützung für dieses Relay-System bietet, um drei Arten von Ausgaben zu generieren: Logs im Agent Trajectory Observability Format (ATOF), schrittweise Aufzeichnungen im Agent Trajectory Interchange Format (ATIF) sowie OpenTelemetry-Spans, die mit OpenInference-Standards gekennzeichnet sind.

Der Artikel beschreibt zwei spezifische Experimente. Das erste umfasst eine einfache Terminalaufgabe, bei der der Agent ein Skript in einem isolierten Docker-Container ausführt, um "VALUE=42" auszugeben. Dies überprüft das grundlegende Setup und stellt sicher, dass der Agent Tools aufrufen und Trace-Dateien ohne Netzwerkzugriff erzeugen kann. Das zweite Experiment ist komplexer: Der Agent muss einen Reiseeintrag lesen, im Web suchen, Konferenzdetails auf einer offiziellen Website überprüfen und einen Bericht erstellen, der "COLT 2026" identifiziert. Dieser mehrstufige Prozess demonstriert, wie Traces Interaktionen über verschiedene Tools und externe Dienste hinweg erfassen.

Über das individuelle Debugging hinaus hebt der Beitrag eine Benchmark-Fallstudie namens Hermes ToolPerf hervor. Forscher nutzten NeMo Relay-Traces, um Änderungen an der Agent-Harness-Umgebung über 108 Läufe hinweg zu bewerten. Sie verglichen eine Basisversion mit einer revidierten Version, die Korrekturen auf Tool-Ebene enthielt. Die Daten zeigten Kompromisse auf, die einfache Erfolgsmetriken nicht erfassen würden, wie etwa erhöhte Latenz und Token-Nutzung, selbst wenn die Abschlussraten der Aufgaben stiegen.

Wie es funktioniert

NeMo Relay funktioniert, indem es den Workflow des Agenten an wichtigen Lifecycle-Punkten abfängt. Es behandelt Sitzungen, Turns, Modellaufrufe und Tool-Aufrufe als hierarchische Scopes. Wenn Arbeit beginnt oder endet, zeichnet das Relay das Ereignis mit präzisen Zeitstempeln und Eltern-Kind-Beziehungen auf. Diese Struktur ermöglicht es Entwicklern, die exakte Sequenz der vom Agenten ausgeführten Aktionen zu rekonstruieren.

Das System exportiert diese Daten in Formaten, die für unterschiedliche Analysebedürfnisse geeignet sind. ATOF bietet ein rohes JSONL-Log, ideal für die Prüfung von Timing und Fehlerzuständen. ATIF setzt diese Ereignisse zu einer lesbaren Erzählung der Entscheidungen des Agenten zusammen. Für die visuelle Inspektion verwendet das Relay einen OpenInference-Exporter, um Daten über das OpenTelemetry Protocol (OTLP) an kompatible Backends zu senden. Im Tutorial ist dieses Backend Arize Phoenix, das die Traces als interaktive Graphen anzeigt, die Modelleingaben, Tool-Ausgaben und Dauermetriken darstellen.

Wichtige Details

• NeMo Relay erfasst drei Ausgabeformate: ATOF für Ereignislogs, ATIF für schrittweise Trajektorien und OpenTelemetry-Spans für die Visualisierung.
• Das Tutorial erfordert macOS oder Linux, Docker, Git und einen NVIDIA Build API Key für Nemotron 3.5 Lightning.
• In den bereitgestellten Beispielen werden Hermes Agent Version 0.21.1 und NeMo Relay Version 0.8.3 verwendet.
• Die Multi-Tool-Rechercheaufgabe identifizierte erfolgreich "COLT 2026", nachdem Dateien gelesen, im Web gesucht und Quellen überprüft wurden.
• Im ToolPerf-Benchmark verbesserte Qwen Coder 30B die Erfolgsquote der Aufgaben von 70 % auf 81 % durch Korrekturen, erhöhte jedoch die durchschnittliche Dauer von 27 s auf 42 s.
• Traces können sensible Daten wie Prompts und Dateipfade enthalten; daher rät die Dokumentation dazu, sie vor dem Teilen zu prüfen.

Warum es wichtig ist

Für Ingenieure, die autonome Agenten entwickeln, garantiert eine korrekte finale Antwort nicht unbedingt einen effizienten oder sicheren Prozess. Ein Agent könnte durch Glück Erfolg haben, indem er fehlgeschlagene Suchvorgänge mehrfach wiederholt oder redundante API-Aufrufe tätigt. Ohne Sichtbarkeit in diese Zwischenschritte können Entwickler Kosten, Latenz oder Zuverlässigkeit nicht optimieren. NeMo Relay bietet die Beweiseebene, die nötig ist, um zwischen robuster Leistung und fragilen Workarounds zu unterscheiden.

Diese Observability ist kritisch für Produktionsumgebungen, in denen Agenten mit externen Tools und Daten interagieren. Durch die Erfassung strukturierter Traces können Teams das Verhalten auf Sicherheitskonformität hin auditieren und Fehler debuggen, die nur unter bestimmten Bedingungen auftreten. Die Möglichkeit, Basis- und revidierte Harnesses anhand konsistenter Metriken zu vergleichen, ermöglicht datengesteuerte Verbesserungen statt Vermutungen. Da Agenten komplexer werden, wird das Verständnis des "Wie" genauso wichtig wie das des "Was".

Was Sie tun können

• Klonen Sie das Begleit-Repository von GitHub, um Zugriff auf lauffähige Beispiele und Verifizierungsskripte zu erhalten.
• Richten Sie eine isolierte Laufzeitumgebung mit dem bereitgestellten Setup-Skript ein, um Konflikte mit bestehenden Python-Umgebungen zu vermeiden.
• Führen Sie zunächst die einfache Terminalaufgabe aus, um zu überprüfen, ob Docker, Hermes und NeMo Relay korrekt konfiguriert sind.
• Untersuchen Sie die generierten ATOF- und ATIF-Dateien, um die Rohstruktur von Agentenereignissen und -trajektorien zu verstehen.
• Stellen Sie Arize Phoenix lokal bereit und führen Sie die Multi-Tool-Rechercheaufgabe aus, um OpenTelemetry-Spans in einer grafischen Oberfläche zu visualisieren.
• Nutzen Sie die Trace-Daten, um Änderungen an Ihren Agenten-Prompts oder Tool-Konfigurationen zu bewerten, bevor Sie diese in die Produktion deployen.