Strukturerad felkontext
Feltyp, försökt fråga, partiella resultat och alternativ.
Strukturerad felkontext är en gratis lektion i Claude Architect på CoddyKit. Detta är lektion 3 av 4. Du kan läsa vilka 3 lektioner som helst i den här lärvägen kostnadsfritt i sin helhet – därefter låser CoddyKit PRO upp alla lektioner, plus praktisk övning med en inbyggd kodredigerare och en AI-lärare dygnet runt. Den ingår i lärvägen för Claude Architect, och Era framsteg synkroniseras mellan webben och CoddyKit-appen. Kursen i Claude Architect innehåller totalt 4 lektioner.
Varför fel behöver struktur
I ett multiagentsystem kommer en underagent förr eller senare att stöta på ett fel: en databas ligger nere, en fråga ger inget resultat eller åtkomst nekas. Hur felet rapporteras avgör om koordinatorn kan återhämta sig på ett intelligent sätt eller bara ger upp.
En generell status som "Operation failed" försvårar återhämtning — koordinatorn har ingen aning om vad den ska göra härnäst. En strukturerad felkontext förvandlar en återvändsgränd till ett routningsbeslut.
Den här lektionen behandlar de fyra grundpelarna i en bra felkontext: feltyp, genomförd fråga, delresultat och alternativ.
Antimönstret med generiska fel
Jämför två felpayloadar som kommer tillbaka från en underagent eller ett verktyg.
Den generiska versionen berättar ingenting användbart för koordinatorn. Den kan inte avgöra om den ska försöka igen, be användaren om mer information eller eskalera. Tyst undertryckning är ännu värre — arbetsflödet fortsätter som om data fanns, trots att den saknas.
Den strukturerade versionen anger vad som misslyckades och varför, vilket är det första steget mot ett intelligent nästa steg.
# 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",
}Pelare 1 — Feltyp
Den första uppgiften för en felkontext är att klassificera felet. Strukturerade MCP-fel innehåller fältet errorCategory med ett litet, fast vokabulär:
- transient — tillfälligt infrastrukturfel (timeout, hastighetsbegränsning). Kan ofta hanteras genom ett nytt försök.
- validation — indata hade fel format.
- business — en domänregel blockerade åtgärden.
- permission — åtkomst nekades.
Det kompletterande booleska värdet isRetryable eliminerar gissningar: koordinatorn läser det direkt i stället för att försöka tolka avsikten utifrån ett fritextmeddelande.
{
"isError": true,
"errorCategory": "transient",
"isRetryable": true,
"message": "Rate limit hit on inventory service"
}Fel kontra tomt resultat
En distinktion som ständigt förvirrar arkitekter: ett åtkomstfel är inte samma sak som ett giltigt tomt resultat.
- Fel: uppslagningen kunde inte köras — databasen är inte nåbar eller åtkomst nekades. Det kan vara värt att försöka igen.
- Tomt: uppslagningen kördes utan problem och hittade noll matchningar. Ett nytt försök ändrar ingenting — svaret är verkligen "inga".
Om man blandar ihop dessa leder det till meningslösa försöksslingor för tomma resultat, eller till att ett faktiskt driftavbrott behandlas som "inga data hittades". Modellera dem alltid som separata tillstånd.
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)}Pelare 2 — Försökt fråga
Koordinatorn körde inte själv den operation som misslyckades och kan därför inte se vad som försöktes. Inkludera attempted_query ordagrant i felkontexten.
Detta har två syften:
- Det låter koordinatorn avgöra om den ska försöka igen med samma fråga eller omformulera den (till exempel bredda ett filter som var för snävt).
- Det ger den mänskliga granskaren, vid eskalering, det exakta reproduktionsfallet i stället för ett vagt "sökningen misslyckades".
return {
"isError": True,
"errorCategory": "transient",
"isRetryable": True,
"attempted_query": {
"endpoint": "GET /orders",
"filters": {"customer_id": "C-4821", "status": "shipped"},
},
"message": "Orders service returned 503",
}Pelare 3 — Delresultat
Ett fel betyder sällan att inget arbete har utförts. En research-underagent kan ha samlat in 6 av 10 källor innan en leverantör begränsade dess anropstakt. Att kasta bort allt detta — eller avbryta hela arbetsflödet — innebär att verkliga framsteg går förlorade.
Bifoga allt som kunde samlas in som partial_results. Koordinatorn kan då sammanställa det som finns, markera luckan och avgöra om det återstående är värt ett nytt försök.
Undertryck aldrig felet tyst och presentera delresultat som om de vore fullständiga.
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",
}Pelare 4 — Alternativ
De mest användbara felkontexterna beskriver inte bara hindret — de pekar också mot en väg framåt. Fältet alternatives föreslår konkreta nästa steg som koordinatorn (eller en människa) kan ta.
Exempel: "försök igen mot läsreplikan", "bredda datumfiltret", "be användaren om ett ordernummer", "eskalera till en människa med de bifogade delresultaten".
Det är detta som förvandlar ett strukturerat fel från en rapport till en dirigeringsinstruktion.
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",
}Återställ lokalt, eskalera fel som inte kan återställas
Strukturerad kontext möjliggör en tydlig policy. Hantera transient-fel inne i underagenten — försök igen efter timeout och tillämpa backoff vid hastighetsbegränsning — så att koordinatorn inte ens behöver se ett återställningsbart tillfälligt fel.
Först när ett fel verkligen inte kan återställas (en policygräns har nåtts, åtkomst nekas eller alla försök är uttömda) eskalerar ni uppåt — och då eskalerar ni med de bifogade delresultaten och alternativen, inte som ett naket "misslyckades".
Målet är att inte avbryta hela arbetsflödet för att en gren misslyckades.
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)Säkerställ strukturen med ett schema
Fritt formaterade feldictar förändras över tid. Säkerställ kontraktet med ett JSON Schema via ett verktyg eller strukturerat utdata, så att underagenten måste fylla i rätt fält.
En viktig regel för utformning av strukturerade utdata: markera ett fält som obligatoriskt endast om det alltid finns. errorCategory och message finns alltid — gör dem obligatoriska. partial_results och alternatives kan saknas — låt dem vara valfria, annars kommer modellen att fabricera dem för att uppfylla schemat.
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"],
}Kontext följer inte automatiskt med över agentgränser
Underagenter ärver inte koordinatorns konversationshistorik. När en underagent misslyckas känner koordinatorn därför bara till det som felpayloaden uttryckligen innehåller.
Det är precis därför attempted_query och partial_results måste finnas i det strukturerade felet — det finns inget gemensamt minne som koordinatorn kan falla tillbaka på. Felkontexten är hela bron mellan dem.
Begränsa den till de relevanta fälten, men ta aldrig bort de fyra pelarna.
# 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"])Sätt ihop helheten
En felkontext av produktionskvalitet låter koordinatorn agera utan att själv köra något igen:
- feltyp +
isRetryable→ beslut om nytt försök eller eskalering - försökt fråga → återskapa eller omformulera
- delresultat → ta vara på framsteg och markera luckan
- alternativ → det konkreta nästa steget
Detta är skillnaden mellan en skör pipeline som stannar vid första störningen och ett motståndskraftigt system som degraderar på ett kontrollerat sätt och hittar vägar runt skadan.
{
"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"
}Snabb kontroll
En research-underagent fick i uppgift att samla in 10 källor. Efter att ha samlat in 6 begränsade nyhets-API:t dess anropstakt (HTTP 429). Vad bör underagenten returnera till koordinatorn?
Sammanfattning — Strukturerad felkontext
Viktigaste lärdomarna:
- Generiska fel blockerar återställning; strukturerade fel möjliggör intelligent dirigering.
- Inkludera alltid de fyra pelarna: feltyp, försökt fråga, delresultat, alternativ.
- Använd
errorCategory(transient / validation / business / permission) +isRetryableför att styra beslutet om nytt försök eller eskalering. - Skilj på ett åtkomstfel (kan eventuellt lösas genom ett nytt försök) och ett giltigt tomt resultat (inga matchningar — ett nytt försök hjälper inte).
- Återställ transient-fel lokalt i underagenten; eskalera fel som inte kan återställas med bifogade delresultat.
- Undertryck aldrig fel tyst och avbryt aldrig hela arbetsflödet på grund av ett enskilt fel.
- Säkerställ strukturen med ett schema, men gör bara fält som alltid finns obligatoriska — valfria pelare måste förbli valfria för att undvika fabricering.
Lär dig Python med en AI-lärare – gratis
Skriv och kör riktig kod i webbläsaren, få omedelbar hjälp av en AI-lärare dygnet runt och fortsätt där du slutade – på webben eller i appen.
- Kurser
- 26
- Lektioner
- 104
Vanliga frågor
Är lektionen ”Strukturerad felkontext” gratis?
Ja – du kan läsa vilka 3 lektioner som helst i lärvägen Claude Architect, inklusive ”Strukturerad felkontext”, kostnadsfritt i sin helhet här på webben. Därefter låser CoddyKit PRO upp alla lektioner, plus interaktiv övning med en inbyggd kodredigerare och en AI-lärare dygnet runt. Kursen i Claude Architect innehåller totalt 4 lektioner.
Vad lär jag mig i ”Strukturerad felkontext”?
Feltyp, försökt fråga, partiella resultat och alternativ. Ni övar på Claude Architect med praktisk kod som körs direkt i webbläsaren, medan en AI-handledare som är tillgänglig dygnet runt svarar på Era frågor under lektionen.
Behöver jag någon erfarenhet för att börja lära mig Claude Architect?
Du behöver inga förkunskaper. Utbildningen i Claude Architect på CoddyKit är upplagd för allt från nybörjare till avancerade elever, så att du kan börja här eller från början och gå fram i din egen takt. Detta är lektion 3 av 4.
Hur lång tid tar lektionen ”Strukturerad felkontext”?
De flesta CoddyKit-lektioner tar cirka 5–10 minuter. Varje lektion är kort och interaktiv, så att du gör stadiga framsteg och kan fortsätta precis där du slutade – på webben eller i appen.
Kan jag skriva och köra kod i den här Claude Architect-lektionen?
Ja. Varje Claude Architect-lektion innehåller en inbyggd kodredigerare, så att du kan skriva och köra riktig kod direkt i webbläsaren och få omedelbar AI-feedback – utan lokal installation.
Alla lektioner i den här kursen
- Tydliga eskaleringsutlösare
- Antimönster: Sentiment- och konfidenspoäng
- Strukturerad felkontext
- Lokal återställning kontra eskalering