AI-agents traceren met OpenTelemetry en toolspans

Maak voor elke uitvoering van een AI-agent een hoofdspan en hang retrieval, modelverzoeken en elke daadwerkelijk uitgevoerde toolaanroep daaronder. De gedeelde trace-ID en ouder-kindrelaties laten zien welke stap tijd kost, waar een fout optreedt en bij welke modelaanroep tokens worden gebruikt. De AWS-handleiding voor AI-observability beschrijft zo’n hiërarchische trace voor agentstappen, modelaanroepen, tools en retrieval.

Instrumenteer de code die een tool uitvoert, niet alleen het modelverzoek dat de tool voorstelt. Houd de standaardtrace beperkt tot operationele gegevens: bewerking, duur, status, fouttype, modelnaam en beschikbare tokenaantallen. Voor het onderzoeken van vertraging en fouten hoeven de vraag van de gebruiker, opgehaalde documenten en toolresultaten niet mee naar de telemetry-backend.

Begin bij de agentuitvoering

Start een hoofdspan zodra de agent een taak aanneemt en sluit die wanneer de uitvoering eindigt met een antwoord of fout. Voor een agent die binnen de eigen applicatie draait, beschrijven de OpenTelemetry-conventies voor agentspans de bewerking invoke_agent, het attribuut gen_ai.agent.name en een interne span; deze conventies hebben nog de status Development. Gebruik een vaste agentnaam als die beschikbaar is en zet de tekst van de gebruikersvraag niet in de spannaam.

De hoofdspan meet de doorlooptijd van de volledige uitvoering. De onderliggende spans verdelen die uitvoering in herkenbare bewerkingen, elk met een eigen begin, einde en status. Daarmee kun je uitvoeringen van dezelfde agent terugvinden zonder een unieke vraag of klantnaam als identificatie te gebruiken.

Houd de vertaling van frameworkgebeurtenissen naar OpenTelemetry-attributen op één plaats in de instrumentatie. Dat maakt het eenvoudiger om een gewijzigde conventie of een ander agentframework te verwerken. Het belangrijkste uitgangspunt blijft gelijk: een span hoort bij een uitgevoerde bewerking en krijgt de juiste bovenliggende span mee.

Maak afzonderlijke spans voor retrieval, model en tool

Neem als voorwaardelijk voorbeeld een uitvoering die eerst context ophaalt, daarna een model aanroept, een tool uitvoert en ten slotte nogmaals het model aanroept. Registreer alleen stappen die werkelijk plaatsvinden: een agent kan rechtstreeks antwoorden, meermaals zoeken of dezelfde tool opnieuw gebruiken. De GenAI-conventies voor model- en retrievalspans geven de bijbehorende bewerkingen en attributen, waaronder de gevraagde documentlimiet en tokengebruik.

Retrieval: plaats een span rond het ophalen van context uit een zoekdienst of databron. Zet gen_ai.operation.name op retrieval en voeg gen_ai.data_source.id toe wanneer een geschikte identificatie beschikbaar is. Met gen_ai.retrieval.top_k leg je de gevraagde bovengrens voor het aantal documenten vast; die waarde zegt niet hoeveel documenten daadwerkelijk zijn gevonden. De duur en eventuele foutstatus maken een trage of mislukte zoekactie zichtbaar.
Modelverzoek: maak een eigen span voor iedere afzonderlijke aanroep. Registreer het aangevraagde model met gen_ai.request.model en voeg gen_ai.usage.input_tokens en gen_ai.usage.output_tokens toe wanneer die aantallen beschikbaar zijn. Houd de waarden bij de modelspan waarop ze betrekking hebben, zodat een extra modelronde na de tooluitvoering herkenbaar blijft.
Tooluitvoering: open een span rond de code die de tool daadwerkelijk start en afrondt. Gebruik execute_tool als bewerking en een stabiele gen_ai.tool.name; markeer een mislukte uitvoering met een foutstatus en een passend error.type. Roept de tool zelf een externe dienst of database aan, dan kan een onderliggende span voor die aanroep laten zien waar de wachttijd ontstaat.

Een model kan een toolaanroep voorstellen zonder dat de applicatie hem uitvoert. De modelspan toont dan het modelverzoek, terwijl pas de span rond de uitvoerende code de werkelijke toolstap vastlegt. Geef herhaalde uitvoeringen elk een eigen span, maar voorkom dat automatische en handmatige instrumentatie dezelfde uitvoering dubbel registreren.

Behoud de tracecontext bij elke overgang

Laat de actieve tracecontext beschikbaar blijven wanneer de agent een onderliggende bewerking start. Gaat een taak naar een andere thread, wachtrij of dienst, draag die context dan mee en maak de nieuwe span onder de juiste ouder aan. Zonder die overdracht kan een gemeten tooluitvoering als losse trace verschijnen.

Voer een uitvoering uit waarin de agent daadwerkelijk een tool gebruikt en bekijk de ontstane spanboom. De toolspan moet dezelfde trace-ID hebben als de hoofdspan en op de juiste plek in de tijdlijn staan. Zie je alleen een modelspan die een toolaanroep voorstelt, voeg dan instrumentatie toe rond de uitvoerende code.

Maak daarbij onderscheid tussen een nieuwe beslissing van de agent en een automatische herhaling binnen één logisch modelverzoek. Een modelclient kan een tijdelijk mislukte aanvraag zelf opnieuw proberen. Een nieuwe agentstap verdient een afzonderlijke span; een automatische retry kan onderdeel blijven van de modelbewerking die de client al uitvoerde.

Laat inhoud weg uit de standaardtrace

Voor onderzoek naar duur, fouten en tokengebruik zijn volledige gebruikersvragen, systeeminstructies, modelantwoorden en opgehaalde documenten doorgaans overbodig. Laat ook retrievalvragen, toolargumenten en toolresultaten standaard weg. Zulke velden kunnen persoonsgegevens, toegangssleutels of interne informatie bevatten, zelfs wanneer de toolnaam zelf onschuldig lijkt.

Beperk de attributen tot wat het operationele onderzoek nodig heeft: een stabiele agent- en toolnaam, een geschikte databronidentificatie, bewerking, duur, status, fouttype en beschikbare tokenaantallen. Beoordeel ook de identificaties zelf. Een documenttitel, vrij ingevulde spannaam of klantgebonden databron-ID kan alsnog inhoud prijsgeven terwijl expliciete berichtvelden uitstaan.

Bekijk de instellingen van automatische instrumentatie vóór export, omdat die andere inhoud kan vastleggen dan handmatig toegevoegde spans. Als berichtinhoud voor een afzonderlijk onderzoek nodig is, vraagt dat om een expliciete keuze over toegang en bewaartermijn. De standaardtrace kan beperkt blijven tot metadata.

Onderzoek de uitkomst per bewerking

Begin bij de onderliggende span met de fout en kijk of de agentuitvoering die fout heeft opgevangen. Vergelijk bij vertraging de tijdlijn van retrieval, model en tool. Een lange toolspan wijst naar een andere bewerking dan een langzame modelspan; een groot verschil tussen de duur van de hoofdspan en de zichtbare onderliggende stappen kan wijzen op agentwerk dat nog geen eigen span heeft.

Tel tokenaantallen van afzonderlijke modelspans op zonder waarden die al op een bovenliggende span zijn samengevat nogmaals mee te nemen. Zo blijft zichtbaar wat een extra modelaanroep na een toolstap aan het totale gebruik toevoegt. De trace maakt de route, tijd en tokenverdeling van de uitvoering inzichtelijk.