Strukturert feilkontekst
Feiltype, forsøkt spørring, delvise resultater og alternativer.
Strukturert feilkontekst er en gratis leksjon i Claude Architect på CoddyKit. Dette er leksjon 3 av 4. Du kan lese valgfritt 3 leksjoner fra denne læringsstien gratis i sin helhet – deretter låser CoddyKit PRO opp alle leksjoner, samt praktisk øving med en innebygd kodeeditor og en AI-veileder som er tilgjengelig døgnet rundt. Den er en del av læringsløpet i Claude Architect, og fremdriften din synkroniseres mellom nettet og CoddyKit-appen. Kurset i Claude Architect inneholder totalt 4 leksjoner.
Hvorfor feil trenger struktur
I et system med flere agenter vil en underagent før eller siden støte på en feil: en database er nede, en spørring gir ingen resultater eller en tillatelse blir avslått. Hvordan feilen rapporteres, avgjør om koordinatoren kan gjenopprette på en intelligent måte eller bare gir opp.
En generell status som "Operation failed" blokkerer gjenoppretting — koordinatoren har ingen anelse om hva den skal gjøre videre. En strukturert feil-kontekst gjør en blindvei om til en rutingbeslutning.
Denne leksjonen dekker de fire grunnpilarene i en god feil-kontekst: feiltype, forsøkt spørring, delvise resultater og alternativer.
Antimønsteret med generiske feil
Sammenlign to feilpayloader som kommer tilbake fra en underagent eller et verktøy.
Den generiske varianten forteller ingenting som koordinatoren kan handle på. Den kan ikke avgjøre om den skal prøve på nytt, be brukeren om mer informasjon eller eskalere. Stilletiende undertrykking er enda verre — arbeidsflyten fortsetter som om data finnes, selv om de ikke gjør det.
Den strukturerte varianten oppgir hva som feilet, og hvorfor, noe som er første steg mot et intelligent neste trekk.
# Anti-pattern: opaque, un-actionable
return {"isError": True, "message": "Operation failed"}
# Better: structured, routable
return {
"isError": True,
"errorCategory": "transient",
"isRetryable": True,
"message": "Connection to orders DB timed out after 5s",
}Grunnpilar 1 — Feiltype
Den første oppgaven til en feilkontext er å klassifisere feilen. Strukturerte MCP-feil har et errorCategory-felt med et lite, fast vokabular:
- transient — midlertidig infrastrukturfeil (tidsavbrudd, hastighetsbegrensning). Kan ofte håndteres ved å prøve på nytt.
- validation — inndataene hadde feil format.
- business — en domeneregel blokkerte handlingen.
- permission — tilgang ble nektet.
Det tilhørende boolske feltet isRetryable eliminerer gjetting: Koordinatoren leser det direkte i stedet for å tolke hensikten ut fra en fritekstmelding.
{
"isError": true,
"errorCategory": "transient",
"isRetryable": true,
"message": "Rate limit hit on inventory service"
}Feil kontra tomt resultat
Én forskjell skaper stadig problemer for arkitekter: en tilgangsfeil er ikke det samme som et gyldig tomt resultat.
- Feil: Oppslaget kunne ikke kjøres — databasen er utilgjengelig eller tilgangen er nektet. Det kan være verdt å prøve på nytt.
- Tomt: Oppslaget ble kjørt og fant null treff. Et nytt forsøk endrer ingenting — svaret er faktisk «ingen».
Hvis disse to blandes sammen, fører det til meningsløse løkker med nye forsøk på tomme resultater, eller til at et reelt driftsavbrudd behandles som «ingen data funnet». Modellér dem alltid som separate tilstander.
def classify(result):
if result.connection_error:
return {"isError": True, "errorCategory": "transient",
"isRetryable": True}
if not result.rows: # ran fine, found nothing
return {"isError": False, "empty": True, "matches": 0}
return {"isError": False, "matches": len(result.rows)}Grunnpilar 2 — Forespørsel som ble forsøkt
Koordinatoren kjørte ikke den mislykkede operasjonen selv, så den kan ikke se hva som ble forsøkt. Ta med attempted_query ordrett i feilkontexten.
Dette har to formål:
- Det lar koordinatoren avgjøre om den skal prøve på nytt med samme forespørsel eller omformulere den (for eksempel utvide et filter som var for snevert).
- Ved eskalering får den menneskelige gjennomgåeren den nøyaktige saken som kan gjenskapes, i stedet for en vag «søk mislyktes».
return {
"isError": True,
"errorCategory": "transient",
"isRetryable": True,
"attempted_query": {
"endpoint": "GET /orders",
"filters": {"customer_id": "C-4821", "status": "shipped"},
},
"message": "Orders service returned 503",
}Grunnpilar 3 — Delvise resultater
En feil betyr sjelden at ingenting ble gjort. En research-underagent kan ha samlet inn 6 av 10 kilder før en leverandør begrenset hastigheten. Å forkaste alt dette — eller avbryte hele arbeidsflyten — sløser bort reell fremdrift.
Legg ved alt som ble samlet inn, som partial_results. Koordinatoren kan da aggregere det som finnes, annotere mangelen og avgjøre om resten er verdt et nytt forsøk.
Undertrykk aldri en feil i stillhet og presenter delresultater som om de var komplette.
return {
"isError": True,
"errorCategory": "transient",
"isRetryable": True,
"attempted_query": "fetch 10 sources on 'EU AI Act timelines'",
"partial_results": collected_sources, # 6 of 10 gathered
"message": "Provider rate-limited after 6 sources",
}Grunnpilar 4 — Alternativer
De mest nyttige feilkontextene beskriver ikke bare hindringen — de viser også en vei videre. Feltet alternatives foreslår konkrete neste handlinger som koordinatoren (eller et menneske) kan utføre.
Eksempler: «prøv mot lesereplikaen på nytt», «utvid datofilteret», «be brukeren om et ordrenummer», «eskaler til et menneske med delresultatene vedlagt».
Det er dette som gjør en strukturert feil til en rutinginstruksjon i stedet for bare en rapport.
return {
"isError": True,
"errorCategory": "business",
"isRetryable": False,
"attempted_query": "process_refund(order='O-77', amount=620)",
"partial_results": {"order_total": 620, "customer_verified": True},
"alternatives": [
"Refund exceeds $500 policy cap — escalate to human",
"Offer store credit within auto-approve limit",
],
"message": "Refund blocked by policy threshold",
}Gjenopprett lokalt, eskaler feil som ikke kan gjenopprettes
Strukturert kontekst legger grunnlaget for en tydelig policy. Håndter transient-feil inne i underagenten — prøv tidsavbruddet på nytt og vent lenger ved en hastighetsbegrensning — slik at koordinatoren aldri ser et problem som kan gjenopprettes.
Først når en feil faktisk ikke kan gjenopprettes (policygrensen er nådd, tilgangen er nektet eller alle nye forsøk er brukt opp), eskalerer De oppover — og De eskalerer med delresultatene og alternativene vedlagt, ikke som en ren «mislyktes»-melding.
Målet er å ikke avbryte hele arbeidsflyten fordi én gren feilet.
for attempt in range(3): # local recovery for transient faults
res = run_query()
if not res.get("isError"):
return res
if not res.get("isRetryable"):
break # non-recoverable: stop retrying
# escalate upward WITH context, never a bare failure
return escalate(res)Håndhev strukturen med et skjema
Feildikter i friform driver over tid. Håndhev kontrakten med et JSON Schema via et verktøy eller strukturert output, slik at underagenten må fylle ut de riktige feltene.
En viktig regel fra design av strukturert output: Marker et felt som påkrevd bare hvis det alltid er til stede. errorCategory og message finnes alltid — krev dem. partial_results og alternatives kan mangle — la dem være valgfrie, ellers vil modellen fabrikere dem for å oppfylle skjemaet.
error_schema = {
"type": "object",
"properties": {
"errorCategory": {"enum": ["transient", "validation",
"business", "permission", "other"]},
"isRetryable": {"type": "boolean"},
"attempted_query": {"type": "string"},
"partial_results": {"type": "array"},
"alternatives": {"type": "array", "items": {"type": "string"}},
"message": {"type": "string"},
},
"required": ["errorCategory", "isRetryable", "message"],
}Kontekst krysser ikke agentgrenser av seg selv
Underagenter arver ikke koordinatorens samtalehistorikk. Når en underagent feiler, kjenner koordinatoren derfor bare til det som uttrykkelig står i feilpayloaden.
Det er nettopp derfor attempted_query og partial_results må være med i den strukturerte feilen — det finnes ikke noe delt minne koordinatoren kan støtte seg på. Feilkontexten er hele broen mellom dem.
Begrens den til de relevante feltene, men fjern aldri de fire grunnpilarene.
# Coordinator delegates; subagent returns ONLY its payload.
# No shared history -> the error context must be self-contained.
results = await asyncio.gather(
research_subagent("EU AI Act"),
research_subagent("US AI policy"),
)
for r in results:
if r.get("isError") and not r["isRetryable"]:
annotate_coverage_gap(r["attempted_query"], r["partial_results"])Slik henger det sammen
En feilkontext av produksjonskvalitet lar koordinatoren handle uten å kjøre noe på nytt selv:
- feiltype +
isRetryable→ avgjørelse om nytt forsøk eller eskalering - forespørsel som ble forsøkt → gjenskap eller omformuler
- delvise resultater → ta vare på fremdriften og annoter mangelen
- alternativer → det konkrete neste trekket
Dette er forskjellen mellom en sårbar pipeline som stopper ved første lille problem, og et robust system som degraderer på en kontrollert måte og finner veier rundt skaden.
{
"isError": true,
"errorCategory": "permission",
"isRetryable": false,
"attempted_query": "SELECT * FROM payroll WHERE dept='ENG'",
"partial_results": [],
"alternatives": [
"Request read grant on payroll schema",
"Escalate to data-owner for approval"
],
"message": "Access denied to payroll table"
}Kort kontroll
En research-underagent fikk i oppgave å samle inn 10 kilder. Etter å ha samlet inn 6 ble den nyhets-API-et hastighetsbegrenset (HTTP 429). Hva bør underagenten returnere til koordinatoren?
Oppsummering — Strukturert feilkontext
Viktigste punkter:
- Generiske feil blokkerer gjenoppretting; strukturerte feil muliggjør intelligent ruting.
- Ta alltid med de fire grunnpilarene: feiltype, forespørsel som ble forsøkt, delvise resultater, alternativer.
- Bruk
errorCategory(transient / validation / business / permission) +isRetryabletil å avgjøre om De skal prøve på nytt eller eskalere. - Skill mellom en tilgangsfeil (kan kanskje prøves på nytt) og et gyldig tomt resultat (ingen treff — et nytt forsøk hjelper ikke).
- Gjenopprett transient-feil lokalt i underagenten, og eskaler feil som ikke kan gjenopprettes med delresultatene vedlagt.
- Undertrykk aldri feil i stillhet, og avbryt aldri hele arbeidsflyten på grunn av én enkelt feil.
- Håndhev strukturen med et skjema, men krev bare felt som er alltid til stede — valgfrie grunnpilarer må forbli valgfrie for å unngå fabrikering.
Lær deg Python med en AI-veileder – gratis
Skriv og kjør ekte kode i nettleseren, få umiddelbar hjelp fra en AI-veileder som er tilgjengelig døgnet rundt, og fortsett der du slapp – på nettet eller i appen.
- Kurs
- 26
- Leksjoner
- 104
Ofte stilte spørsmål
Er leksjonen «Strukturert feilkontekst» gratis?
Ja – du kan lese valgfritt 3 av leksjonene i læringsstien Claude Architect, inkludert «Strukturert feilkontekst», gratis i sin helhet her på nettet. Deretter låser CoddyKit PRO opp alle leksjoner, samt interaktiv øving med en innebygd kodeeditor og en AI-veileder som er tilgjengelig døgnet rundt. Kurset i Claude Architect inneholder totalt 4 leksjoner.
Hva lærer jeg i «Strukturert feilkontekst»?
Feiltype, forsøkt spørring, delvise resultater og alternativer. Du øver på Claude Architect med praktisk kode som du kjører direkte i nettleseren, mens en AI-veileder som er tilgjengelig døgnet rundt, svarer på spørsmålene dine mens du jobber deg gjennom leksjonen.
Trenger jeg erfaring for å begynne med Claude Architect?
Ingen tidligere erfaring er nødvendig. Claude Architect på CoddyKit er lagt opp for både nybegynnere og viderekomne, så De kan begynne her eller helt fra start og lære i Deres eget tempo. Dette er leksjon 3 av 4.
Hvor lang tid tar leksjonen «Strukturert feilkontekst»?
De fleste CoddyKit-leksjoner tar omtrent 5–10 minutter. Hver leksjon er kort og interaktiv, slik at De gjør jevne fremskritt og kan fortsette akkurat der De slapp – både på nettet og i appen.
Kan jeg skrive og kjøre kode i denne Claude Architect-leksjonen?
Ja. Alle Claude Architect-leksjoner har en innebygd kodeeditor, slik at De kan skrive og kjøre ekte kode direkte i nettleseren og få umiddelbar tilbakemelding fra AI – uten lokal konfigurering.
Alle leksjonene i dette kurset
- Tydelige utløsere for eskalering
- Antimønster: Følelses- og konfidensskårer
- Strukturert feilkontekst
- Lokal gjenoppretting kontra eskalering