Claude Architect · Oppitunti

Uudelleenyrityksen metatiedot ja osittaiset tulokset

errorCategory, isRetryable, attempted_query, partials.

Oppitunti 3/413 vaihetta

Uudelleenyrityksen metatiedot ja osittaiset tulokset on ilmainen Claude Architect-oppitunti CoddyKitissä. Tämä on oppitunti 3/4. Voit lukea tästä oppimispolusta kokonaan mitkä tahansa 3 oppituntia ilmaiseksi — sen jälkeen CoddyKit PRO avaa kaikki oppitunnit sekä käytännön harjoittelun sisäänrakennetulla koodieditorilla ja ympäri vuorokauden toimivalla tekoälytuutorilla. Oppitunti kuuluu Claude Architect-oppimispolkuun, ja edistymisesi synkronoituu verkon ja CoddyKit-sovelluksen välillä. Claude Architect-kurssilla on yhteensä 4 oppituntia.

Miksi virheen rakenne on tärkeä

Kun työkalu tai MCP-palvelin epäonnistuu, mallin on päätettävä, mitä seuraavaksi tehdään. Yleinen tila, kuten "Operation failed", ei anna päätöksentekoon mitään tietoa, joten ainoiksi turvallisiksi vaihtoehdoiksi jäävät keskeyttäminen tai arvaaminen.

Jäsennelty virhe muuttaa umpikujan päätökseksi: yritetäänkö uudelleen, kierretäänkö virhe vai eskaloidaanko asia ihmiselle? Tässä oppitunnissa opitte neljä metatietokenttää, jotka tekevät tämän mahdolliseksi: errorCategory, isRetryable, attempted_query ja partial_results.

isError-lippu

Jokainen jäsennelty MCP-virhe alkaa yhdestä totuusarvosta: isError: true. Tämä on yksiselitteinen signaali siitä, että työkalun tulos on virhe eikä dataa.

Ilman sitä malli saattaa käsitellä virheilmoitusta kelvollisena vastauksena ja tiivistää virheen tyytyväisenä aivan kuin se olisi tulos. Lippu on portti, joka aktivoi kaiken sitä seuraavan palautuslogiikan.

tool_result = {
    "isError": True,
    "errorCategory": "transient",
    "isRetryable": True,
    "message": "Upstream timeout contacting orders DB",
    "attempted_query": "SELECT * FROM orders WHERE id='A-2291'",
    "partial_results": []
}

errorCategory: neljä luokkaa

errorCategory luokittelee, miksi kutsu epäonnistui, jotta malli voi reitittää älykkäästi. Neljä vakioluokkaa ovat:

transient — tilapäinen vika (aikakatkaisu, nopeusrajoitus). Uudelleenyritys on todennäköisesti aiheellinen.
validation — syöte oli virheellisessä muodossa. Korjatkaa pyyntö, älkää yrittäkö sokeasti uudelleen.
business — toimialasääntö esti toiminnon (esimerkiksi tilaus on jo lähetetty).
permission — kutsujalla ei ole tarvittavia käyttöoikeuksia. Uudelleenyritys ei auta; eskaloikaa tai tunnistautukaa uudelleen.

Luokka ohjaa strategiaa; se ei yksin tee päätöstä.

isRetryable: toimintavihje

isRetryable ilmaisee yksiselitteisesti kyllä tai ei, voiko uudelleenyritys mahdollisesti onnistua. Se toimii yhdessä luokan kanssa, mutta antaa täsmällisemmän signaalin.

transient-aikakatkaisussa on yleensä isRetryable: true. validation-virheessä on isRetryable: false — saman virheellisen syötteen yrittäminen uudelleen epäonnistuu vain jälleen. Tämä mahdollistaa ennen kaikkea sen, että aliagentti voi palautua tilapäisistä vioista paikallisesti sen sijaan, että jokainen häiriö välitettäisiin koordinaattorille.

if result.get("isError"):
    if result["isRetryable"] and attempt < max_attempts:
        attempt += 1
        continue          # recover locally in the subagent
    else:
        escalate(result)  # non-recoverable: pass it up with context

Älkää sekoittako virhettä tyhjään tulokseen

Hienovarainen mutta kokeen kannalta ratkaiseva ero: käyttöoikeuksien VIRHE ei ole sama asia kuin kelvollinen TYHJÄ tulos.

isError: true + transient → kyselyä ei voitu suorittaa. Harkitkaa uudelleenyritystä.
isError: false + tyhjä lista → kysely suoritettiin ongelmitta, eikä osumia todellakaan ole. Uudelleenyritys on turha ja tuhlaava.

Yleiset virheet hämärtävät tämän eron. Jäsennelty metatieto pitää selkeästi erillään tilanteet "en pystynyt tarkistamaan" ja "tarkistin, mutta mitään ei löytynyt".

attempted_query: mahdollista uudelleenyritys

attempted_query tallentaa täsmälleen, mitä työkalu yritti tehdä — SQL-kyselyn, API-kutsun tai hakumerkkijonon. Tällä on kaksi tarkoitusta:

Sen ansiosta malli voi yrittää uudelleen palautteen perusteella: alkuperäinen tavoite ja virhe lähetetään, jotta voidaan muodostaa korjattu kysely.
Se tuottaa alkuperäketjun — käytettävissä säilyy jälki siitä, mitä todella pyydettiin ja mistä lähteestä väite on peräisin.

Muistakaa: palautteen perusteella tehtävä uudelleenyritys korjaa muotoilu- ja rakennevirheitä. Jos tietoa ei yksinkertaisesti ole lähteessä, mikään kyselyn toistaminen ei auta.

{
    "isError": True,
    "errorCategory": "validation",
    "isRetryable": True,
    "message": "Unknown column 'order_no'; did you mean 'order_id'?",
    "attempted_query": "SELECT * FROM orders WHERE order_no='A-2291'",
    "partial_results": []
}

partial_results: Älkää heittäkö hyvää dataa pois

Kun monivaiheinen tai useista lähteistä koostuva toiminto epäonnistuu puolivälissä, ennen virhettä tehty työ on yhä arvokasta. partial_results välittää sen eteenpäin.

Kuvitelkaa tutkimusaliagentti, joka kyseli viidestä lähteestä ja jonka viidennen lähteen kysely aikakatkaistiin. Kun neljä onnistunutta tulosta palautetaan virheen lisäksi, koordinaattori voi jatkaa työtä sen sijaan, että kaikki hylättäisiin yhden epäonnistuneen vaiheen vuoksi. Älkää koskaan keskeyttäkö koko työnkulkua yhden virheen vuoksi.

{
    "isError": True,
    "errorCategory": "transient",
    "isRetryable": True,
    "message": "Source 5 (vendor API) timed out after 4 of 5 sources",
    "attempted_query": "fetch pricing from [s1..s5]",
    "partial_results": [
        {"source": "s1", "price": 19.0},
        {"source": "s2", "price": 21.5},
        {"source": "s3", "price": 18.9},
        {"source": "s4", "price": 20.0}
    ]
}

Palauta paikallisesti, eskaloi kontekstin kanssa

Metatieto mahdollistaa keskitetyn koordinaattorin ja aliagenttien järjestelmissä selkeän kaksitasoisen strategian:

Palautukaa tilapäisistä vioista paikallisesti aliagentin sisällä — yrittäkää isRetryable-tapauksia uudelleen huomaamattomasti.
Eskaloi palautumattomat virheet koordinaattorille ja välitä mukana koko jäsennelty konteksti: virhetyyppi, yritetty kysely ja mahdolliset osittaiset tulokset.

Koordinaattori käsittelee virheet ja reitittää ne. Se voi kuitenkin reitittää hyvin vain, jos aliagentti välittää sille jäsennellyn signaalin eikä pelkkää poikkeusta tai hiljaisuutta.

Virheskeeman suunnittelu

Jos määrittelette virheen jäsennellyksi tulosteeksi, soveltakaa skeeman sääntöjä huolellisesti. Merkitkää kenttä pakolliseksi vain, jos se on aina mukana. partial_results on kovan virheen yhteydessä usein tyhjä tai puuttuu kokonaan — älkää siis pakottako sitä pakolliseksi, sillä muuten malli saattaa keksiä merkintöjä täyttääkseen skeeman vaatimukset.

Käyttäkää errorCategory-kentässä enumia, jossa on arvo "other" ja lisäksi vapaatekstinen tarkennuskenttä. Näin luokittelu pysyy selkeänä nyt ja sitä voidaan laajentaa myöhemmin vielä kohtaamattomia virhetilanteita varten.

error_schema = {
    "type": "object",
    "properties": {
        "isError": {"type": "boolean"},
        "errorCategory": {
            "enum": ["transient", "validation",
                     "business", "permission", "other"]
        },
        "categoryDetail": {"type": "string"},
        "isRetryable": {"type": "boolean"},
        "attempted_query": {"type": "string"},
        "partial_results": {"type": "array"}
    },
    "required": ["isError", "errorCategory", "isRetryable"]
}

Koukut rahaa aiheuttaville virheille

Metatieto ohjaa mallia todennäköisyyspohjaisesti (noin 90-prosenttisesti). Kun virheellä on taloudellisia, oikeudellisia tai turvallisuuteen liittyviä seurauksia, se ei riitä.

Käyttäkää PostToolUse-hookia sieppaamaan työkalun tulos ennen kuin malli näkee sen ja valvomaan käytäntöä deterministisesti (100-prosenttisesti). Jos esimerkiksi errorCategory on hyvitystyökalussa permission, estäkää kaikki uudelleenyritykset ja pakottakaa eskalointi — älkää jättäkö toimintaa kehotteen varaan.

# PostToolUse hook: deterministic guard on structured errors
def post_tool_use(result):
    if result.get("isError") and \
       result["errorCategory"] == "permission":
        return block_and_escalate(
            reason=result["message"],
            attempted=result["attempted_query"])
    return result

Vastamalli: hiljainen vaientaminen

Pahinta, mitä virheelle voi tehdä, on piilottaa se. Välttäkää näitä kahta virheenkäsittelytapaa:

Hiljainen vaientaminen — virheen nieleminen ja tyhjän tai keksityn tuloksen palauttaminen. Tällöin malli ei pysty erottamaan todellista "ei osumia" -tilannetta rikkoutuneesta kyselystä.
Koko työnkulun keskeyttäminen yhden epäonnistuneen vaiheen vuoksi — kaikki osittaiset tulokset heitetään pois.

Jäsennellyt virheet ratkaisevat molemmat ongelmat: ne tuovat virheen näkyviin ja säilyttävät onnistuneen työn tulokset.

Pikatarkistus: osittaisen virheen reititys

Soveltakaa oppimaanne todelliseen moniagenttiseen tilanteeseen.

Vastaa interaktiivisessa oppitunnissa

Kertaus: palautustyökalut

Jäsennellyt virheet muuttavat virheet reititettäviksi päätöksiksi:

isError — portti, joka aktivoi palautuslogiikan.
errorCategory — transient / validation / business / permission (+ "other") määrittää strategian.
isRetryable — yksiselitteinen uudelleenyritysvihje; palaudu tilapäisistä vioista paikallisesti.
attempted_query — mahdollistaa palautteen perusteella tehtävän uudelleenyrityksen ja alkuperäketjun (ei auta, jos tietoa todella puuttuu).
partial_results — välittää hyvän datan eteenpäin; älä koskaan keskeytä koko työnkulkua yhden virheen vuoksi.

Merkitkää pakollisiksi vain aina mukana olevat kentät, suojatkaa raha-, oikeus- ja turvallisuusvirheet deterministisillä hookeilla älkääkä koskaan vaientako virheitä hiljaisesti. Tällaista on arkkitehtitason virheenkäsittely.

Aloita maksutta

Opi Python tekoälytuutorin avulla — ilmaiseksi

Kirjoita ja suorita oikeaa koodia selaimessa, saa välitöntä apua tekoälytuutorilta ympäri vuorokauden ja jatka siitä, mihin jäit, verkossa tai sovelluksessa.

Kurssit: 26
Oppitunnit: 104

Aloita opiskelu maksutta Näytä koko kurssi

Usein kysytyt kysymykset

Onko oppitunti ”Uudelleenyrityksen metatiedot ja osittaiset tulokset” ilmainen?

Kyllä — voit lukea täällä verkossa kokonaan ilmaiseksi mitkä tahansa Claude Architect-oppimispolun 3 oppituntia, myös oppitunnin “Uudelleenyrityksen metatiedot ja osittaiset tulokset”. Sen jälkeen CoddyKit PRO avaa kaikki oppitunnit sekä interaktiiviset harjoitukset sisäänrakennetulla koodieditorilla ja ympäri vuorokauden toimivalla tekoälytuutorilla. Claude Architect-kurssilla on yhteensä 4 oppituntia.

Mitä opin oppitunnilla ”Uudelleenyrityksen metatiedot ja osittaiset tulokset”?

errorCategory, isRetryable, attempted_query, partials. Harjoittelet Claude Architect-aihetta koodilla, jonka suoritat suoraan selaimessa. Ympäri vuorokauden käytettävissä oleva tekoälytuutori vastaa kysymyksiisi oppitunnin aikana.

Tarvitsenko kokemusta aloittaakseni Claude Architect-opiskelun?

Aiempi kokemus ei ole tarpeen. CoddyKitin Claude Architect-oppimispolku sopii vasta-alkajista edistyneisiin, joten voit aloittaa tästä tai alusta ja edetä omaan tahtiisi. Tämä on oppitunti 3/4.

Kuinka kauan ”Uudelleenyrityksen metatiedot ja osittaiset tulokset”-oppitunnin suorittaminen kestää?

Useimmat CoddyKitin oppitunnit kestävät noin 5–10 minuuttia. Jokainen oppitunti on lyhyt ja interaktiivinen, joten edistyt tasaisesti ja voit jatkaa siitä, mihin jäit – sekä verkossa että sovelluksessa.

Voinko kirjoittaa ja suorittaa koodia tällä Claude Architect-oppitunnilla?

Kyllä. Jokainen Claude Architect-oppitunti sisältää sisäänrakennetun koodieditorin, joten voit kirjoittaa ja suorittaa oikeaa koodia suoraan selaimessa ja saada välitöntä palautetta tekoälyltä – paikallista asennusta ei tarvita.

Kaikki tämän kurssin oppitunnit

isError-lippu
Virheluokat
Uudelleenyrityksen metatiedot ja osittaiset tulokset
Vastaesimerkki: yleiset virheilmoitukset

← Takaisin: Claude Architect