Spåra AI-agentens verktyg – loggen kan annars dölja felet

Spåra en AI-agents verktygsanrop i en hierarki som skiljer agentkörning, tur, modellkörning och faktiskt utfört verktygsanrop åt. Registrera relationer, tider, status och begränsade felklasser på rätt nivå. Då går det att lokalisera ett fel eller en fördröjning utan att rutinmässigt spara råa promptar och verktygsresultat.

En loggrad som bara säger att agenten misslyckades kan dölja var felet uppstod. Modellen kan ha föreslagit ett anrop som aldrig utfördes, verktyget kan ha fått timeout eller agenten kan ha fortsatt efter ett giltigt verktygssvar. Spåret behöver visa skillnaden mellan dessa steg, medan innehållet i dem hanteras enligt en separat policy.

Bygg hierarkin från körning till verktyg

OpenTelemetrys konventioner för agentspår beskriver operationerna invoke_agent, plan och execute_tool. Konventionerna har utvecklingsstatus. Samla därför mappningen till deras namn och attribut i instrumenteringen, så att den kan ändras utan att felsökningsmodellen byggs om.

1. Starta ett rotspår när en begäran sätter igång arbetsflödet. Använd ett opersonligt arbetsflödesnamn och ett spår-id som binder ihop stegen.
2. Lägg ett invoke_agent-spann för agentens körning under rotspåret. Om arbetet lämnas över till en annan agent ska även nästa körning gå att följa i samma sammanhang.
3. Skapa ett applikationsspann för varje tur i agentens arbetsloop. Lägg modellkörningen under den tur där den sker, med den modelloperation som faktiskt används, till exempel chat eller generate_content.
4. Skapa ett execute_tool-spann när applikationen verkligen kör verktyget. Använd plan för en tydligt avgränsad planeringsfas; en modellkörning som skapar planen hör under planspannet, medan efterföljande verktygsarbete normalt ligger som ett separat steg under agenten.

Varje spann behöver start- och sluttid, status och en relation till sitt föräldraspann. Lägg agentnamn, modellnamn och verktygsnamn på de steg där de hör hemma. En tur är här en användbar del av applikationens spårschema, inte en egen agentoperation som OpenTelemetry kräver. Använd heller inte prompttext, sökfrågor eller personidentifierare som spannamn: namn och etiketter kan spridas till många delar av telemetrisystemet.

Koppla förslaget till det utförda anropet

Modellens förslag och verktygets exekvering är olika händelser. Om ett anrops-id finns kan det koppla ett föreslaget verktygsanrop till motsvarande verktygsspann utan att argumenten kopieras dit. Saknas ett verktygsspann kan anropet ha stoppats före exekvering; det ska inte presenteras som ett verktyg som fått timeout.

Registrera varaktighet och status för varje faktiskt anrop. Ett långt modellspann visar var väntan inträffade i modellsteget, medan ett långt verktygsspann placerar väntan i eller kring verktygsexekveringen. Om applikationen gör om ett anrop bör varje försök få ett eget spann med en säker koppling till samma arbetsuppgift. Tidslinjen visar var arbetet tog tid, men den förklarar inte på egen hand varför modellen valde ett visst verktyg.

I ett villkorat exempel föreslår en kundtjänstagent en ordersökning. Verktyget får timeout, varefter agenten ändå ger ett svar. Med separata spann syns både timeouten och att svaret kom senare; en enda rad om agentens slutstatus skulle kunna dölja den ordningen. Bedömningen av om svaret är sakligt korrekt kan kräva annan, kontrollerat tillgänglig information än den som bör finnas i det vanliga driftspåret.

Så motsvaras stegen i OpenAI Agents SDK

OpenAI Agents SDK:s tracingdokumentation anger standardhierarkin TaskSpan → AgentSpan → TurnSpan. Modellkörningar får GenerationSpan och anrop till funktionsverktyg får FunctionSpan under turen. SDK:n har även separata spann för överlämningar och skyddsregler. Det ger en konkret motsvarighet till arbetsflöde, agent, tur, modellarbete och utfört funktionsanrop.

SDK:ns spanntyper och OpenTelemetrys operationsnamn fyller olika roller i samma felsökningsmodell. När spåren förs till ett gemensamt system kan den utförda funktionskörningen mappas till en verktygsoperation, medan en överlämning eller ett beslut från en skyddsregel behålls som ett eget steg. Annars riskerar en avvisad åtgärd att se ut som ett misslyckat verktyg och gränsen där felet uppstod försvinner.

I SDK:n kan RunConfig.traceIncludeSensitiveData användas för att stänga av insamling av in- och utdata i spann för modellgenereringar och funktionsanrop. Den inställningen gäller inte automatiskt egna spann, applikationsloggar eller andra exporterade händelser. Granska därför hela vägen från instrumentering till export, även när SDK:ns innehållsinsamling är avstängd.

Maskera innehållet före export

Börja med en tillåtelselista för fält som behövs i normal drift: operation, säkert verktygsnamn, tider, status, begränsad felklass och möjligen om ett resultat var tomt. Behandla promptar, modellsvar, verktygsargument och verktygsresultat som innehåll som kan bära personuppgifter, affärsinformation eller hemligheter. Även felsträngar, URL:er och fria etiketter kan innehålla sådana uppgifter.

För strukturerade verktygsargument kan fältnamn bevaras medan värden som e-postadress, personnummer, fritext och åtkomsttoken ersätts med fasta markörer. För ostrukturerad text är det ofta säkrare att utelämna hela fältet än att förlita sig på enstaka sök-och-ersätt-regler. Gör maskeringen innan spannen lämnar applikationen; en exporterad råtext kan redan ha kopierats till flera lagringsplatser när en senare rensning körs.

En felklass som timeout är mer användbar för gruppering än ett fritt felmeddelande som kan återge indata. Om en särskild incident kräver mer innehåll bör omfattning, behörighet och lagringstid beslutas separat för just den insamlingen. Det håller normalspåret användbart för latens och fel utan att göra varje körning till ett arkiv över användarens samtal.

Svensk kontrollista för lagring och åtkomst

IMY:s vägledning om säkerhetsloggning framhåller att loggning ofta innebär behandling av personuppgifter. Den tar upp balansen mellan detaljrikedom, uppgiftsminimering och lagringstid samt behovet av skydd mot obehörig åtkomst och förändring. För agentspår behöver de avvägningarna omsättas i konkreta beslut:

• Beskriv vilka fel, avbrott och prestandaproblem spåren ska kunna utreda. Koppla varje insamlat fält till det ändamålet.
• Bestäm lagringstid och gallring för spårdata. Bedöm separat om ett tillfälligt, mer detaljerat incidentspår behöver kortare tid.
• Ge åtkomst efter arbetsuppgift och begränsa särskilt vem som får se eventuellt råinnehåll. Skydda spåren även mot obehörig ändring.
• Kontrollera vart exportören skickar data och om samma innehåll hamnar i applikationsloggar, felrapporter eller andra system.

Avsluta införandet med en kontrollerad provkörning med påhittade känsliga värden och ett framkallat verktygsfel. Det exporterade spåret ska visa vilken tur och vilket verktyg som fallerade, hur länge stegen tog och hur agenten fortsatte. De påhittade värdena ska samtidigt saknas i spann, feltexter och sidologgar.

Läs också:

• Prompt injection stoppas inte av ett filter – lås agentens verktyg
• MCP och A2A löser olika problem – en agent kan behöva båda
• Rensa dolda data före delning – Word och PDF kräver olika verktyg