Felsökning av AI-agenter: Din instrumentpanel känner till kostnaden men inte orsaken.

Felsökning av AI-agenter börjar där din instrumentpanel för observerbarhet slutar. När en AI-kodningsagent bryter något och körningen redan är över, kan instrumentpanelen visa vad körningen kostade (tokens, dollar, latens), men den tiger om den enda frågan du faktiskt har: varför ändrade agenten den filen? Artefakten som svarar på frågan är en inspelad trace som du kan öppna, läsa och spela upp, eftersom den ger dig körningen tillbaka istället för att beskriva den utifrån.

Detta har slutat vara en sällsynt händelse i samma stund som agenter började utföra riktigt arbete. En agent sveper igenom ett repository, redigerar flera filer, kör kontrollerna och rapporterar framgång – allt mellan två kommandon du skrev med minuters mellanrum. Om en av dessa redigeringar är fel, får du reda på det senare: efter att terminalen har stängts, efter att scrollbacken är borta, efter att processen som kunde ha förklarat sig har avslutats. Vad som händer härnäst beror helt på vad du har sparat. Om svaret är en kostnadsdashboard, är du på väg att ägna dig åt arkeologi. Om svaret är en inspelning, är du på väg att ägna dig åt läsning.

Felet du inte kan återskapa

Så här ser det ut. Du kommer tillbaka till repot och en fil som du aldrig bett någon röra har skrivits om, eller raderats, eller tömts på den funktion som allt annat är beroende av. Du frågar agenten vad som hände; sessionen är stängd, och även när ett transkript finns kvar är agentens redogörelse för sin egen körning en rekonstruktion, inte en inspelning. Så du gör det naturliga och kör den igen, och du får en annan körning. Olika verktygsanrop, olika redigeringar, möjligen inget fel alls, eftersom den ursprungliga banan berodde på sampling, på repots tillstånd, på tajming. Körningen du behöver inspektera finns inte längre.

Det är värre än icke-reproducerbart. Det är icke-reproducerbart och markeras som lyckat. En körning avslutas med 0 när agenten avslutas med 0, även om en kontroll inuti körningen avslutades med 1: pipelinen kan vara grön medan ett verifieringssteg inuti körningen misslyckades, och den exitkod du naturligt skulle lita på säger dig ingenting.

Det spelar ingen roll vilken modell routern valde för körningen (GLM 5.3 Flash eller något annat): när processen väl avslutas är resonemanget borta med den. Bevisen fanns bara medan körningen var aktiv: promptarna, verktygsanropen, utdata, diffarna. Om inget registrerade dem finns det inget svar på "varför ändrade den den filen". Det finns bara teorier.

Detta är det felsätt som skiljer AI-kodningsagenter från alla verktyg som kom före dem: skadan och förklaringen äger rum på samma plats, och platsen stängs.

Vad mäter en dashboard, och vad hoppar den över?

Efter en dålig körning är instinkten att öppna observability-dashboarden, och dashboarden är verkligen bra på sitt jobb. Dess jobb är trafik: tokens per dag, kostnad per modell, latens och felfrekvenser. För kapacitetsplanering och fakturering är det exakt rätt instrument, och om du kör agenter i produktion bör du ha den öppen.

Men din fråga handlar inte om aggregering. Den handlar om ett enskilt fall och en orsak: varför ändrade den här körningen den här filen? Aggregering hoppar över just den granularitet som kan besvara den. Tar man ett medelvärde över körningar blir den körning du bryr dig om brus; inuti den körningen blir det verktygsanrop du bryr dig om återigen brus.

En dashboard beskriver en körning utifrån: att den ägde rum, vad den vägde, vad den kostade. Den kan inte överlämna körningen till dig, och "varför" är inte en egenskap hos beskrivningen. Det är en egenskap hos sekvensen.

• Vad kostade körningen? — Kostnadsdashboard besvarar det vs inspelad spårning besvarar det

• Varför ändrade agenten den filen? — Kostnadsinstrumentpanel Inget svar vs Inspelat spår Ändringen, i ordning, med sin diff

• Vilken check misslyckades i en grön build? — Cost dashboard No answer vs Recorded trace Checken, med dess utgångskod.

• Kan jag köra om exakt samma fel? — Kostnadsinstrumentpanel: Nej, Inspelad spårning: Ja, offline, utan kostnad.

Lagret som besvarar den ligger under: inspelade förfrågningsloggar, registrerade när körningen genomfördes, med varje uppmaning som skickades, varje verktygsanrop som utfärdades och varje svar som kom tillbaka, i ordning. Inte en sammanfattning av körningen. Själva körningen.

Läsa en körning som en tidslinje

Med en inspelning upphör felsökning att vara arkeologi och blir läsning. Arkeologi är vad du gör utan en: git reflog, stash-poster, skalhistorik, din egen minnesbild av vad du bad om tidigare den dagen. Läsning är vad du gör med en: öppna tidslinjen och rulla.

Tidslinjen lägger upp körningen i den ordning den hände: prompten som startade den, varje verktygsanrop, varje filändring med dess diff, varje kontroll, varje exitkod. En ögonblicksbild av filsystemet tas en gång per tur snarare än en gång per verktygsanrop, vilket räcker för att se repots tillstånd vid varje steg i konversationen utan att dränkas i brus från varje enskilt anrop. Det som gör detta till felsökning snarare än bläddrande är närheten: ändringen och kontrollen som fångade den sitter bredvid varandra, i ordning, med ingenting däremellan att spekulera om. ”Varför” är mestadels en egenskap av närhet.

Ett konkret exempel, avläst från en inspelad fix: 14 händelser, inklusive filändringen utskriven som +1 -3 och en misslyckad kontroll med utgångskod 1. Redigeringen och därefter kontrollen som misslyckades på grund av den ligger intill varandra i inspelningen. Det är hela skillnaden mellan att rekonstruera en körning från fragment och att läsa en sådan. Det spelar störst roll för terminalbaserade kodningsagenter, vars arbetsyta är en terminal som stängs i samma ögonblick som uppgiften är klar: tidslinjen är rullningsbufferten som överlever.

Registrerat eller härlett: vad tracen vet kontra vad den räknat ut

En tidslinje berättar vad som hände i ordning. Den kausala grafen berättar vad som ledde till vad, och gapet mellan dessa två är där förtroende måste förtjänas.

Grafen kopplar samman händelser: den här redigeringen, sedan den här misslyckade kontrollen. Vissa av dessa kanter är registrerade fakta: verktygsanropet som producerade diffen finns precis där i spårningen. Andra är härledda: grafens slutsats att kontrollen misslyckades på grund av den diffen. orca graph märker varje kant som registrerad eller härledd och namnger regeln den använde i båda fallen, så att du alltid vet om du tittar på något som körningen gjorde eller något som verktyget räknade ut om körningen.

Den distinktionen upprätthålls, inte bara eftersträvas: infererade kanter skrivs aldrig tillbaka till spåret. Spåret förblir en trogen registrering av vad som hände; inferens är en vy ovanpå spåret, som du kan inspektera, ifrågasätta och bestrida. Detta har störst betydelse när mer än en agent är inblandad. När en refaktoragent och en testskrivande agent rör vid samma filer är "vilken agent orsakade detta" precis den fråga som multi-agent-attribuering finns till för att besvara. En kant som i tysthet befordrar sig själv från inferens till faktum är hur man hamnar i att felsöka en berättelse i stället för en körning.

Att reproducera det så ofta du vill helt gratis.

Läsning förklarar. Uppspelning bevisar. När du väl har en hypotes (kontrollen misslyckades eftersom redigeringen tog bort återställningsanropet), vill du köra om kontrollen och se det hända. Att köra om liveagenten ger dig en ny trajektoria och en ny räkning.

Att spela upp inspelningen ger dig samma körning: uppspelningen körs med nätverket blockerat, så det kostar inga token och har ingen variation. Samma händelser, varje gång, offline. Det är den egenskapen som förvandlar agentfelsökning från hasardspel till ingenjörskonst: felet har blivit deterministiskt, och deterministiska fel åtgärdas.

Verktyget är inte heller en svart låda. OrcaReplay är öppen källkod under Apache-2.0 och spårformatet är CC BY 4.0, så vem som helst kan återimplementera det: dina inspelningar är inte utlämnade åt ett proprietärt format, inte heller våra. Och det är beprövat, inte demonstrerat: 1393 tester på Node 20 och Node 22. Du kan själv läsa källkoden, granska formatet och köra testsviten innan du anförtror ditt teams körningar åt något av det.

Slutsatsen

En dashboard är en räkning. En inspelad trace är körningen. Om din plan för att felsöka AI-agenter slutar vid en kostnadsdashboard, har du ingen felsökningsplan: du har ett faktureringssystem. Dashboarden kommer alltid att kunna berätta vad en körning kostade, och den kommer aldrig att kunna berätta varför agenten raderade din fil, eftersom "varför" lever i sekvensen, och sekvensen existerar bara om du behöll den.

Hela metoden består av fyra steg:

• Registrera körningarna.

• Läs tidslinjen.

Kontrollera grafens kanter.

• Spela om de som skrämmer dig, gratis, så ofta du vill.

Källnotering: Varje siffra i den här artikeln är leverantörsrapporterad, från vår egen produkt och från OrcaReplay-repositoriet och dess dokumentation: exit-kod-beteendet vid en körning, den inspelade fixen som omfattar 14 händelser, med dess +1 -3-diff och dess exit-1-kontroll, kantetiketteringen i orca-grafen, snapshot-takten en gång per runda, offline-uppspelning med nätverket blockerat, och 1393-testsviten på Node 20 och Node 22. Inga tredjepartsmätningar citeras någonstans i den här artikeln. 1393-testsviten är det enda påstående du kan verifiera själv, genom att klona repositoriet och köra den. Alla punkter kontrollerades senast 2026-09-04.