Konteks Ralat Berstruktur
Jenis kegagalan, pertanyaan yang dicuba, hasil separa dan alternatif
Konteks Ralat Berstruktur ialah pelajaran Claude Architect percuma di CoddyKit. Ini ialah pelajaran 3 daripada 4. Sebanyak 3 pelajaran dalam laluan pembelajaran ini boleh dibaca sepenuhnya secara percuma — selepas itu, CoddyKit PRO membuka akses kepada semua pelajaran, serta latihan praktikal dengan penyunting kod terbina dalam dan tutor kecerdasan buatan yang tersedia 24/7. Pelajaran ini merupakan sebahagian daripada laluan pembelajaran Claude Architect, dan kemajuan anda disegerakkan merentas web serta aplikasi CoddyKit. Kursus Claude Architect merangkumi sejumlah 4 pelajaran.
Sebab Ralat Memerlukan Struktur
Dalam sistem berbilang ejen, subejen akhirnya akan menghadapi kegagalan: pangkalan data tidak tersedia, pertanyaan tidak mengembalikan apa-apa, atau kebenaran ditolak. Cara kegagalan itu dilaporkan menentukan sama ada penyelaras boleh memulihkan keadaan dengan bijak atau sekadar berputus asa.
Status umum seperti "Operation failed" menghalang pemulihan — penyelaras tidak tahu perkara yang patut dilakukan seterusnya. Konteks ralat berstruktur mengubah jalan buntu menjadi keputusan penghalaan.
Pelajaran ini merangkumi empat tunjang konteks ralat yang baik: jenis kegagalan, pertanyaan yang dicuba, hasil separa dan alternatif.
Antipola Ralat Umum
Bandingkan dua muatan ralat yang diterima daripada subagen atau alat.
Versi generik tidak memberikan apa-apa maklumat yang boleh diambil tindakan kepada penyelaras. Ia tidak dapat menentukan sama ada perlu mencuba semula, meminta input tambahan daripada pengguna atau escalate. Penindasan secara senyap adalah lebih buruk — aliran kerja diteruskan seolah-olah data wujud walaupun sebenarnya tiada.
Versi berstruktur menyatakan apa yang gagal dan sebabnya, iaitu langkah pertama ke arah tindakan seterusnya yang bijak.
# 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",
}Teras 1 — Jenis Kegagalan
Tugas pertama konteks ralat adalah untuk mengelaskan kegagalan. Ralat MCP berstruktur membawa medan errorCategory dengan perbendaharaan kata kecil yang tetap:
- sementara — kerosakan infrastruktur sementara (had masa, had kadar). Selalunya boleh dicuba semula.
- pengesahan — input tidak berformat dengan betul.
- perniagaan — peraturan domain menghalang tindakan tersebut.
- kebenaran — akses dinafikan.
Boolean isRetryable yang menyertainya menghapuskan tekaan: penyelaras membacanya secara terus dan bukannya membuat kesimpulan daripada mesej teks bebas.
{
"isError": true,
"errorCategory": "transient",
"isRetryable": true,
"message": "Rate limit hit on inventory service"
}Kegagalan berbanding Hasil Kosong
Satu perbezaan yang sering mengelirukan arkitek ialah: kegagalan akses tidak sama dengan hasil kosong yang sah.
- Kegagalan: carian tidak dapat dijalankan — pangkalan data tidak boleh dicapai, kebenaran dinafikan. Hal ini mungkin wajar dicuba semula.
- Kosong: carian berjaya dijalankan tetapi menemukan sifar padanan. Percubaan semula tidak mengubah apa-apa — jawapannya benar-benar "tiada".
Mencampuradukkan kedua-duanya menyebabkan gelung percubaan semula yang sia-sia untuk hasil kosong, atau menyebabkan gangguan sebenar dianggap sebagai "tiada data ditemui". Sentiasa modelkan kedua-duanya sebagai keadaan yang berasingan.
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)}Teras 2 — Pertanyaan yang Dicuba
Penyelaras tidak menjalankan operasi yang gagal itu sendiri, jadi ia tidak dapat melihat perkara yang telah dicuba. Sertakan attempted_query secara verbatim dalam konteks ralat.
Hal ini mempunyai dua tujuan:
- Ia membolehkan penyelaras menentukan sama ada perlu mencuba semula dengan pertanyaan yang sama atau merumuskan semulanya (contohnya, meluaskan penapis yang terlalu sempit).
- Ia memberikan penyemak manusia, apabila berlaku eskalasi, kes penghasilan semula yang tepat dan bukannya mesej umum "carian gagal".
return {
"isError": True,
"errorCategory": "transient",
"isRetryable": True,
"attempted_query": {
"endpoint": "GET /orders",
"filters": {"customer_id": "C-4821", "status": "shipped"},
},
"message": "Orders service returned 503",
}Teras 3 — Hasil Separa
Kegagalan jarang bermaksud tiada kerja yang berjaya dilakukan. Subagen penyelidikan mungkin telah gathered 6 daripada 10 sumber sebelum penyedia mengenakan had kadar. Membuang kesemuanya — atau membatalkan seluruh aliran kerja — mensia-siakan kemajuan sebenar.
Lampirkan apa sahaja yang berjaya dikumpulkan sebagai partial_results. Penyelaras kemudiannya boleh mengagregatkan perkara yang ada, menganotasi jurang tersebut dan menentukan sama ada baki kerja berbaloi untuk dicuba lagi.
Jangan sekali-kali menindas kegagalan secara senyap dan mempersembahkan hasil separa seolah-olah lengkap.
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",
}Teras 4 — Alternatif
Konteks ralat yang paling berguna bukan sekadar menerangkan halangan — konteks itu menunjukkan jalan keluar. Medan alternatives mencadangkan tindakan seterusnya yang konkrit yang boleh diambil oleh penyelaras (atau manusia).
Contoh: "cuba semula terhadap replika bacaan", "luaskan penapis tarikh", "minta nombor pesanan daripada pengguna", "escalate kepada manusia dengan hasil separa dilampirkan".
Inilah yang mengubah ralat berstruktur daripada sekadar laporan menjadi arahan penghalaan.
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",
}Pulihkan Secara Setempat, Eskalasi yang Tidak Boleh Dipulihkan
Konteks berstruktur mendorong dasar yang jelas. Kendalikan kerosakan sementara di dalam subagen — cuba semula had masa, undur apabila terkena had kadar — supaya penyelaras tidak perlu melihat gangguan yang boleh dipulihkan itu.
Hanya apabila kerosakan benar-benar tidak boleh dipulihkan (had dasar dicapai, kebenaran dinafikan, percubaan semula habis) barulah anda escalate ke peringkat lebih tinggi — dan anda perlu berbuat demikian dengan hasil separa serta alternatif dilampirkan, bukannya sekadar "gagal".
Matlamatnya: jangan batalkan seluruh aliran kerja hanya kerana satu cabang gagal.
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)Menguatkuasakan Bentuk dengan Skema
Dict ralat berbentuk bebas berubah-ubah dari semasa ke semasa. Kuatkuasakan kontrak tersebut dengan Skema JSON melalui alat / output berstruktur supaya subagen mesti mengisi medan yang betul.
Peraturan utama daripada reka bentuk output berstruktur: tandakan medan sebagai diperlukan hanya jika medan itu sentiasa ada. errorCategory dan message sentiasa ada — jadikan kedua-duanya wajib. partial_results dan alternatives mungkin tiada — biarkan kedua-duanya pilihan, jika tidak model akan mereka-reka nilainya untuk memenuhi skema.
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"],
}Konteks Tidak Merentasi Sempadan Ejen Secara Percuma
Subagen tidak mewarisi sejarah perbualan penyelaras. Oleh itu, apabila subagen gagal, penyelaras hanya mengetahui perkara yang dibawa secara jelas oleh muatan ralat.
Itulah sebabnya attempted_query dan partial_results mesti berada dalam ralat berstruktur — tiada memori dikongsi yang boleh digunakan oleh penyelaras sebagai sandaran. Konteks ralat ialah satu-satunya jambatan antara kedua-duanya.
Ringkaskannya kepada medan yang berkaitan, tetapi jangan sekali-kali membuang empat teras tersebut.
# 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"])Menggabungkan Kesemuanya
Konteks ralat bertaraf produksi membolehkan penyelaras bertindak tanpa menjalankan semula apa-apa sendiri:
- jenis kegagalan +
isRetryable→ keputusan cuba semula atau escalate - pertanyaan yang dicuba → hasilkan semula atau rumuskan semula
- hasil separa → selamatkan kemajuan, anotasi jurang
- alternatif → tindakan seterusnya yang konkrit
Inilah perbezaan antara pipeline rapuh yang terhenti pada gangguan pertama dengan sistem berdaya tahan yang merosot secara terkawal dan menghala mengelilingi kerosakan.
{
"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"
}Semakan Pantas
Subagen penyelidikan diminta untuk gather 10 sumber. Selepas mengumpulkan 6 sumber, API berita mengenakan had kadar terhadapnya (HTTP 429). Apakah yang patut dipulangkan oleh subagen kepada penyelaras?
Imbas Kembali — Konteks Ralat Berstruktur
Perkara utama:
- Ralat generik menghalang pemulihan; ralat berstruktur membolehkan penghalaan yang bijak.
- Sentiasa bawa empat teras: jenis kegagalan, pertanyaan yang dicuba, hasil separa, alternatif.
- Gunakan
errorCategory(sementara / pengesahan / perniagaan / kebenaran) +isRetryableuntuk menentukan keputusan cuba semula atau escalate. - Bezakan kegagalan akses (mungkin boleh dicuba semula) daripada hasil kosong yang sah (tiada padanan — percubaan semula tidak membantu).
- Pulihkan kerosakan sementara secara setempat dalam subagen; escalate kerosakan yang tidak boleh dipulihkan dengan hasil separa dilampirkan.
- Jangan sekali-kali menindas ralat secara senyap dan jangan sekali-kali membatalkan seluruh aliran kerja hanya kerana satu kegagalan.
- Kuatkuasakan bentuk dengan skema, tetapi hanya wajibkan medan yang sentiasa ada — teras pilihan mesti kekal pilihan untuk mengelakkan rekaan.
Pelajari Python dengan tutor kecerdasan buatan — percuma
Tulis dan jalankan kod sebenar dalam pelayar anda, dapatkan bantuan segera daripada tutor kecerdasan buatan yang tersedia 24/7, dan sambung semula dari tempat anda berhenti di web atau dalam aplikasi.
- Kursus
- 26
- Pelajaran
- 104
Soalan Lazim
Adakah pelajaran “Konteks Ralat Berstruktur” percuma?
Ya — sebanyak 3 pelajaran dalam laluan pembelajaran Claude Architect, termasuk “Konteks Ralat Berstruktur”, boleh dibaca sepenuhnya secara percuma di web ini. Selepas itu, CoddyKit PRO membuka akses kepada semua pelajaran, serta latihan interaktif dengan penyunting kod terbina dalam dan tutor kecerdasan buatan yang tersedia 24/7. Kursus Claude Architect merangkumi sejumlah 4 pelajaran.
Apakah yang akan saya pelajari dalam “Konteks Ralat Berstruktur”?
Jenis kegagalan, pertanyaan yang dicuba, hasil separa dan alternatif Anda berlatih Claude Architect menggunakan kod praktikal yang dijalankan terus dalam pelayar, manakala tutor kecerdasan buatan 24/7 menjawab soalan anda semasa anda mengikuti pelajaran.
Adakah saya memerlukan pengalaman untuk memulakan Claude Architect?
Tiada pengalaman terdahulu diperlukan. Pembelajaran Claude Architect di CoddyKit disusun untuk pelajar daripada peringkat pemula hingga lanjutan, jadi anda boleh bermula di sini atau dari awal dan belajar mengikut kadar anda sendiri. Ini ialah pelajaran 3 daripada 4.
Berapa lamakah pelajaran “Konteks Ralat Berstruktur” diambil?
Kebanyakan pelajaran CoddyKit mengambil masa kira-kira 5–10 minit. Setiap pelajaran ringkas dan interaktif, jadi anda boleh membuat kemajuan secara berterusan dan menyambung tepat dari tempat anda berhenti di web atau aplikasi.
Bolehkah saya menulis dan menjalankan kod dalam pelajaran Claude Architect ini?
Ya. Setiap pelajaran Claude Architect menyertakan penyunting kod terbina dalam, jadi anda boleh menulis dan menjalankan kod sebenar terus dalam pelayar serta menerima maklum balas kecerdasan buatan serta-merta — tanpa memerlukan persediaan setempat.
Semua pelajaran dalam kursus ini
- Pencetus Eskalasi yang Jelas
- Anti-Corak: Skor Sentimen dan Keyakinan
- Konteks Ralat Berstruktur
- Pemulihan Setempat berbanding Eskalasi