Claude Architect · Oppitunti

Silmukka- ja orkestrointivastaesimerkit

Tekstin jäsentämiseen perustuva lopetus, mielivaltaiset rajat ja liian kapea hajotus.

Oppitunti 1/413 vaihetta

Silmukka- ja orkestrointivastaesimerkit on ilmainen Claude Architect-oppitunti CoddyKitissä. Tämä on oppitunti 1/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 silmukat menevät pieleen

Agenttisilmukka on petollisen yksinkertainen: lähettäkää pyyntö, tarkistakaa stop_reason, suorittakaa tarvittavat työkalut, lisätkää tulokset historiaan ja toistakaa, kunnes arvo on end_turn. Silti juuri tässä tuotantoagentit epäonnistuvat useimmin.

Tässä oppitunnissa eritellään kolme orkestroinnin anti-patternia, jotka toistuvat Claude Certified Architect -kokeessa:

Lopettaminen tekstiä jäsentämällä — lopettaminen, kun vastauksessa esiintyy sana kuten ”done”.
Satunnaiset iteraatiorajat, joita käytetään ensisijaisena pysäytysmekanismina.
Liian hienojakoinen hajauttaminen — työn pilkkominen niin pieniin osiin, että laatu ja koordinointi romahtavat.

Esittelyssä jokainen näyttää järkevältä ja todellisessa liikenteessä jokainen hajoaa. Tehdään oikeista toimintamalleista automaattisia.

Silmukan sopimus

Claude ei säilytä tilaa palvelinpuolella. Lähetätte koko messages-historian uudelleen jokaisella vuorolla. Malli ilmaisee ohjelman kulun stop_reason-kentän kautta, ei proosatekstin avulla.

Neljä lopetussyytä, joiden perusteella orkestroitte:

end_turn — tehtävä on valmis; poistukaa silmukasta.
tool_use — suorittakaa pyydetyt työkalut, lisätkää tulokset ja jatkakaa.
max_tokens — tuloste katkaistiin.
stop_sequence — määritetty sarja tuotettiin.

Sopimus on rakenteinen. Haarautukaa sen kentän perusteella, jonka API takaa, älkää koskaan sen tekstin perusteella, jonka malli sattuu tuottamaan.

import anthropic

client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Audit the repo and summarize risks."}]

while True:
    resp = client.messages.create(
        model="claude-opus-4-1",
        max_tokens=2048,
        tools=tools,
        messages=messages,
    )
    if resp.stop_reason == "end_turn":
        break
    # ... handle tool_use, append results, loop ...

Anti-pattern 1: tekstin jäsentäminen sanan ”Done” löytämiseksi

Yleisin lopetusvirhe: avustajan tekstin skannaaminen valmistumissignaalin löytämiseksi.

Tämä epäonnistuu tavoilla, joita on vaikea selvittää:

Malli kirjoittaa "En ole vielä valmis" — osajonohaku sanalle "valmis" laukeaa silti ja suoritus päättyy liian aikaisin.
Malli saa työnsä valmiiksi, mutta ilmaisee sen muodossa "tämä viimeistelee analyysin" — tarkistus ei koskaan löydä osumaa ja silmukka jatkaa pyörimistään.
Työkalun tuloksessa lainataan sanaa "valmis" — seurauksena on virheellinen lopetus.

Luonnollinen kieli on todennäköisyyspohjaista, mutta ohjausvuon on oltava deterministinen. stop_reason-kenttä on olemassa juuri siksi, ettei valmistumista tarvitse koskaan päätellä proosasta.

# ANTI-PATTERN — do NOT do this
text = resp.content[0].text.lower()
if "done" in text or "finished" in text:
    break  # brittle: false positives + missed completions

Oikea lopetustapa

Lopettakaa, kun stop_reason == "end_turn". Kun arvo on tool_use, suorittakaa kaikki pyydetyt työkalut, lisätkää tulokset tool_result-viestinä ja jatkakaa. Malli ilmoittaa valmistumisestaan lähettämällä arvon end_turn — Teidän tarvitsee vain noudattaa tätä signaalia.

Näin päätös pysyy siellä, minne se kuuluukin: mallin ohjaamana. Mallilla on valmistumisen arviointiin tarvittava kokonaiskonteksti; orkestrointikehikko vain välittää rakenteisen signaalin.

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

    if resp.stop_reason == "end_turn":
        break

    if resp.stop_reason == "tool_use":
        results = run_requested_tools(resp.content)
        messages.append({"role": "user", "content": results})

Anti-pattern 2: yläraja ensisijaisena lopetusehtona

Seuraava sudenkuoppa on iteraatioiden ylärajan käsitteleminen lopetustapana. Kirjoitatte for _ in range(5) ja kutsutte sitä orkestroinniksi.

Ongelma on tarkoituksessa. Kun yläraja on ensisijainen lopetusehto:

Tehtävät, jotka tarvitsevat perustellusti 7 työkalukutsua, katkaistaan huomaamatta kesken tutkimuksen.
Tehtävät, jotka valmistuvat kahdella kutsulla, näyttävät telemetriassa silti "ylärajaan päättyneiltä", mikä peittää todellisen toiminnan.
Teillä ei ole signaalia, joka erottaisi valmistuneen tehtävän budjetin loppumisesta.

Mallin end_turn-arvon on säilyttävä päätöskohtana. Yläraja on jotakin aivan muuta.

# ANTI-PATTERN — cap IS the stop mechanism
for _ in range(5):
    resp = client.messages.create(...)
    run_tools(resp)
# loop exits by exhaustion, not because the task is done

Yläraja turvaverkkona

Iteraatioiden ylärajat ovat perusteltuja — mutta ainoastaan turvaverkkona hallitsemattomien silmukoiden varalta, eivät koskaan ensisijaisena lopetuslogiikkana. Faktalehden perusohje kuuluu: päätökset ohjaa malli; varatkaa kova koodi takuiden toteuttamiseen.

Yläraja siis ympäröi mallin ohjaamaa silmukkaa. Normaalisti poistutaan arvolla end_turn. Yläraja laukeaa vain poikkeustapauksessa, ja silloin sitä on käsiteltävä lokiin kirjattavana ja eskaloitavana virhetilanteena — ei normaalina lopetuksena.

MAX_ITERS = 25  # safety net, not the plan
for i in range(MAX_ITERS):
    resp = client.messages.create(...)
    messages.append({"role": "assistant", "content": resp.content})
    if resp.stop_reason == "end_turn":
        break          # normal, model-driven exit
    handle_tools(resp)
else:
    log.error("hit safety cap without end_turn")
    escalate(messages)  # treat as anomaly, not success

Milloin takuut kuuluvat koodiin

"Mallin ohjaama" ei tarkoita, ettei kovaa koodia pitäisi koskaan käyttää. Varatkaa deterministinen koodi aidoille takuille — tilanteisiin, joissa todennäköisyyspohjainen päätös ei ole hyväksyttävä.

Esimerkkejä kokeen anti-pattern-luettelosta:

Hook, joka estää yli 500 dollarin hyvityksen — deterministinen valvonta on lähes 100-prosenttisen luotettava, kun taas kehotteen luotettavuus on noin 90 prosenttia.
Ohjelmallinen esiehto: estetään process_refund, kunnes get_customer on palauttanut vahvistetun tunnisteen.

Raja on selvä: ohjatkaa avoimet päätökset mallille ja koodatkaa käytännöt ja turvallisuus koodiin. Ylärajat kuuluvat jälkimmäiseen vain varmistavana suojana.

Anti-pattern 3: liian kapea hajautus

Multi-agent-järjestelmät noudattavat hub-and-spoke-rakennetta: koordinaattori hajottaa tehtävän, delegoi, kokoaa tulokset, reitittää ja käsittelee virheet. Tässä orkestrointivirheessä työ pilkotaan liian pieniin osiin.

Liian kapea hajautus käynnistää aliagentin jokaista vähäpätöistä vaihetta varten. Kustannukset kasaantuvat:

Koordinoinnin kustannukset ylittävät varsinaisen työn moninkertaisesti.
Kukin aliagentti menettää kontekstin — aliagentit eivät peri koordinaattorin keskusteluhistoriaa.
Kokonaiskuvaa edellyttävä, eri osa-alueet yhdistävä harkinta pirstoutuu erillisten agenttien kesken.

Hajottakaa tehtävä merkityksellisiin työyksiköihin, ei yksittäisiin operaatioihin.

Konteksti on välitettävä nimenomaisesti

Koska aliagentit aloittavat tyhjästä historiasta, koordinaattorin on välitettävä kaikki tarvittava konteksti nimenomaisesti jokaisessa aliagentin kehotteessa. Liian kapea hajautus pahentaa tilannetta: mitä enemmän agentteja on, sitä enemmän syntyy rajoja, joissa konteksti voi kadota, ja sitä enemmän kehotteita on pidettävä synkronoituna.

Huomioikaa myös, että useat Task-kutsut yhdessä vastauksessa suoritetaan rinnakkain ja koordinaattorin allowedTools-luettelon on sisällettävä "Task". Rinnakkaisuus on syy hajottaa tehtävä oikean tarkkuustason mukaan — toisistaan riippumattomiksi, itsenäisiksi yksiköiksi — ei hajottaa yhtä yhtenäistä tehtävää palasiksi, joihin kuhunkin on lisättävä sama jaettu konteksti uudelleen.

AgentDefinition(
    name="file_reviewer",
    description="Reviews a single source file for local correctness issues.",
    system_prompt=(
        "You review ONE file in isolation.\n"
        # subagent has NO coordinator history — pass everything it needs:
        "Project conventions: {conventions}\n"
        "File under review: {file_path}\n"
        "Known constraints: {constraints}\n"
    ),
    allowed_tools=["Read", "Grep"],  # least privilege
)

Oikea tarkkuustaso: koodikatselmointi

Koodikatselmointi on klassinen esimerkki oikeaoppisesta hajautuksesta — ja se osoittaa eron liian kapeaan pilkkomiseen.

Oikea rakenne on tiedostokohtainen paikallinen katselmointi, jota seuraa erillinen tiedostojen välinen integrointikatselmointi. Yhdellä kertaa tehtävä monen tiedoston katselmointi hajauttaa huomion; kaikki langat käsissään pitävä yksi agentti jättää huomaamatta sekä paikalliset virheet että integraatio-ongelmat.

Väärä, liian kapea ääripää on vastakkainen virhe: aliagentti jokaista funktiota tai riviä varten, jolloin mikään niistä ei näe riittävästi oikeellisuuden arviointiin. Hajottakaa työ katselmointivaiheisiin, joilla kullakin on yhtenäinen laajuus — ensin tiedostotaso, sitten integraatiotaso — älkääkä pilkkoko sitä harkinnan mahdollistavaa tasoa pienemmiksi palasiksi.

Kiinteä ja mukautuva hajautus

Yksi lisäkeino ehkäisee sekä liian laajaa että liian kapeaa hajautusta: sovittakaa strategia ongelman rakenteeseen.

Kiinteät putket / kehoteketjutus tunnettuihin, peräkkäisiin vaiheisiin — poimikaa, validoikaa ja muotoilkaa.
Mukautuva hajautus avoimiin tutkimuksiin, joissa seuraava vaihe riippuu juuri löydetystä tiedosta.

Kiinteän putken pakottaminen avoimeen tutkimustehtävään johtaa helposti hauraisiin, liian kapeisiin vaiheisiin; mukautuvan hajautuksen käyttäminen deterministiseen kolmivaiheiseen muunnokseen lisää tarpeetonta koordinointia. Valitkaa tietoisesti ja antakaa mallin ohjata ne vaiheet, joista sen kuuluu vastata, samalla kun koodi vastaa vaiheista, joiden on oltava taattuja.

Pikatarkistus: silmukan lopetus

Arkkitehdin agenttisilmukka kutsuu työkaluja useiden vuorojen aikana. Valitkaa orkestrointi, joka vastaa sertifioinnin luotettavuusohjeita.

Vastaa interaktiivisessa oppitunnissa

Kertaus: orkestroikaa signaalien perusteella ja hajottakaa tarkoituksellisesti

Kolme toimintaperiaatetta, jotka kannattaa muistaa kokeessa ja tuotannossa:

Lopettakaa stop_reason-arvon perusteella. Poistukaa arvolla end_turn; älkää koskaan jäsentäkö tekstiä sanan "done" löytämiseksi. Malli vastaa valmistumispäätöksestä, ja Te välitätte sen rakenteisen signaalin.
Yläraja on turvaverkko, ei suunnitelma. Pitäkää yläraja riittävän suurena hallitsemattomien silmukoiden havaitsemiseksi, käsitelkää sen saavuttaminen poikkeamana ja varatkaa kova koodi todellisille takuille (hookit, esiehdot).
Hajottakaa työ oikean tarkkuustason mukaan. Käyttäkää hub-and-spoke-rakennetta ja yhtenäisiä yksiköitä — ensin tiedostokohtaiset ja sitten tiedostojen väliset vaiheet, ei aliagenttia jokaista riviä varten. Välittäkää kaikki konteksti nimenomaisesti ja sovittakaa kiinteä tai mukautuva strategia ongelmaan.

Kun nämä kolme asiaa ovat kunnossa, useimmat kokeen silmukoita ja orkestrointia koskevat harhautukset on helppo karsia.

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 ”Silmukka- ja orkestrointivastaesimerkit” ilmainen?

Kyllä — voit lukea täällä verkossa kokonaan ilmaiseksi mitkä tahansa Claude Architect-oppimispolun 3 oppituntia, myös oppitunnin “Silmukka- ja orkestrointivastaesimerkit”. 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 ”Silmukka- ja orkestrointivastaesimerkit”?

Tekstin jäsentämiseen perustuva lopetus, mielivaltaiset rajat ja liian kapea hajotus. 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 1/4.

Kuinka kauan ”Silmukka- ja orkestrointivastaesimerkit”-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

← Takaisin: Claude Architect