Fejlkategorier

Midlertidige fejl er kortvarige og skyldes ikke din forespørgsel: et timeout, et kortvarigt netværksudfald eller en upstream-tjeneste, der midlertidigt er overbelastet. Det samme kald vil sandsynligvis lykkes, hvis det udføres igen lidt senere.

Disse fejl svarer til isRetryable: true. Det rigtige er næsten altid at prøve igen lokalt i underagenten – genopret fejlen dér, hvor den opstod, med en kort pause, i stedet for at afbryde hele arbejdsgangen på grund af et kortvarigt problem.

Valideringsfejl betyder, at selve forespørgslen var forkert formateret: et manglende påkrævet felt, en forkert type, en værdi uden for det tilladte interval eller et forkert datoformat. Værktøjet nåede aldrig langt nok til at udføre det egentlige arbejde.

Hvis du blindt prøver den identiske forespørgsel igen, mislykkes den igen – derfor er isRetryable normalt false. Fejlen kan dog stadig håndteres: Claude kan læse meddelelsen, rette inputtet og kalde værktøjet igen. Jo mere detaljeret meddelelsen er (hvilket felt og hvad der blev forventet), desto hurtigere retter modellen sig selv.

Forretningsfejl opstår, når forespørgslen er korrekt formateret, og den kaldende part har tilladelse, men en domæneregel forbyder handlingen. Tænk på: En tilbagebetaling overstiger politikkens grænse, saldoen er for lav, varen er udsolgt, eller reservationen ligger efter tidsfristen.

Dette er ikke en fejl, der kan løses ved at prøve igen – det er en begrænsning i den virkelige verden. isRetryable er false. Agenten bør tydeligt vise reglen, og hvis arbejdsgangen ikke kan fortsætte inden for politikken, skal den eskalere i stedet for at forsøge at gennemtvinge handlingen.

Tilladelsesfejl betyder, at adgang blev nægtet: legitimationsoplysningerne, tokenet eller rollen giver ikke tilladelse til denne handling eller ressource. Forespørgslen kan sagtens være korrekt i både form og hensigt – den er ganske enkelt ikke tilladt.

Hvis du prøver det samme kald igen med de samme legitimationsoplysninger, vil det fortsat mislykkes, så isRetryable er false. Agenten bør ikke gå i løkke; den bør rapportere den manglende adgang og, når det er relevant, eskalere til et menneske eller en privilegeret vej.

Hele formålet med kategorisering er at dirigere. Når koordinatoren har læst errorCategory, er genoprettelsesvejen entydig — den behøver ikke gætte ved at læse prosa.

En enkel mapping:

• transient → prøv igen lokalt med backoff
• validation → ret inputtet, og prøv derefter igen
• business → respekter reglen; eskalér, hvis du er blokeret
• permission → stop; rapportér eller eskalér den manglende adgang

Det er intelligent dirigering, som en generisk status som "failed" ganske enkelt ikke kan understøtte.

Du behøver ikke altid forgrene på alle fire kategorier. Flaget isRetryable er en hurtig kontrol: true betyder "det kan med rimelighed virke at prøve igen", mens false betyder "det samme kald vil fejle på samme måde".

Som tommelfingerregel kan kun transient-fejl forsøges igen, som de er. Ved validering skal inputtet først ændres; forretningsregler og tilladelser ændrer sig slet ikke ved et nyt forsøg. Betragt isRetryable: false som et klart signal om at holde op med at prøve igen og vælge en anden handling — reparér, eskalér eller rapportér.

En subtil, men eksamenskritisk forskel: en adgangsfejl er ikke det samme som et gyldigt tomt resultat.

Hvis et opslagværktøj ikke kan få forbindelse til databasen, er det en midlertidig fejl — måske skal du prøve igen. Hvis værktøjet får forbindelse til databasen uden problemer, og der ganske enkelt ikke er nogen matchende rækker, er kaldet lykkedes og returnerer nul resultater — isError er false. Hvis du blander de to ting sammen, fører det til meningsløse nye forsøg på "ingen match fundet" eller, endnu værre, til at en reel fejl i stilhed behandles som "der er ikke noget".

Når en fejl, der ikke kan genoprettes fra, skal sendes videre, skal du sende struktureret kontekst med — ikke bare "det gik i stykker". Medtag fejltypen, den attempted_query, eventuelle partial_results, der allerede er indsamlet, og brugbare alternativer.

I et forskningssystem med flere agenter er det dette, der gør det muligt for koordinatoren at annotere dækningshuller og stadig samle et nyttigt svar ud fra det, der lykkedes. De to fejltilstande, du skal undgå, er: stille undertrykkelse (at sluge fejlen) og at afbryde hele arbejdsgangen, fordi én af ti underopgaver mislykkedes.

Saml de to dele i ét grundprincip for håndtering af agentfejl:

• Genopret midlertidige fejl lokalt — prøv igen i underagenten med backoff; lad ikke en timeout boble hele vejen op til mennesket.
• Eskalér fejl, der ikke kan genoprettes, sammen med delvise resultater — når forretningsregler, tilladelser eller manglende data blokerer fremdriften, skal du sende den strukturerede kontekst videre, så et menneske eller en koordinator kan træffe beslutningen.

Eskaleringstriggere skal være konkrete (mangler i politikken, overskridelse af tærskler, manglende fremdrift efter flere forsøg, udtrykkelige anmodninger fra mennesker) — aldrig baseret på stemning eller en models egen vurdering af sin sikkerhed.

Strukturerede fejl forvandler en blindgyde til en beslutning. Husk de fire kategorier og deres standardveje:

• transient (isRetryable: true) → prøv igen lokalt med backoff
• validation → ret inputtet, og prøv derefter igen
• business → respekter reglen; eskalér, hvis du er blokeret
• permission → stop; rapportér eller eskalér den manglende adgang

Skeln altid mellem en adgangsfejl og et gyldigt tomt resultat. Når du sender en fejl videre, skal du medtage attempted_query og partial_results — undertryk aldrig en fejl i stilhed, og afbryd aldrig hele arbejdsgangen på grund af én fejl. Generiske fejl blokerer genoprettelse; strukturerede fejl med en kategori og isRetryable muliggør den.