Het scherm zei dat de run was geslaagd. Het verslag vertelde iets anders.

Het is donderdagmiddag. Een klant vraagt waarom de bestelling die hij maandag heeft geplaatst nooit is bevestigd. Iemand opent de workflowtool. De run van maandag staat als afgerond geregistreerd. Iemand anders opent de achterliggende database. Daar staat dezelfde run nog op 'running', zonder eindtijd.

Twee onderdelen van hetzelfde systeem vertellen twee verschillende verhalen over wat er die middag is gebeurd. Voordat iemand de bestelling van de klant kan herstellen, moet het team bepalen welk verhaal het kan vertrouwen.

Dit komt vaker voor dan u misschien denkt, en daarvoor hoeft geen enkele tool kapot te zijn. Drie meldingen uit het onderzoek voor deze reeks laten zien hoe dit op drie verschillende manieren kan gebeuren.

Het scherm en de database. Een team dat een workflowtool op een eigen server draait, meldde het volgende. Wanneer de instelling om geslaagde runs niet op te slaan was ingeschakeld, werden runs op het scherm normaal afgerond, terwijl de bijbehorende records in de database op 'running' bleven staan. Ze waren gemarkeerd als niet afgerond en hadden geen eindtijd. Deze records stapelden zich op voor elke workflow, zelfs voor eenvoudige workflows. De melder verwoordde het probleem nauwkeurig: 'Niet opslaan' zou de gegevens van de run moeten overslaan, niet de stap die het runrecord afsluit. Op het moment dat wij de melding bekeken, had de leverancier het probleem nog niet bevestigd en stond het issue nog open.

De aanroeper en de run. Een ander team meldde problemen met een productieworkflow die via een webhook klanten antwoord gaf in een chatapp. Sommige runs bleven eindeloos op 'running' staan, zonder foutmelding of time-out, terwijl de webhook al had gemeld dat alles in orde was. Het opgeslagen verslag was leeg. Zelfs de invoer van de eerste stap ontbrak. Alleen een herstart loste het probleem op. Daarom bouwde het team een waakhond die de container opnieuw startte wanneer een run vastliep.

Weken later ontdekte de melder de oorzaak, die bij het team zelf lag. Een toegangsgegeven dat van een oude server was overgezet, bevatte nog een oud wachtwoord. De client achter een van de stappen bleef daardoor eindeloos opnieuw proberen. De stap liep dus niet vast door een foutmelding, maar bleef proberen zonder ooit iets op te slaan. Omdat het opslaan van de voortgang was uitgeschakeld, wat de standaardinstelling was, liet de opgeslagen run alleen de eerste momentopname zien. Die toonde precies het punt waarop de registratie was gestopt. Zodra het team het opslaan van de voortgang en aanvullende debuguitvoer inschakelde, werd de vastgelopen stap direct zichtbaar.

De foutmelding en de oorzaak. Een ontwikkelaar meldde dat de eigen gehoste agent, aangeroepen vanuit de eigen webapp, plotseling een melding gaf dat er een interne fout was opgetreden. De app toonde vervolgens een serverfout. Alles had eerder gewerkt en er was niets veranderd. De ontwikkelaar kon niet vaststellen of de fout in de eigen code zat of op de server van de leverancier.

Een expert op het forum legde eerst uit dat de foutmelding alleen aangaf waar de fout zichtbaar werd, niet wat de oorzaak was. Ook kwam de serverfout uit de eigen app van de ontwikkelaar. Nadat de ontwikkelaar de runtrace had gedeeld, vond de expert de oorzaak: de modelaanbieder had een limiet ingesteld voor het aantal tokens per minuut. De ontwikkelaar reageerde daarna niet meer om die conclusie te bevestigen.

Drie meldingen, één patroon. Elk onderdeel van het systeem legde op een bepaald moment zijn eigen status vast. De waarheid stond in het verslag per stap, voor zover dat verslag die informatie had bewaard.

Een status is één veld. Dat wordt meestal één of twee keer bijgewerkt: wanneer een run begint en wanneer een onderdeel van het systeem besluit dat de run voorbij is. Een verslag bestaat uit veel afzonderlijke regels die worden vastgelegd terwijl stappen beginnen, invoer ontvangen, uitvoer produceren of fouten veroorzaken.

Verschillende onderdelen van het systeem schrijven deze gegevens op verschillende momenten weg. Daardoor kunnen status en verslag elkaar op verschillende manieren tegenspreken.

• De status kan 'afgerond' aangeven omdat het scherm zag dat de laatste stap eindigde, terwijl de schrijfactie die het verslag afsluit nooit heeft plaatsgevonden.
• De status kan eindeloos op 'running' blijven staan omdat geen enkele stap een fout heeft gemeld, terwijl de run vastzit bij een stap die nooit wordt afgerond.
• De foutmelding kan aangeven waar een fout zichtbaar werd, terwijl de werkelijke oorzaak twee lagen dieper in het systeem zit.
• Een run kan als 'afgerond' eindigen terwijl een van de stappen een fout heeft vastgelegd. Dat kan gebeuren wanneer de flow zo is ingericht dat de fout wordt opgevangen en de uitvoering doorgaat. Dat is niet per se een storing. Het kan een bewuste ontwerpkeuze zijn, maar u moet die wel kunnen herkennen.

Ook de instellingen bepalen hoeveel informatie het verslag bevat. Een verslag dat alleen de eerste momentopname bewaart, of helemaal geen geslaagde runs opslaat, vertelt u minder dan u misschien denkt. Controleer daarom wat uw systeem standaard vastlegt voordat u die informatie nodig hebt.

Eén eenvoudige regel helpt: vertrouw op de registratie die het dichtst bij de betreffende stap is vastgelegd.

De status is een bewering over de run. De regels per stap vormen het bewijs: deze stap is begonnen, heeft deze invoer ontvangen, heeft deze uitvoer geproduceerd of is met deze fout geëindigd. Als de status en het verslag elkaar tegenspreken, weegt het bewijs uit de stapregistratie zwaarder. De tegenspraak zelf is bovendien een bevinding. Leg die vast. Ze laat zien welk onderdeel van uw opzet u niet zonder meer kunt vertrouwen.

Geeft een tool u alleen een status, dan hebt u geen tegenstrijdige gegevens om te onderzoeken. U hebt dan alleen een bewering, zonder het bewijs om die te controleren.

Het verslag wordt vastgelegd door de harness, de laag rond het model die uw agents uitvoert. Of die laag de gebeurtenissen correct registreert, is een aparte vraag. Lees meer in wie auditeert de agent-harness.

EpicStaff-flows bestaan uit afzonderlijke stappen (nodes). EpicStaff noemt een run een sessie. Elke node schrijft eigen records weg: een startrecord met de invoer, een eindrecord met de uitvoer en status, en een foutrecord met de details van een fout. Elk record bevat de naam van de node, een volgnummer en een tijdstempel. Deze records worden afzonderlijk van de sessiestatus opgeslagen. Het live scherm kan tijdelijk achterlopen. Het opgeslagen runverslag is de bron van waarheid.

Een run kan de status 'finished' hebben terwijl een fout van een node is vastgelegd. Een decision-table-node vangt zijn eigen fout op, schrijft het foutrecord weg en gaat verder via het foutpad of naar het einde. De run gaat vervolgens door. De meeste andere nodes geven een fout juist door. U kunt de fout van een node bekijken in de berichtenweergave van de run. U vindt deze ook via het filter 'error cause' (foutoorzaak) in het overzicht van alle sessies. Dit filter toont elke sessie met een foutrecord, ongeacht de status.

De sessie-export in JSON-formaat bevat het verslag per stap, inclusief tool-aanroepen. Elke tool-aanroep van een agent en elk toolresultaat wordt als een afzonderlijk record opgeslagen. Argumenten en resultaten van tools worden elk afgekapt na 2.000 tekens. Ze worden als afgekapt gemarkeerd en nooit samengevat.

Wat een bruikbaar runverslag moet bevatten, leest u in De agent is klaar. Niemand kan zeggen wat hij deed.

Stel uzelf één keer per week drie vragen over de flows die ertoe doen. Deze controles werken op elk platform. De toelichting bij EpicStaff laat zien waar u de informatie in ons platform vindt.

• Welke runs hebben een fout vastgelegd, ongeacht hun status? Filter niet alleen op 'mislukt'. Een afgeronde run met een fout in een van de stappen is juist het soort run waar niemand naar kijkt. In EpicStaff vindt u met het filter 'error cause' in het overzicht van alle sessies elke sessie met een foutrecord, ongeacht de status.
• Welke runs staan nog op 'running', lang nadat ze hadden moeten eindigen? Open het verslag van elke run en zoek de laatste stap die is begonnen. Daar moet u zoeken, niet alleen naar de status van de volledige run. In EpicStaff laat het verslag zien welke stap als laatste is begonnen, ook wanneer een run blijft hangen.
• Komen enkele afgeronde runs overeen met de wijzigingen die ze moesten aanbrengen? Kies drie runs en controleer de bestelling, e-mail of registratie in het doelsysteem. Een status kan u niet vertellen of het werk daadwerkelijk is uitgevoerd. Alleen het doelsysteem kan dat bevestigen. Voor runs die groen eindigen terwijl het werk niet af is, leest u meer in Stille fouten in AI agents: groen vinkje is niet klaar.

Voer daarnaast eenmalig een andere controle uit, en herhaal die niet noodzakelijk elke week: onderzoek welke gegevens uw tool standaard in het verslag opslaat en welke gegevens worden overgeslagen door instellingen als 'niet opslaan' of 'minder opslaan'. Neem die vraag mee in de vragen die u aan elke leverancier stelt voordat u zelf gaat hosten. Doe dit op een rustig moment, niet midden in een incident.

Als het scherm en het verslag elkaar tegenspreken, is dat geen ruis. Het is het eerste spoor.