Debuggen van AI-agenten: uw dashboard weet wat het kost, maar niet de oorzaak.

Het debuggen van AI-agents begint waar je observability-dashboard eindigt. Wanneer een AI-codeeragent iets kapotmaakt en de run al voorbij is, kan het dashboard je vertellen wat de run heeft gekost (tokens, dollars, latentie), maar het zwijgt over de enige vraag die je echt hebt: waarom heeft de agent dat bestand veranderd? Het artefact dat die vraag beantwoordt, is een opgenomen trace die je kunt openen, lezen en opnieuw afspelen, omdat het je de run teruggeeft in plaats van deze van buitenaf te beschrijven.

Vanaf het moment dat agents echt werk gingen doen, was dit geen zeldzame gebeurtenis meer. Een agent zal een repository doorkammen, meerdere bestanden bewerken, de checks draaien en succes rapporteren — allemaal tussen twee prompts die je maar minuten uit elkaar typte. Als een van die bewerkingen fout is, kom je er later achter: nadat de terminal is gesloten, nadat de scrollback verdwenen is, nadat het proces dat zichzelf had kunnen uitleggen is beëindigd. Wat er daarna gebeurt, hangt volledig af van wat je hebt bewaard. Als het antwoord een kostendashboard is, ga je archeologie doen. Als het antwoord een opname is, ga je lezen.

De fout die je niet kunt reproduceren

Zo zit het in elkaar. Je komt terug bij de repo en een bestand waarvan je nooit iemand hebt gevraagd het aan te raken, is herschreven, of verwijderd, of leeggehaald van de functie waar al het andere van afhangt. Je vraagt de agent wat er is gebeurd; de sessie is gesloten, en zelfs waar een transcript bewaard is gebleven, is het verslag van de agent over zijn eigen uitvoering een reconstructie, geen opname. Dus doe je het meest voor de hand liggende en voer je het opnieuw uit, en je krijgt een andere uitvoering. Andere tool-aanroepen, andere bewerkingen, mogelijk helemaal geen fout, omdat het oorspronkelijke traject afhing van sampling, van de staat van de repo, van timing. De uitvoering die je moet inspecteren bestaat niet meer.

Het is erger dan niet-reproduceerbaar. Het is niet-reproduceerbaar en wordt als succes gemarkeerd. Een run eindigt met 0 wanneer de agent eindigt met 0, zelfs als een controle binnen de run met 1 eindigde: de pipeline kan groen zijn terwijl een verificatiestap binnen de run is mislukt, en de exitcode die je van nature zou vertrouwen, vertelt je niets.

Het maakt niet uit welk model de router voor de run heeft gekozen (GLM 5.3 Flash of wat dan ook): zodra het proces wordt beëindigd, gaat de redenering ermee verloren. Het bewijs bestond alleen terwijl de run live was: de prompts, de tool calls, de outputs, de diffs. Als niets ze heeft vastgelegd, heeft "waarom veranderde het dat bestand" geen antwoord. Het heeft theorieën.

Dit is de faalmodus die een onderscheid maakt tussen AI-coderingsagenten en elk hulpmiddel dat hen voorging: de schade en de uitleg gebeuren op dezelfde plek, en de plek sluit.

Wat meet een dashboard, en waar stapt het overheen?

Het instinct na een slechte run is om het observability-dashboard te openen, en het dashboard zal zijn werk echt goed doen. Zijn taak is verkeer: tokens per dag, kosten per model, latentie, foutpercentages. Voor capaciteitsplanning en facturering is dat precies het juiste instrument, en als je agents in productie draait, zou je het open moeten hebben.

Maar uw vraag is niet geaggregeerd. Hij is enkelvoudig en causaal: waarom heeft deze run dit bestand veranderd? Aggregatie stapt precies over de granulariteit heen die het antwoord bevat. Gemiddeld over runs is de run waar het u om gaat ruis; binnen die run is de toolaanroep waar het u om gaat opnieuw ruis.

Een dashboard beschrijft een run van buitenaf: dat het gebeurde, wat het woog, wat het kostte. Het kan je de run niet overhandigen, en "waarom" is geen eigenschap van de beschrijving. Het is een eigenschap van de reeks.

• Wat kostte de run? — Kosten-dashboard beantwoordt het vs Opgenomen trace beantwoordt het

• Waarom heeft de agent dat bestand gewijzigd? — Kosten-dashboard Geen antwoord vs. Opgenomen trace De bewerking, in volgorde, met de diff

• Welke check is mislukt in een groene run? — Cost dashboard Geen antwoord vs Opgenomen trace De check, met zijn exitcode

• Kan ik de exacte fout opnieuw uitvoeren? — Kostendashboard: nee, versus opgenomen trace: ja, offline en kosteloos.

De laag die dit beantwoordt, ligt eronder: vastgelegde verzoeklogs, opgenomen terwijl de run plaatsvond, met elke verzonden prompt, elke gedane toolaanroep, elk antwoord dat terugkwam, in volgorde. Geen samenvatting van de run. De run zelf.

Een run als tijdlijn lezen

Met een opname wordt debuggen geen archeologie meer, maar lezen. Archeologie is wat je doet zonder opname: git reflog, stash-items, shellgeschiedenis, je eigen herinnering aan wat je eerder die dag hebt gevraagd. Lezen is wat je met een opname doet: open de tijdlijn en scroll.

De tijdlijn toont de run in de volgorde waarin deze plaatsvond: de prompt die het startte, elke toolaanroep, elke bestandswijziging met de bijbehorende diff, elke controle en elke exitcode. Er wordt één keer per beurt een bestandssysteemsnapshot gemaakt in plaats van één keer per toolaanroep, wat voldoende is om de staat van de repo bij elke stap van het gesprek te zien, zonder te verdrinken in de ruis per aanroep. Wat dit debuggen maakt in plaats van browsen is nabijheid: de wijziging en de controle die de fout opmerkte, staan naast elkaar, in volgorde, met niets ertussen om over te speculeren. 'Waarom' is vooral een eigenschap van nabijheid.

Een concreet voorbeeld, af te lezen uit een vastgelegde fix: 14 gebeurtenissen, waaronder de bestandswijziging weergegeven als +1 -3 en een check die faalt met exit 1. De bewerking en daarna de check die daardoor faalde, staan pal naast elkaar in die vastlegging. Dat is het hele verschil tussen het reconstrueren van een run uit fragmenten en het lezen van een run. Het is het meest van belang voor codeeragenten in de terminal, waarvan de werkruimte een terminal is die sluit zodra de klus geklaard is: de tijdlijn is de scrollback die overblijft.

Vastgelegd of afgeleid: wat de trace weet versus wat deze heeft uitgewerkt

Een tijdlijn vertelt je wat er in volgorde is gebeurd. De causale graaf vertelt je wat tot wat heeft geleid, en de kloof tussen die twee is waar vertrouwen moet worden verdiend.

De grafiek verbindt gebeurtenissen: deze bewerking, en daarna deze mislukte controle. Sommige van die verbindingen zijn geregistreerde feiten: de toolaanroep die de diff heeft geproduceerd, staat daar gewoon in de trace. Andere zijn afgeleid: de conclusie van de grafiek dat de controle mislukte vanwege die diff. orca graph labelt elke verbinding als geregistreerd of afgeleid en noemt in beide gevallen de regel die is gebruikt, zodat je altijd weet of je naar iets kijkt dat de run heeft gedaan of naar iets dat de tool over de run heeft afgeleid.

Dat onderscheid is geen streefbeeld, maar een afgedwongen werkelijkheid: afgeleide verbanden worden nooit teruggeschreven in de trace. De trace blijft een getrouw verslag van wat er is gebeurd; inferentie is een interpretatie bovenop de trace, die u kunt bekijken, bevragen en betwisten. Dit is vooral belangrijk wanneer er meer dan één agent bij betrokken is. Wanneer een refactoragent en een testschrijvende agent dezelfde bestanden bewerken, is "welke agent dit heeft veroorzaakt" precies de vraag die multi-agentattributie moet beantwoorden. Een verband dat zich stilletjes van inferentie tot feit opwerkt, zorgt ervoor dat u uiteindelijk een verhaal aan het debuggen bent in plaats van een run.

Het zo vaak als je wilt reproduceren, voor niets

Lezen verklaart. Replay bewijst. Zodra je een hypothese hebt (de controle mislukte omdat de wijziging de reset-aanroep verwijderde), wil je het opnieuw uitvoeren en het zien gebeuren. Het opnieuw uitvoeren van de live-agent levert je een nieuw traject en een nieuwe rekening op.

De opname opnieuw afspelen levert dezelfde run op: replay-runs draaien met geblokkeerd netwerk, dus kost het geen tokens en is er geen variatie. Dezelfde gebeurtenissen, elke keer, offline. Dat is de eigenschap die agent-debugging verandert van gokken naar engineering: de fout is deterministisch geworden, en deterministische fouten worden opgelost.

De tooling is ook geen black box.OrcaReplay is open source onder Apache-2.0 en het traceformaat is CC BY 4.0, dus iedereen kan het opnieuw implementeren: jouw opnames zitten niet vast aan een propriëtair formaat, de onze ook niet. En het wordt getest, niet gedemonstreerd: 1393 tests op Node 20 en Node 22. Je kunt de broncode lezen, het formaat controleren en de suite zelf draaien voordat je je team-runs eraan toevertrouwt.

De kern

Een dashboard is een factuur. Een vastgelegde trace is de run. Als je plan voor het debuggen van AI-agenten eindigt bij een kostendashboard, heb je geen debugplan: je hebt een facturatiesysteem. Het dashboard kan je altijd vertellen wat een run heeft gekost, maar het zal je nooit kunnen vertellen waarom de agent je bestand heeft verwijderd, want 'waarom' leeft in de sequentie, en de sequentie bestaat alleen als je hem hebt bewaard.

De hele methode bestaat uit vier stappen:

• Leg de runs vast.

• Lees de tijdlijn.

• Controleer de kanten van de grafiek.

• Speel degenen die je bang maken gratis opnieuw af, zo vaak je wilt.

Bronvermelding: elk cijfer in dit artikel is door de leverancier gerapporteerd, uit ons eigen product en uit de OrcaReplay-repository en de documentatie daarvan: het exit-codegedrag van een run, de opgenomen fix van 14 events met de +1 -3-diff en de exit-1-check, de edge-labeling in de orca graph, de snapshot-cadans van één keer per beurt, offline-replay met geblokkeerd netwerk, en de 1393-testsuite op Node 20 en Node 22. Er worden in dit artikel geen metingen van derden aangehaald. De 1393-testsuite is de enige bewering die u zelf kunt verifiëren door de repository te klonen en de tests uit te voeren. Alle items zijn voor het laatst gecontroleerd op 2026-09-04.