DI agento pėdsakas su „OpenTelemetry“: įrankio klaida neturi dingti viename žurnale

DI agento veiksmus sujunkite į vieną „OpenTelemetry“ trasą: „invoke_agent“ atkarpa apima paleidimą, „chat“ atkarpos žymi modelio užklausas, o „execute_tool“ – įrankių vykdymą. „OpenTelemetry“ agentų semantinės taisyklės taip pat numato „plan“ atkarpą, kai instrumentavimas gali patikimai atpažinti atskirą planavimo etapą.

Taip matysite, ar eiga nutrūko kreipiantis į modelį, planuojant, ar vykdant įrankį. Gedimui nustatyti pirmiausia reikia susietų atkarpų, jų trukmės, operacijos pavadinimo ir klaidos tipo. Naudotojo užklausos, modelio atsakymo bei įrankio argumentų į trasą pagal nutylėjimą neįrašykite.

Sudėliokite vieno paleidimo atkarpas

„invoke_agent“ pradėkite prieš agentui imantis užduoties ir užbaikite jam pateikus rezultatą arba nutraukus vykdymą. Tame pačiame procese veikiantis agentas žymimas vidine atkarpa, o nuotolinės agento paslaugos iškvietimas – kliento atkarpa. Kiekvienam toliau atliekamam veiksmui perduokite aktyvų trasos kontekstą, kad modelio ir įrankio atkarpos būtų susietos su tuo pačiu paleidimu.

Sąlyginio paleidimo eiga gali būti tokia:

1. „invoke_agent“ apima visą užduotį ir nurodo agento pavadinimą, jei jis žinomas.
2. „plan“ apima atskirą planavimo etapą. Jei planui sudaryti kviečiamas modelis, to iškvietimo „chat“ atkarpa priklauso „plan“ atkarpai.
3. Kita „chat“ atkarpa apima modelio užklausą, per kurią agentas pasirenka įrankį.
4. „execute_tool“ apima patį įrankio vykdymą ir jo baigtį.
5. Po įrankio rezultato sukuriama nauja „chat“ atkarpa, jeigu agentas dar kartą kreipiasi į modelį.

Įrankio vykdymo netraukite į ankstesnės modelio užklausos trukmę: modelis gali jau būti atsakęs, nors įrankis dar dirba. Jei agentas kviečia kelis įrankius arba modelį pakartotinai, kiekvienas realus iškvietimas turi savo atkarpą. „plan“ kurkite tik tada, kai planavimas jūsų sistemoje yra atpažįstamas veiksmas; vien modelio sugeneruotas tekstas tokios ribos savaime nenustato.

Parinkite atributus gedimui rasti

Visose šiose atkarpose „gen_ai.operation.name“ nusako veiksmą: „invoke_agent“, „chat“, „execute_tool“ arba „plan“. Agento atkarpoje įrašykite „gen_ai.agent.name“, kai turite stabilų pavadinimą. Įrankio atkarpai svarbūs „gen_ai.tool.name“ ir, jei iškvietimas jį turi, „gen_ai.tool.call.id“. Pastarasis atskiria pakartotinius to paties įrankio iškvietimus neatskleisdamas jų argumentų.

Modelio „chat“ atkarpoje įrašykite „gen_ai.provider.name“ ir žinomą „gen_ai.request.model“. Tiekėjo reikšmė atspindi tai, ką žino instrumentavimo sluoksnis: per tarpinę paslaugą siunčiamoje užklausoje ji gali skirtis nuo galutinio modelio tiekėjo. Tiekėjo atributo nepriskirkite kiekvienai įrankio ar vidinei agento atkarpai vien dėl to, kad šios priklauso tai pačiai trasai.

Jei modelio API pateikia žetonų apskaitą, „gen_ai.usage.input_tokens“ ir „gen_ai.usage.output_tokens“ leidžia matyti įvesties bei išvesties apimtį. Lėtą žingsnį nustatykite pagal atkarpos trukmę, o ne pagal žetonų skaičių: ilga modelio užklausa ir lėtas įrankis yra skirtingi reiškiniai. Atkarpų pavadinimuose naudokite operaciją ir žinomą agento ar įrankio vardą, bet ne dinaminį naudotojo tekstą.

Pažymėkite nesėkmę ten, kur ji įvyko

Kai įrankio vykdymas baigiasi klaida, jo „execute_tool“ atkarpai nustatykite klaidos būseną ir mažo kintamumo „error.type“, pavyzdžiui, apibrėžtą klaidos kodą. Jei agentas vėliau sėkmingai pasirenka kitą kelią, įrankio nesėkmė vis tiek lieka matoma savo atkarpoje, o visas „invoke_agent“ paleidimas gali baigtis sėkmingai. Tai leidžia atskirti atsigavusį paleidimą nuo paleidimo be nesėkmingo įrankio iškvietimo.

Išimties fiksavimas nepadeda, kai įrankis grąžina įprastą objektą, kurio būsena jūsų programoje reiškia nesėkmę. „hashspan“ praktinis agento pėdsakas rodo tokį atvejį: operacija grąžino objektą, todėl „execute_tool“ liko be klaidos žymos, nors jame nurodyta operacija neįvyko. Įrankio adapteryje apibrėžkite, kurie grąžinti kodai ar būsenos reiškia nesėkmę, ir tuomet pažymėkite atitinkamą atkarpą.

Jeigu įrankis kreipiasi į kitą paslaugą, jos iškvietimo atkarpą susiekite su „execute_tool“. Taip bus matyti, ar nesėkmė kilo pačiame įrankyje, ar už jo esančioje operacijoje. Į „error.type“ nedėkite laisvos formos klaidos pranešimo: jame gali būti naudotojo duomenų, o skirtingi pranešimai apsunkintų vienodų klaidų grupavimą.

Jautrų turinį įjunkite atskirai

„OpenTelemetry“ turinio rinkimo taisyklės rekomenduoja pagal nutylėjimą nerinkti modelio instrukcijų, įvesčių ir atsakymų, o jų rinkimui numatyti atskirą įjungimo galimybę. Šią ribą taikykite „gen_ai.system_instructions“, „gen_ai.input.messages“ ir „gen_ai.output.messages“ atributams. Įrankio argumentai bei rezultatai taip pat gali atskleisti jautrią informaciją, todėl „gen_ai.tool.call.arguments“ ir „gen_ai.tool.call.result“ palikite išjungtus, kol jų sąmoningai prireiks.

Programos konfigūracijoje turėkite aiškų turinio rinkimo jungiklį su numatytąja reikšme „išjungta“. Taip pat patikrinkite agento karkaso ir modelio SDK nustatymus: vien programos jungiklio neužtenka, jei kuri nors automatinio instrumentavimo dalis savarankiškai įrašo įvestis ar išvestis. Išjungus turinį, operacijų pavadinimai, įrankio vardas, iškvietimo identifikatorius, trukmė ir klaidos tipas tebėra naudingi gedimui nustatyti.

Kai diagnostikai reikia pranešimo ar įrankio rezultato, rinkimą įjunkite apibrėžtoje aplinkoje ir ribokite prieigą prie surinktų duomenų. Didelį ar jautrų turinį galima saugoti atskirai, o trasoje palikti nuorodą į jį. Toks pasirinkimas išsaugo susietą veiksmų seką ir leidžia turiniui taikyti kitokias prieigos taisykles nei įprastiems trasos atributams.

Patikrinkite trasą su sąlygine klaida

Kontroliuojamame bandyme paleiskite agentą taip, kad vienas įrankis grąžintų jūsų apibrėžtą nesėkmės būseną. Eksportuotoje trasoje turėtų būti vienas „invoke_agent“ paleidimas, susijusios modelio bei įrankio atkarpos ir klaidos žyma ties konkrečiu „execute_tool“. Jei agentas po nesėkmės pasirenka kitą kelią, palyginkite įrankio atkarpos ir viso paleidimo baigtį. Atskira „plan“ atkarpa reikalinga tik tada, kai bandymo eiga iš tiesų turi atpažįstamą planavimo etapą.

Pakartokite bandymą išjungę turinio rinkimą ir peržiūrėkite eksportuotus atributus bei įvykius. Juose neturėtų būti užklausos teksto, modelio atsakymo, įrankio argumentų ar rezultato. Kartu trasa turi parodyti, kuris agentas veikė, kuris modelio iškvietimas vyko prieš įrankį, kiek truko kiekvienas žingsnis ir kokio tipo klaida sustabdė konkretų įrankį.

Taip pat skaitykite:

• n8n DI agento patvirtinimai: rizikingą veiksmą sustabdykite laiku
• „Todoist“ ar „TickTick“: mažesnė kaina atneša daugiau įrankių, ne paprastumą
• DI agento atmintis: sesijos istorija dar nėra ilgalaikė atmintis