Retrybare metadata en gedeeltelijke resultaten

errorCategory classificeert waarom de aanroep is mislukt, zodat het model intelligent kan routeren. De vier standaardcategorieën zijn:

• transient — een tijdelijke fout (timeout, snelheidslimiet). Opnieuw proberen is waarschijnlijk zinvol.
• validation — de invoer had een onjuiste indeling. Corrigeer het verzoek en probeer niet blind opnieuw.
• business — een domeinregel blokkeerde de actie (bijvoorbeeld: de bestelling is al verzonden).
• permission — de aanroeper is niet gemachtigd. Opnieuw proberen helpt niet; escaleer of meld je opnieuw aan.

De categorie bepaalt de strategie; op zichzelf neemt die niet de beslissing.

isRetryable geeft expliciet ja of nee aan op de vraag of opnieuw proberen mogelijk kan slagen. Het werkt samen met de categorie, maar geeft een scherper signaal.

Een transient-timeout heeft meestal isRetryable: true. Een validation-fout heeft isRetryable: false — dezelfde onjuiste invoer opnieuw proberen leidt gewoon weer tot een fout. Belangrijk is dat de subagent hierdoor transient-fouten lokaal kan herstellen, in plaats van elke hapering door te geven aan de coördinator.

Een subtiel maar voor het examen belangrijk onderscheid: een toegangsFOUT is niet hetzelfde als een geldig LEEG resultaat.

• isError: true + transient → de query kon niet worden uitgevoerd. Overweeg opnieuw proberen.
• isError: false + lege lijst → de query is goed uitgevoerd en er zijn echt geen overeenkomsten. Opnieuw proberen is zinloos en verspilt middelen.

Algemene fouten vervagen deze grens. Gestructureerde metadata houdt "ik kon niet zoeken" duidelijk gescheiden van "ik heb gezocht, maar er is niets".

attempted_query legt precies vast wat het hulpmiddel probeerde te doen — de SQL, de API-aanroep of de zoektekst. Dit dient twee doelen:

• Het stelt het model in staat om opnieuw te proberen met feedback: stuur de oorspronkelijke bedoeling samen met de fout, zodat een gecorrigeerde query kan worden opgesteld.
• Het levert herkomstinformatie — je houdt een spoor bij van bewering naar bron, met wat er daadwerkelijk is gevraagd.

Onthoud: opnieuw proberen met feedback corrigeert opmaak- en structurele fouten. Als de informatie simpelweg niet in de bron staat, helpt geen enkele nieuwe query.

Wanneer een bewerking met meerdere stappen of bronnen halverwege mislukt, is het werk dat vóór de fout is uitgevoerd nog steeds waardevol. partial_results geeft het door.

Stel je een onderzoeksagent voor die vijf bronnen heeft bevraagd en waarbij de vijfde een timeout kreeg. Door de vier geslaagde resultaten samen met de fout terug te geven, kan de coördinator doorgaan — in plaats van alles weg te gooien omdat één onderdeel is mislukt. Breek de volledige workflow nooit af vanwege één fout.

De metadata maakt een heldere strategie met twee niveaus mogelijk in hub-en-spaaksystemen:

• Herstel transient-fouten lokaal binnen de subagent — probeer de isRetryable-gevallen stilletjes opnieuw.
• Escaleer niet-herstelbare fouten naar de coördinator en geef de volledige gestructureerde context mee: fouttype, uitgeprobeerde query en eventuele gedeeltelijke resultaten.

De coördinator handelt fouten af en routeert. Maar dat kan alleen goed als de subagent een gestructureerd signaal doorgeeft in plaats van een kale uitzondering of stilte.

Als je de fout definieert als gestructureerde uitvoer, pas de regels voor het schema dan zorgvuldig toe. Markeer een veld alleen als verplicht als het altijd aanwezig is. partial_results is bij een harde fout vaak leeg of afwezig — maak het dus niet verplicht, anders kan het model vermeldingen verzinnen om aan het schema te voldoen.

Gebruik voor errorCategory een enum met een waarde "other" en daarnaast een veld met vrije tekst voor details. Zo blijft de classificatie vandaag overzichtelijk en kun je later foutmodi toevoegen die je nog niet bent tegengekomen.

Metadata stuurt het model probabilistisch (ongeveer 90%). Wanneer een fout financiële, juridische of veiligheidsgevolgen heeft, is dat niet voldoende.

Gebruik een PostToolUse-hook om het resultaat van het hulpmiddel te onderscheppen voordat het model het ziet, en dwing beleid deterministisch af (100%). Bijvoorbeeld: als errorCategory bij een terugbetalingshulpmiddel permission is, blokkeer dan elke nieuwe poging en forceer escalatie — laat het niet aan de prompt over om zich correct te gedragen.

Het ergste wat je met een fout kunt doen, is die verbergen. Vermijd deze twee foutmodi:

• Stil onderdrukken — de fout inslikken en een leeg of verzonnen resultaat teruggeven. Het model kan dan een echt "geen overeenkomsten" niet onderscheiden van een defecte query.
• De volledige workflow afbreken vanwege één mislukt onderdeel — en alle gedeeltelijke resultaten weggooien.

Gestructureerde fouten zijn de oplossing voor beide: ze maken de fout zichtbaar en behouden wat wel is gelukt.

Gestructureerde fouten veranderen fouten in beslissingen die kunnen worden gerouteerd:

• isError — de poort die de herstellogica activeert.
• errorCategory — transient / validation / business / permission (plus "other") bepaalt de strategie.
• isRetryable — de expliciete tip voor opnieuw proberen; herstel transient-fouten lokaal.
• attempted_query — maakt opnieuw proberen met feedback en herkomstinformatie mogelijk (helpt niet als de informatie echt ontbreekt).
• partial_results — geef goede gegevens door; breek de volledige workflow nooit af vanwege één fout.

Markeer alleen velden die altijd aanwezig zijn als verplicht, bescherm fouten met financiële, juridische of veiligheidsgevolgen met deterministische hooks en onderdruk fouten nooit stilletjes. Dat is foutafhandeling op architectniveau.