Az ügynök (agent) gyakran befejez egy feladatot helyes végeredménnyel, miközben fölösleges vagy költséges lépéseket hajt végre: többször keres, megismétel egy fájlolvasást, vagy extra modellhívásokat tesz. Ezek a pazarló lépések növelik a latenciát és a tokenfelhasználást, és több hibalehetőséget teremtenek. Ahhoz, hogy fejlesztők célzottan javítsák egy agent viselkedését, nem elég csak egy sikerellenőrzés; szükség van részletes nyomkövetésre arról, hogyan hajtotta végre a feladatot.
Ez a bemutató két Hermes Agent példát futtat a NeMo Relay segítségével, és a keletkező trace-ekből vizsgálja a modell- és eszközhívásokat, hibákat, újrapróbálkozásokat, időtartamot és tokenhasználatot. A bemutatott módszerrel összevetik a trace-ek bizonyítékát a feladatverifikáció eredményével, és egy Hermes ToolPerf esettanulmányon keresztül megmutatják, hogyan lehet ismételt futtatásokon keresztül kiértékelni harness-változtatásokat.
Mire tanít a tutorial
A leírás és a hozzá tartozó videó lépésről lépésre megmutatja, hogyan kell:
- Létrehozni egy izolált Hermes Agent futtatókörnyezetet NeMo Relay integrációval.
- Lefuttatni egy egyszerű terminál-eszköz feladatot és megvizsgálni az eseményfolyamot és trajectory-t.
- Lefuttatni egy fájl- és webalapú kutató feladatot, majd az OpenTelemetry trace-et Arize Phoenix-ben böngészni.
- Összekapcsolni a feladatverifikációt a trace-bizonyítékokkal egy agent harness-változtatás értékeléséhez.
Előfeltételek
Mielőtt nekiáll, szükséges:
- macOS vagy Linux
- Git és curl
- Docker Desktop vagy Docker Engine
- Egy NVIDIA Build API kulcs az NVIDIA Nemotron 3.5 Lightning modellhez (a modell oldalán válassza a Generate API Key opciót)
NeMo Relay és a Hermes Agent együttműködése
A NeMo Relay egységes módot ad a modell- és eszközvégrehajtás megfigyelésére és vezérlésére. A népszerű Hermes Agent harness natívan tartalmazza a NeMo Relay-t; a futásokat, köröket, modell- és eszközhívásokat a Relay scope-hierarchiájában képviseli, és életciklus eseményeket rögzít a munka kezdete és vége szerint, megőrizve a szülő-gyerek kapcsolatok időzítését.
A trace kimenetek megértése
Három, egymást kiegészítő reprezentációt használ a tutorial:
- Agent Trajectory Observability Format (ATOF): JSONL log scope-startokkal, scope-endekkel és időbélyeggel. Használható egyedi események, időzítések és parent-child kapcsolatok auditálására.
- Agent Trajectory Interchange Format (ATIF): lépésenkénti JSON rekord az interakciókról, eszközhívásokról és megfigyelésekről; jól használható pályák áttekintésére.
- OpenTelemetry (OpenInference exporterrel): a futást span-ekként rögzíti, ahol agent-, LLM- és tool-span-ek vannak címkézve attribútumokkal; OTEL-kompatibilis eszközökben (például Arize Phoenix) lehet vizsgálni a modell- és eszközhívásokat, időtartamot, tokenhasználatot és hibákat.
Fontos megjegyzés: egy ATIF eszközkérés megmutatja, mit kért a modell, de önmagában nem igazolja az eszköz sikerét; a megerősítéshez az ATOF-ban keressük a megfelelő tool start és end eseményeket és esetleges hibákat (a közös uuid párosítja az eseményeket, a parent_uuid csatolja a hívást a szülőhöz).
Ügyeljen a trace-ek átvizsgálására megosztás előtt: konfigurációtól függően tartalmazhatnak promptokat, model-válaszokat, eszközargumentumokat, fájlútvonalakat és egyéb érzékeny adatokat.
NeMo Relay a vállalati biztonsági és megfelelőségi réteg szerepét is betölti: rendezett nyomkövetést ad, amelyet auditorok, biztonsági rendszerek és policy-értékelők használhatnak az agent-viselkedés vizsgálatához és a kontrollok javításához.
Kísérlet #1: egyszerű terminál-eszköz feladat futtatása
Az első példa kicsi és determinisztikus: Hermes a beépített terminal toolt használja egy Python szkript futtatására egy izolált Docker konténerben. A szkript egyszerűen kiírja:
VALUE=42
Ez az állandó kimenet pontos sikerellenőrzést ad. Egy sikeres futtatás megerősíti, hogy Hermes elérte a modellt, meghívta a terminál eszközt a sandboxban, és létrehozta a NeMo Relay trace fájlokat. A konténer nem fér hozzá hálózathoz, repository-hoz vagy NVIDIA API kulcshoz, és Hermes sem futtathat host-parancsokat fallbackként.
A reprodukcióhoz futtassa a következő parancsokat (másolja a keys.env fájlt és írja bele az NVIDIA_API_KEY értékét):
- git clone https://github.com/NVIDIA/nemoclaw-community
- cd nemoclaw-community/examples/tools/hermes-relay-tracing
- ./scripts/setup_tutorial_runtime.sh
- cp keys.env.example keys.env (szerkessze és adja hozzá az NVIDIA_API_KEY-t)
- docker version (ellenőrizze, hogy Docker fut)
- ./scripts/build_tutorial_image.sh
- ./scripts/run_tutorial.sh
A setup a .tutorial-runtime/ könyvtárban hoz létre egy önálló környezetet, amely tartalmazza a szükséges függőségeket (például Python 3.11, Hermes 0.21.1 és NeMo Relay 0.8.3), anélkül, hogy megváltoztatná a rendszer Python- vagy Hermes-installációját. A futtatás után a runner ellenőrzi a választ és a trace fájlokat: ha a futás átmegy, egy "Task verified: VALUE=42" sor látható, majd az ATOF és ATIF összegzés.
Példa kimeneti összegzés egy ellenőrzött futásból (számok futásonként változhatnak):
ATOF summary
- events: 74
- completed llm scopes: 2
- llm scopes with usage: 2
- prompt tokens: 7239
- completion tokens: 96
- total tokens: 7335
- tool calls: 1
- tool errors: 0
- correlated events: 74
ATIF summary
- agent: Hermes Agent
- model: nvidia/nemotron-3.5-lightning-30b-a3b
- steps: 3
- llm calls: 2
- requested tool calls: 1
Task verified: VALUE=42
Az "Artifacts:" sor mutatja a futás könyvtárát, ahol a teljes ATOF eseményfolyam és ATIF trajectory megtalálható.
Kísérlet #2: többeszközös kutató feladat és Phoenix trace vizsgálat
A második példa összetettebb: Hermes kap egy utazási rekordot nyomokkal egy névtelen gépi tanulási konferenciáról. A feladat: beolvasni a rekordot, megtalálni a konferenciát a megadott témához, dátumhoz és helyszínhez illeszkedően, megerősíteni az információt az hivatalos weboldalon, elmenteni egy jelentésbe és visszaadni a konferencia nevét.
A NeMo Relay OpenInference exportere segítségével OpenTelemetry span-eket küldünk az Arize Phoenix-nek OTLP-n keresztül; Phoenix-ben az interaktív trace megmutatja a modell- és eszközhívásokat, időzítést, tokenhasználatot, hibákat, és az elérhető bemeneteket/kimeneteket. Ugyanezt az OTEL trace-et más OTLP-kompatibilis backendeknek (például LangSmith) is el lehet küldeni a végpont és hitelesítés módosításával.
A példa újrahasználja az NVIDIA Nemotron modellt és az API kulcsot az első kísérletből, Hermes beépített kulcsmentes webkeresőt használ, és a runner Phoenix-t egy helyi, pinned konténerben indítja el. A konferencia-kutatást így futtathatjuk:
./scripts/run_conference_research_with_phoenix.sh
A futás során NeMo Relay helyben menti az ATOF eseményfolyamot és az ATIF trajectory-t. A runner sikerjelentése előtt ellenőrzi, hogy Hermes:
- azonosította a COLT 2026 nevű konferenciát;
- mentett egy jelentést, amely tartalmazza a várt konferenciaadatokat és a hivatalos forrást;
- sikeresen végrehajtotta a read_file, web_search, web_extract és write_file hívásokat;
- létrehozott egy nemüres ATIF trajectory-t;
- tokenhasználattal rendelkező modell- és eszközspan-eket küldött Phoenix-nek.
A terminál kimenete linket ad a Phoenix projekthez és a helyi futás könyvtárához; Phoenix-ben végigkövethető a futás a fájlolvasástól a webkeresésen és forrásellenőrzésen át a jelentésírásig.
Megjegyzés: ha másik modellre szeretné átvinni a feladatot, a minta-repozitórium leírja hogyan kell profilt váltani; fontos, hogy a keresési válaszok élő jellegéből adódóan ezek a futások inkább a viselkedés felfedezésére alkalmasak, nem közvetlen modellrankingre – kontrollált összehasonlításhoz rögzített keresési válaszokra és ismételt futtatásokra van szükség.
Trace-ek használata harness-változtatás kiértékelésére
Az egyszeri futások vizsgálata hasznos, de egy változtatás értékeléséhez kontrollált, ismételt környezetre és determinisztikus sikerellenőrzésre van szükség. A javasolt lépések:
- Válasszon fix feladatot pontos, automatikus sikerellenőrzéssel.
- Definiáljon egy baseline-t és egy egyetlen, fókuszált változtatást (prompt, eszköz, konfiguráció, vagy harness).
- Tartson minden mást változatlanul (modell snapshot, provider, bemenet, végrehajtási keret, timeout).
- Futtassa ugyanannyi ismétlést baseline-ra és candidate-re NeMo Relay bekapcsolva.
- Először hasonlítsa össze a verifikált kimeneteket; majd vizsgálja a trace-eket modellhívások, eszközhívások, retry-k, hibák, eltelt idő, tokenhasználat és költség szempontjából.
- Ismételje több modellel vagy terheléssel, ahol a változtatás hatása várható.
Egy változtatást csak akkor tekintsen javulásnak, ha ismétlődően növeli a sikerességet, vagy megtartja a sikerességet miközben javítja a megbízhatóságot, késleltetést vagy költséget.
Benchmark esettanulmány: Hermes ToolPerf
A Hermes ToolPerf benchmarkot a Nous Research fejlesztette a gyártási session-ök elemzése, eszközsémák auditálása és a session logok hibamintáinak feltárása után. NeMo Relay ATOF trace-eket használtak ground-truth turn-számlálásra. Kilenc hibamintát vizsgáltak, majd determinisztikus benchmark esetekké alakították, és ezeket használták egy batch Hermes tool-layer javítások kiértékelésére.
Az "August 6 rerun" egy rögzített baseline-t és javított revíziókat hasonlított össze kilenc feladaton. Minden feladatot háromszor futtattak modell/karonként, ami összesen 108 futtatást eredményezett, ugyanazokkal a promptokkal, eszközökkel, végrehajtási korlátokkal és sikerellenőrzésekkel. A verifikátor mérte a completiont, és a NeMo Relay ATOF trace-ek rögzítették a modellhívásokat, eszközhívásokat, hibákat, retry-kat, tool-result adatokat és időzítést.
A fő eredmények (két modell, baseline vs fixes):
- Claude Sonnet 4.5: baseline 24/27 (89%) siker, mean LLM calls 2.9, mean tool calls 2.2, mean tool result data 17 KB, mean duration 16 s. Fixes: 23/27 (85%), 2.8 LLM calls, 2.1 tool calls, 17 KB, 22 s.
- Qwen3 Coder 30B: baseline 19/27 (70%), mean LLM calls 3.8, mean tool calls 2.8, mean tool result data 16 KB, mean duration 27 s. Fixes: 22/27 (81%), mean LLM calls 4.9, mean tool calls 3.9, mean tool result data 33 KB, mean duration 42 s.
A Sonnet esetében nem volt érdemi változás; a Qwen3 Codernél viszont a javítások növelték a sikeres futások számát (három futásnyi javulás), ugyanakkor a futások több LLM- és eszközhívást, nagyobb eredmény-adatmennyiséget és hosszabb időtartamot eredményeztek. Az audit megmutatta, hogy a megnövekedett fordulatszám jórészt a helyreállításokból (recovery) adódott, vagyis a javítások olyan helyzetekben segítettek befejezni a feladatokat, amelyeket a baseline feladott. Másfelől egyes feladatoknál a javítások extra, felfedező keresésekhez vezettek, ami regressziót okozott.
A trace-ek adották a részletes bizonyítékot: minden modellhívás, eszközhívás, hiba, retry, payload és időzítés rögzítve volt mind a 108 futtatásnál, így az eredmények visszavezethetők a nyers adatokra.
Következtetések és további lépések
A NeMo Relay egységes, strukturált nyomkövetést biztosít az agent viselkedésének vizsgálatához és a harnessok optimalizálásához. Az ATOF megőrzi az életciklus események rendezett sorát, az ATIF olvasható trajectory-t ad, és az OpenTelemetry-exporterek integrálhatók OTEL-kompatibilis megfigyelőeszközökkel (például Arize Phoenix). Egy determinisztikus verifikátorral párosítva ezek a trace-ek lehetővé teszik a harness-változtatások összehasonlítását anélkül, hogy a kevesebb modellhívást automatikusan jobb eredményként értelmeznénk.
A companion repository tartalmazza a futtatható példákat, verifikátorokat, NeMo Relay konfigurációt és Phoenix beállítást, amelyeket a posztban bemutattak.
További olvasnivaló:
- NeMo Relay dokumentáció (telepítés, koncepciók, konfiguráció)
- Hermes Agent dokumentáció (telepítés, használat)
- Companion tutorial repository (a posztban szereplő futtatható példákhoz)
- ATOF és ATIF dokumentáció (esemény- és trajectory-formátumok)
- NeMo Relay observability konfiguráció (exporterek és telemetry célpontok beállítása)
- Támogatott integrációk listája (NeMo Relay más agent frameworkokkal való használata)
(Használja a mellékelt repót és a fenti parancsokat, hogy reprodukálja a példákat és megnézze a telemetriai kimeneteket saját környezetében.)
