Gestructureerde foutcontext

De eerste taak van een foutcontext is het classificeren van de fout. Gestructureerde MCP-fouten bevatten een veld errorCategory met een kleine, vaste woordenschat:

• transient — een tijdelijke fout in de infrastructuur (time-out, snelheidslimiet). Vaak opnieuw uitvoerbaar.
• validation — de invoer had een ongeldige indeling.
• business — een domeinregel blokkeerde de actie.
• permission — de toegang werd geweigerd.

De bijbehorende booleaanse waarde isRetryable neemt het giswerk weg: de coördinator leest deze rechtstreeks uit in plaats van de bedoeling af te leiden uit een vrijetekstbericht.

Een onderscheid brengt architecten voortdurend in verwarring: een toegangsprobleem is niet hetzelfde als een geldig leeg resultaat.

• Fout: de opzoekactie kon niet worden uitgevoerd — de database is onbereikbaar of de toegang is geweigerd. Opnieuw proberen kan zinvol zijn.
• Leeg: de opzoekactie is succesvol uitgevoerd en leverde nul overeenkomsten op. Opnieuw proberen verandert niets — het antwoord is echt „geen resultaten”.

Als je deze twee door elkaar haalt, ontstaan zinloze herhaallussen voor lege resultaten, of wordt een echte storing behandeld als „geen gegevens gevonden”. Modelleer ze altijd als afzonderlijke toestanden.

De coördinator heeft de mislukte bewerking niet zelf uitgevoerd en kan dus niet zien wat er is geprobeerd. Neem attempted_query letterlijk op in de foutcontext.

Dit heeft twee doelen:

• De coördinator kan beslissen of die dezelfde zoekopdracht opnieuw uitvoert of deze herformuleert (bijvoorbeeld door een te smal filter te verruimen).
• Bij escalatie krijgt de menselijke beoordelaar het exacte geval om te reproduceren, in plaats van een vaag bericht als „zoeken mislukt”.

Een fout betekent zelden dat er geen werk is verricht. Een onderzoeks-subagent kan 6 van de 10 bronnen hebben verzameld voordat een aanbieder de toegang wegens een snelheidslimiet blokkeerde. Dat allemaal weggooien — of de hele workflow afbreken — verspilt echte voortgang.

Voeg alles wat succesvol is verzameld toe als partial_results. De coördinator kan dan de beschikbare gegevens samenvoegen, het ontbrekende deel markeren en beslissen of het resterende werk een nieuwe poging waard is.

Onderdruk de fout nooit stilzwijgend en presenteer gedeeltelijke resultaten niet alsof ze volledig zijn.

De nuttigste foutcontexten beschrijven niet alleen de blokkade, maar wijzen ook een uitweg aan. Het veld alternatives stelt concrete volgende acties voor die de coördinator of een mens kan uitvoeren.

Voorbeelden: „probeer het opnieuw via de leesreplica”, „verruim het datumfilter”, „vraag de gebruiker om een ordernummer”, „escaleer naar een mens en voeg de gedeeltelijke resultaten toe”.

Hierdoor wordt een gestructureerde fout een routeringsinstructie in plaats van alleen een rapport.

Gestructureerde context leidt tot een duidelijk beleid. Handel transient-fouten binnen de subagent af — probeer de time-out opnieuw en wacht langer na het bereiken van een snelheidslimiet — zodat de coördinator een herstelbare hapering nooit te zien krijgt.

Pas wanneer een fout echt niet-herstelbaar is (beleidslimiet bereikt, toegang geweigerd, alle nieuwe pogingen uitgeput), escaleer je deze naar boven — en wel met de gedeeltelijke resultaten en alternatieven erbij, niet als een kale melding „mislukt”.

Het doel: breek niet de hele workflow af omdat één vertakking is mislukt.

Vrije foutwoordenboeken wijken na verloop van tijd af. Leg het contract vast met een JSON Schema via een tool of gestructureerde uitvoer, zodat de subagent de juiste velden moet invullen.

Een belangrijke regel bij het ontwerpen van gestructureerde uitvoer: markeer een veld alleen als verplicht als het altijd aanwezig is. errorCategory en message zijn altijd aanwezig — maak ze verplicht. partial_results en alternatives kunnen ontbreken — laat ze optioneel, anders gaat het model ze verzinnen om aan het schema te voldoen.

Subagents erven de gespreksgeschiedenis van de coördinator niet. Wanneer een subagent dus mislukt, weet de coördinator alleen wat het foutpayload expliciet bevat.

Daarom moeten attempted_query en partial_results in de gestructureerde fout staan — er is geen gedeeld geheugen waarop de coördinator kan terugvallen. De foutcontext is de volledige brug tussen beide.

Beperk deze tot de relevante velden, maar verwijder nooit de vier pijlers.

Dankzij een foutcontext van productiekwaliteit kan de coördinator handelen zonder zelf iets opnieuw uit te voeren:

• fouttype + isRetryable → beslissing: opnieuw proberen of escaleren
• uitgevoerde zoekopdracht → reproduceren of herformuleren
• gedeeltelijke resultaten → voortgang benutten en het ontbrekende deel markeren
• alternatieven → de concrete volgende actie

Dit is het verschil tussen een kwetsbare pijplijn die bij de eerste hapering stopt en een veerkrachtig systeem dat netjes terugvalt en om de schade heen routeert.

Belangrijkste punten:

• Generieke fouten blokkeren herstel; gestructureerde fouten maken intelligente routering mogelijk.
• Neem altijd de vier pijlers op: fouttype, uitgevoerde zoekopdracht, gedeeltelijke resultaten, alternatieven.
• Gebruik errorCategory (transient / validation / business / permission) + isRetryable om de beslissing over opnieuw proberen of escaleren aan te sturen.
• Maak onderscheid tussen een toegangsprobleem (opnieuw proberen kan zinvol zijn) en een geldig leeg resultaat (geen overeenkomsten — opnieuw proberen helpt niet).
• Herstel transient-fouten lokaal in de subagent; escaleer niet-herstelbare fouten met de gedeeltelijke resultaten erbij.
• Onderdruk fouten nooit stilzwijgend en breek de hele workflow niet af vanwege één fout.
• Dwing de structuur af met een schema, maar maak alleen velden verplicht die altijd aanwezig zijn — optionele pijlers moeten optioneel blijven om verzinsels te voorkomen.