Claude Architect · Oppitunti

Vastaesimerkki: tekstin jäsentäminen valmistumisen tunnistamiseksi

Miksi tulosteen etsiminen 'done'-sanan varalta on hauraalla pohjalla ja väärin.

Oppitunti 3/413 vaihetta

Vastaesimerkki: tekstin jäsentäminen valmistumisen tunnistamiseksi 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.

Ansa

Rakennatte agentin. Se suorittaa työkaluja, ajattelee ja vastaa. Nyt teidän on tiedettävä, milloin se on valmis. Houkutteleva oikotie on etsiä mallin tekstistä sanaa kuten done, finished tai complete ja pysäyttää silmukka, kun sana löytyy.

Tämä on vastamalli nimeltä valmistumisen päättelemistä tekstistä. Se vaikuttaa intuitiiviselta, mutta on hauras ja väärä. Claude API antaa jo käyttöönne täsmällisen, rakenteisen valmistumissignaalin. Tässä oppitunnissa opitte, miksi tekstin läpikäynti ei toimi ja mitä sen sijaan kannattaa käyttää.

Miten agenttisilmukka todella toimii

Agenttisilmukkaa ohjaa yksi vastauksen kenttä: stop_reason. Silmukka on yksinkertainen ja deterministinen:

Lähettäkää pyyntö (koko viestihistorian kanssa jokaisella vuorolla).
Tarkastakaa stop_reason.
Jos sen arvo on tool_use, suorittakaa työkalut, lisätkää tulokset historiaan ja toistakaa.
Jos sen arvo on end_turn, tehtävä on valmis. Pysähtykää.

Malli kertoo itse rakenteisten metatietojen avulla, haluaako se jatkaa vai onko se valmis. Teidän ei tarvitse koskaan arvailla lukemalla proosatekstiä.

while True:
    response = client.messages.create(
        model="claude-opus-4-8",
        max_tokens=16000,
        tools=tools,
        messages=messages,
    )
    if response.stop_reason == "end_turn":
        break  # complete
    # else: tool_use -> run tools, append results, loop

Neljä pysäytyssyytä

Päättäkää suoritus signaalin, älkää sanojen perusteella. Claude palauttaa yhden neljästä pysäytyssyystä:

end_turn — Claude päätti luonnollisesti. Tehtävä on valmis.
tool_use — Claude haluaa työkalun suoritettavaksi; suorittakaa se ja jatkakaa silmukkaa.
max_tokens — tulos katkaistiin token-rajoituksen vuoksi.
stop_sequence — määritetty pysäytyssarja saavutettiin.

Jokainen näistä on yksiselitteinen ja koneellisesti luettava. Verratkaa tätä vapaan tekstin läpikäyntiin, jossa merkitys riippuu täysin siitä, miten malli sattui tällä kertaa muotoilemaan asiansa.

Miksi tekstin läpikäynti on hauraaa

Luonnollinen kieli ei ole ohjausprotokolla. Sama valmis tehtävä voi päättyä tusinalla eri tavalla:

"All done!"
"That completes the migration."
"I've finished the analysis."
"Everything is in place now."

done-sanan tarkistus osuu ensimmäiseen, ehkä toiseenkin, mutta ohittaa huomaamatta loput. Silmukka ei koskaan pysähdy. Kulutatte tokeneita ja aikaa tai saavutatte kovan rajan, vaikka tehtävä on todellisuudessa ollut valmis jo useita vuoroja.

# ANTI-PATTERN: brittle keyword scan
if "done" in response_text.lower():
    break  # misses "finished", "complete", "all set"...

Väärät positiiviset tulokset ovat pahempia

Signaalin huomaamatta jääminen tuhlaa resursseja. Vastakkainen virhe on vaarallisempi: pysähtyminen liian aikaisin.

Oletetaan, että pyydätte Claudea "check whether the deployment is done". Claude saattaa vastata kesken tutkimisen: "Let me verify the deploy is done before I continue." Tarkistus havaitsee sanan done ja lopettaa silmukan — tehtävä jää kesken ennen työkalun suorittamista tai vastauksen tuottamista.

Malli käyttää sanoja kuten done keskustelunomaisesti. Avainsanan täsmäytys ei erota selostusta aidosta valmistumissignaalista. stop_reason erottaa.

Malli ei säilytä tilaa

Tässä on syvempi syy siihen, miksi tekstin läpikäynti on väärä ratkaisu väärällä tasolla. Claude API on tilaton: malli ei säilytä muistia pyyntöjen välillä. Lähetätte koko keskustelun — system-viestin, kaikki aiemmat messages-vuorot ja työkalujen tulokset — jokaisella kutsulla.

Kysymys "onko agentti valmis?" koskee siis hallinnoimaanne silmukkaa, ja siihen vastaa API:n palauttama rakenteinen stop_reason — sitä ei pidä päätellä proosasta. Ohjaustaso (silmukkanne) ja sisältötaso (mallin teksti) ovat erillisiä. Pitäkää valmistumislogiikka ohjaustasolla.

# Stateless: full history goes up every turn
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    system=system_prompt,
    tools=tools,
    messages=messages,  # ENTIRE history, every call
)
messages.append({"role": "assistant", "content": response.content})

Oikea päättämistarkistus

Ohjatkaa silmukkaa pelkästään arvon stop_reason perusteella. Kun arvo on tool_use, suorittakaa pyydetyt työkalut ja lisätkää niiden tulokset historiaan vastaavan tool_use_id-tunnisteen kanssa. Kun arvo on end_turn, työ on valmis.

Tämä toimii riippumatta siitä, miten Claude muotoilee viimeisen viestinsä — "All set", "Finished" tai ei mitään. Päätös tehdään luotettavien metatietojen, ei valvottavaa merkkijonotäsmäytystä vaativan arvailun perusteella.

while True:
    response = client.messages.create(
        model="claude-opus-4-8", max_tokens=16000,
        tools=tools, messages=messages,
    )
    messages.append({"role": "assistant", "content": response.content})

    if response.stop_reason == "tool_use":
        results = run_tools(response.content)  # each with tool_use_id
        messages.append({"role": "user", "content": results})
        continue
    if response.stop_reason == "end_turn":
        break  # done -- no text parsing anywhere

Päätökset ovat mallin ohjaamia

Keskeinen arkkitehtuuriperiaate on tämä: agenttisilmukassa malli päättää työnkulun, ja päätös välittyy arvon stop_reason kautta. Te ette määrää, että "kolmen työkalun jälkeen on pakko olla valmista". Claude ilmoittaa, milloin se tarvitsee uutta työkalua ja milloin se on valmis.

Varatkaa kovakoodattu ohjaus asioille, jotka vaativat takuun — yrityksenne edellyttämälle deterministiselle invariantille. Valmistumisen havaitseminen ei ole tällainen asia, koska API tarjoaa siihen jo selkeän ratkaisun. Tekstin tulkintaan perustuva oma toteutus korvaa luotettavan signaalin arvauksella.

Iteraatiorajat ovat turvaverkko

"Hyvä on", sanotte, "pysäytän sen vain N iteraation jälkeen." Varokaa: iteraatioraja on turvaverkko, ei ensisijainen pysäytysmekanismi. Sen tarkoitus on rajoittaa hallitsemattomia silmukoita ja suojautua virheiltä — ei päättää, että työ on valmis.

Jos silmukkanne tarvitsee rajan päättyäkseen normaalisti, siinä on sama ongelma kuin tekstin läpikäynnissä: korvaatte todellisen, mallin ohjaaman signaalin mielivaltaisella heuristiikalla. Päättäkää suoritus ensin arvon stop_reason perusteella ja antakaa rajan ottaa kiinni vain poikkeustapaukset.

MAX_ITERS = 20  # safety net, NOT the primary stop
for _ in range(MAX_ITERS):
    response = client.messages.create(...)
    messages.append({"role": "assistant", "content": response.content})
    if response.stop_reason == "end_turn":
        break  # primary: model-driven
    # ... handle tool_use ...
else:
    log.warning("hit iteration cap -- investigate, don't trust as 'done'")

Käsittele muut pysäytyssyyt

Vankka silmukka haarautuu jokaisen pysäytyssyyn perusteella, ei vain onnistuneen suorituksen tapauksessa. Erityisesti max_tokens tarkoittaa, että vastaus katkaistiin — se ei tarkoita valmistumista. Jos käsittelette katkaistun vuoron valmiina, toimitatte huomaamatta puolikkaan vastauksen.

Kun näette arvon max_tokens, ratkaisu on suurentaa max_tokens-arvoa tai siirtyä suurissa tulosteissa suoratoistoon ja jatkaa — älkää koskaan katkaisko silmukkaa kuin tehtävä olisi onnistunut.

if response.stop_reason == "end_turn":
    break
elif response.stop_reason == "tool_use":
    messages.append({"role": "user", "content": run_tools(response.content)})
elif response.stop_reason == "max_tokens":
    # truncated, NOT complete -- raise cap or stream, then continue
    raise OutputTruncated("increase max_tokens or stream")

Tarvitsetteko rakenteisen valmis-lipun? Käyttäkää työkalua

Joskus haluatte aidosti mallin ilmoittavan valmistuessaan rakenteisen lopputuloksen — tilan, luottamuksen tai yhteenvedon. Ratkaisu ei silti ole proosan tulkitseminen. Antakaa Claudelle työkalu (tai JSON Schema rakenteisten tulosteiden kautta) ja antakaa sen tuottaa tyypitetty tulos.

Arvolla tool_choice: "any" voitte pakottaa mallin kutsumaan jotakin työkalua, jolloin rakenteinen tuloste on taattu vapaan tekstin sijaan. Silmukka päättyy silti arvon stop_reason perusteella; työkalu vain välittää koneellisesti luettavan arvion. Rakenne korvaa merkkijonotäsmäytyksen kaikkialla, missä sillä on merkitystä.

tools = [{
    "name": "submit_result",
    "description": "Report the final task outcome.",
    "input_schema": {
        "type": "object",
        "properties": {
            "status": {"type": "string", "enum": ["success", "failed"]},
            "summary": {"type": "string"},
        },
        "required": ["status", "summary"],
    },
}]
# tool_choice={"type": "any"} forces a structured call, not prose

Pikatarkistus

Testatkaa arviointikykyänne realistisessa suunnittelupäätöksessä.

Vastaa interaktiivisessa oppitunnissa

Tärkeimmät opit

Tiedätte nyt, miksi tulosteen etsiminen valmistumisen havaitsemiseksi on väärä työkalu tähän tehtävään:

Päättäkää suoritus arvon stop_reason perusteella, älkää koskaan tekstin perusteella. end_turn = valmis; tool_use = suorita työkalut ja jatka.
Tekstin läpikäynti on hauras molempiin suuntiin — se ei havaitse todellista valmistumista (vaihteleva muotoilu) ja tuottaa vääriä positiivisia tuloksia (sanan "done" keskustelunomainen käyttö).
API on tilaton ja mallin ohjaama. Lähettäkää koko historia jokaisella vuorolla ja antakaa rakenteisen signaalin, ei proosan, ohjata silmukkaa.
Iteraatiorajat ovat turvaverkko, eivät ensisijainen pysäytys. Käsitelkää max_tokens katkaisuna, älkää onnistumisena.
Tarvitsetteko rakenteisen lopputuloksen? Käyttäkää työkalua tai JSON Schemaa (pakottakaa se arvolla tool_choice: "any") — älkää koskaan tulkitko vapaata tekstiä.

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 ”Vastaesimerkki: tekstin jäsentäminen valmistumisen tunnistamiseksi” ilmainen?

Kyllä — voit lukea täällä verkossa kokonaan ilmaiseksi mitkä tahansa Claude Architect-oppimispolun 3 oppituntia, myös oppitunnin “Vastaesimerkki: tekstin jäsentäminen valmistumisen tunnistamiseksi”. 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 ”Vastaesimerkki: tekstin jäsentäminen valmistumisen tunnistamiseksi”?

Miksi tulosteen etsiminen 'done'-sanan varalta on hauraalla pohjalla ja väärin. 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 ”Vastaesimerkki: tekstin jäsentäminen valmistumisen tunnistamiseksi”-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

Ydinsilmukka
Lopettaminen stop_reasonin perusteella
Vastaesimerkki: tekstin jäsentäminen valmistumisen tunnistamiseksi
Vastaesimerkki: mielivaltaiset iteraatiorajat

← Takaisin: Claude Architect