NVIDIA NeMo Relay: Offizielles Tutorial zeigt Tracing für Agenten

NVIDIA stellt offizielles Tutorial für Tracing mit NeMo Relay vor

NVIDIA hat ein offizielles Tutorial und eine zugehörige Dokumentation veröffentlicht, die zeigen, wie sich mit NeMo Relay Agenten-Traces erfassen und analysieren lassen. Das Tutorial führt zwei Hermes-Agent-Beispiele aus, um Modell- und Tool-Aufrufe, Fehler, Retries, Dauer und Token-Nutzung zu inspizieren. Die Auswertung erfolgt über OpenTelemetry und Arize Phoenix. Laut NVIDIA ist der Hintergrund: Ein Agent kann eine Aufgabe abschließen und dennoch einen ineffizienten Weg nehmen. Eine fehlgeschlagene Suche kann eine weitere Suche auslösen, ein abgeschnittener Datei-Lesevorgang kann dazu führen, dass ein Befehl denselben Inhalt erneut abruft. Eine korrekte finale Antwort verdeckt diese zusätzlichen Schritte, obwohl sie die Latenz erhöhen und Token verbrauchen. Ineffizienzen schaffen mehr Gelegenheiten für Fehler. Um das Verhalten eines Agenten zu verbessern, müssen Entwickler verstehen, ob eine Aufgabe erfolgreich war und wie der Agent sie abgeschlossen hat. Eine reine Erfolgsprüfung kann nicht erklären, warum ein Agent sich von einem Tool-Fehler erholt hat, früh gestoppt hat oder zusätzliche Modellaufrufe benötigte. Das Tutorial zeigt, wie man eine isolierte Hermes-Agent-Laufzeit mit nativer NeMo-Relay-Integration einrichtet, eine einfache Terminal-Tool-Aufgabe ausführt und deren Ereignisstrom und Trajektorie untersucht, sowie eine Datei-und-Web-Recherche-Aufgabe ausführt und deren OpenTelemetry-Trace in Arize Phoenix erkundet. Zudem wird gezeigt, wie man Aufgabenverifikation mit Trace-Beweisen kombiniert, um eine Änderung am Agenten-Harness zu bewerten.

Instrumentierung von Scopes bis Lifecycle Events

NeMo Relay instrumentiert eine Reihe von Laufzeitkomponenten: Scopes, Tool Calls, LLM Calls, Middleware, Lifecycle Events, Subscribers, Plugins und adaptives Tuning. Diese Komponenten bilden ein gemeinsames Ausführungsmodell über die unterstützten Bindungen hinweg. Ein Scope definiert den aktiven Besitz und die sichtbaren lokalen Daten; Middleware-Registries sind prioritätsgeordnet und werden lazy sortiert; verwaltete Tool- und LLM-Helfer lösen sichtbare Middleware auf, bevor der Benutzer-Callback ausgeführt wird; Subscriber erhalten Ereignisse, nachdem die Laufzeitarbeit sie erzeugt hat. Diese Architektur sorgt dafür, dass teure Export-Arbeit die verwaltete Ausführung nicht direkt blockiert, kann aber die Zustellung an Subscriber, Flushes und das Herunterfahren verzögern. NeMo Relay ist in Rust gebaut und bietet Bindings für Rust, Python, Node.js, Go und C FFI. Es ist kein Agent Framework, kein Model Provider, keine Vector DB, kein gehosteter Tracing-Dienst, keine Prompt-Authoring-Umgebung, kein vollständiges Agent-Framework oder eine Workbench und kein Ersatz für SDK-Code. Stattdessen ist es die Laufzeitschicht, die diesen Systemen gemeinsame Ausführungsscopes, Middleware, Lifecycle-Events, Subscriber und Plugins bereitstellt. Die Laufzeit verwendet Scope-Stacks, priorisierte Middleware-Registries und Subscriber-Callbacks. Für die Praxis wird empfohlen, scope-lokale Middleware für anfragespezifisches Verhalten zu bevorzugen, Subscriber-Callbacks leichtgewichtig zu halten und Binding-native typisierte Wrapper zu verwenden, wenn Provider-Payload-Konvertierung sonst an vielen Stellen wiederholt würde.

Integration über CLI, SDK und OpenTelemetry-Export

NeMo Relay lässt sich über verschiedene Wege integrieren: CLI, SDK, Integrationen, Framework-Wrapper oder Plugin. Die Wahl hängt davon ab, wo Relay die reale Arbeit beobachten oder steuern kann. Ein CLI-Sidecar eignet sich, wenn die Arbeit in einer lokalen Coding-Agent-Sitzung stattfindet; direkte SDK-Instrumentierung, wenn Relay in den Anwendungscode eingebettet werden soll; verwaltete Integrationen für Frameworks wie LangChain, LangGraph und Deep Agents; Framework-Wrapper, wenn ein bestehendes Framework um Relay-Funktionen erweitert werden soll; und Plugins, wenn Relay als Teil einer bestehenden Laufzeit konfiguriert wird. NeMo Relay unterstützt die OpenTelemetry GenAI Konventionen und kann Observability-Daten an Drittsysteme exportieren. Die CLI lässt sich einfach installieren: über pip mit `pip install nemo-relay-cli-bin` oder `pip install "nemo-relay[cli]"` für Python-API-Nutzer, oder über Installer-Skripte für Linux, macOS und Windows. Nach der Installation steht der Befehl `nemo-relay --version` zur Verfügung. Die Integrationen für LangChain und LangGraph erfassen Modell- und Tool-Aufrufe über die verwaltete Ausführung von NeMo Relay und leiten bei Verwendung von ChatNVIDIA Request-Header weiter. Für Deep Agents werden zusätzlich Marks für Skills, Subagents und Human-in-the-Loop-Lifecycle-Events erfasst. Die Observability-Daten können an Drittsysteme exportiert werden, wobei die Details im Ökosystem-Guide beschrieben sind.

Token-Nutzung: Widerspruch zwischen Tutorial und OpenTelemetry-Output

Es gibt einen Widerspruch bei der Token-Nutzung. Das offizielle NVIDIA-Tutorial sagt, man könne mit den resultierenden Traces die Token-Nutzung inspizieren. Classmethod, ein japanischer IT-Dienstleister, berichtet dagegen, dass Token counts nicht aus dem OpenTelemetry-Output kommen. Der Widerspruch lässt sich vermutlich durch das Ausgabeziel erklären: Bei OpenTelemetry fehlen Token counts, während andere Ausgabeformate wie Trajectory-Dateien sie enthalten könnten. Classmethod weist darauf hin, dass die Diskrepanz je nach Ausgabeziel erheblich variiert und man vorab wissen sollte, welche Zahlen man benötigt. Das Tutorial selbst erwähnt, dass man den Ereignisstrom und die Trajektorie einer einfachen Terminal-Tool-Aufgabe untersucht und für eine Datei-und-Web-Recherche-Aufgabe den OpenTelemetry-Trace in Arize Phoenix erkundet. Es ist also möglich, dass die Token-Nutzung in den Trajectory-Dateien sichtbar ist, aber nicht im OpenTelemetry-Export. Diese Unterscheidung ist für Entwickler relevant, die Token-Verbrauch messen wollen.

Voraussetzungen für den Einstieg in das Tutorial

Für den Einstieg in das offizielle Tutorial werden folgende Voraussetzungen benötigt: macOS oder Linux als Betriebssystem, Git und curl für die Installation und das Klonen von Repositories, Docker Desktop oder Docker Engine (installiert und laufend) sowie ein NVIDIA Build API key für NVIDIA Nemotron 3.5 Li. Die CLI-Installation von NeMo Relay ist einfach: Sie erfolgt über pip mit `pip install nemo-relay-cli-bin` oder `pip install "nemo-relay[cli]"`, alternativ über Installer-Skripte, die per curl oder PowerShell heruntergeladen und ausgeführt werden. Nach der Installation kann die CLI mit `nemo-relay --version` verifiziert werden. Der Installer unterstützt Linux x86_64/ARM64, macOS Apple Silicon und Windows x86_64. Für das Tutorial selbst wird eine isolierte Hermes-Agent-Laufzeit mit nativer NeMo-Relay-Integration eingerichtet, die keine separate Observability-Plugin- oder Relay-CLI-Einrichtung erfordert.

GitHub als zentraler Ort für Community und Beiträge

Das GitHub-Repository von NeMo Relay dient als primärer Einstiegspunkt für Community und Beiträge. Dort finden sich die Contributing-Richtlinien sowie die Dokumentation zu unterstützten Integrationen und dem Ökosystem. Die Weiterentwicklung und Diskussion finden im Repository statt. Entwickler, die zu NeMo Relay beitragen möchten, beginnen mit der CONTRIBUTING.md im Repository-Root und lesen dann die Abschnitte zu Integrationen und Ecosystem.