Az ügynökhurok magyarázata: hogyan futnak a kódoló ügynökök, és hogyan állítjuk meg őket

Az ügynökhurok minden MI-ügynökben megtalálható vezérlőhurok: a modell elolvassa a saját kontextusát, eszközhívást kér, a kódod lefuttatja az eszközt és hozzáfűzi az eredményt, majd a modellt újra meghívják. Ez addig ismétlődik, amíg egy leállási feltétel le nem zárja a futást. A kódoló ügynökök, a kutatási ügynökök és a support botok ugyanezt használják. Amitől egy hasznos ügynök nem lesz drága, az elsősorban az, hogyan ellenőrzi a hurok a saját munkáját, és mikor áll meg.

Ez a cikk végigmegy a hurkon a kódban, a leállási feltételeken és a kereteken, amelyeket érdemes kikényszeríteni, azon, miért a tesztek az ügynökhurok igazságértékei, és az ezekre épülő külső hurkokon: Geoffrey Huntley „Ralph” technikáján és a Claude Code /loop és /goal parancsain. A végén hibaformák és egy ellenőrzőlista következik.

Mi az ügynökhurok?

Az ügynökhurok egy olyan modell, amely újra és újra meghívja az eszközeit, minden eredményből eldönti a következő lépést, addig, amíg úgy nem dönt, hogy kész van, vagy amíg valami meg nem állítja. Az Anthropic „Building effective agents” cikke (2024. december) így írja le az ügynököket: „környezeti visszajelzésre épülő eszközhívásokat ismételnek egy hurokban”, és elválasztja őket a munkafolyamatoktól, amelyekben „az LLM-eket és az eszközöket előre definiált kódutak szervezik”. Egy ügynökben a modell maga irányítja a folyamatát, egy munkafolyamatban a kódod.

Az ötlet régebbi, mint a mai kódoló ügynökök. A Yao et al. ReAct-papírja („ReAct: Synergizing Reasoning and Acting in Language Models”, 2022) azt tanította a modelleknek, hogy „gondolatmenet-nyomokat és feladatspecifikus műveleteket váltakozva” generáljanak: gondolkodni, cselekedni, megfigyelni, megint gondolkodni. Az interaktív ALFWorld és WebShop benchmarkokon egy-két in-context példával 34, illetve 10 abszolút százalékponttal verte az utánzási és a megerősítéses tanulás alapvonalait. A modern eszközhívó API-k ezt a promptmintát protokollá alakították: a modell strukturált eszközkérést ad vissza olyan szöveg helyett, amelyet parszolni kellene.

Hogyan működik az ügynökhurok a kódban?

A kódban az ügynökhurok egy while hurok egy API-hívás körül. Minden iteráció elküldi a teljes üzenetelőzményt, és a válasz leállási oka mondja meg, hogy futtassunk-e eszközt és folytassuk, vagy álljunk meg.

A Claude Messages API-nél a szerződés egyértelmű. Ha a modell eszközt akar, a válaszban stop_reason: "tool_use" áll, és egy vagy több tool_use blokk van benne, mindegyik id-vel, eszköz-name-mel és input-tel. A kódod lefuttatja az eszközt, majd visszaküld egy „user” szerepű üzenetet, amely kizárólag tool_result blokkokat tartalmaz, a tool_use_id alapján illesztve. A leállási okokról szóló dokumentáció felsorolja a többi értéket: end_turn (befejeződött), max_tokens, stop_sequence, refusal, model_context_window_exceeded és pause_turn, ami azt jelenti, hogy egy szerveroldali eszközhurok elérte a saját iterációs limitjét (alapértelmezetten 10), és a folytatáshoz vissza kell küldeni a tartalmat.

# Simplified sketch of an agent loop (Claude Messages API, Python SDK)
messages = [{"role": "user", "content": task}]

for turn in range(MAX_TURNS):                        # hard stop 1: iterations
    response = client.messages.create(
        model=MODEL, max_tokens=4096, tools=TOOLS, messages=messages)
    messages.append({"role": "assistant", "content": response.content})

    if response.stop_reason != "tool_use":           # end_turn, max_tokens, refusal ...
        break

    results = []
    for block in response.content:
        if block.type == "tool_use":
            output = run_tool(block.name, block.input)   # your code, your sandbox
            results.append({"type": "tool_result",
                            "tool_use_id": block.id,
                            "content": output})
    messages.append({"role": "user", "content": results})

    if budget.exceeded() or no_progress(messages):    # hard stops 2 and 3
        break

Két részlet fontosabb, mint elsőre látszik. Első: a run_tool hordozza az összes kockázatot: azt futtatja le, amit a modell kért, tehát szűk hatókörű hitelesítő adatokkal ellátott sandboxba kerül (lásd a kódoló ügynökök sandboxolását a CI-ban). Másod: minden eszközeredmény a messages listában marad, a kontextus tehát minden iterációval nő. Egy hosszú hurok minden hívásban kifizeti a teljes előzményét.

Mikor álljon meg egy ügynökhurok?

Egy ügynökhurok akkor álljon meg, ha a feladat bizonyíthatóan kész, és akkor is, ha elfogy egy keret, bármit gondol is a modell. Az Anthropic útmutatása kimondja: „különösen fontos leállási feltételeket (például egy maximális iterációszámot) beépíteni, hogy megőrizzük az uralmat”.

A modell saját end_turn jele a természetes kilépés, de a leggyengébb. Csak azt jelenti, hogy a modell késznek érzi magát. Az alábbi táblázat minden más sora azért létezik, mert ez a hit néha téves, és mert a soha véget nem érő hurok csendben pénzt éget.

Az előrehaladás-figyelés az, amit a csapatok kihagynak, és épp ez menti a legtöbbet. Az előrehaladást valamire kell definiálni, amit a hurok számolni tud: a bukó tesztek számának csökkenésére, lezárt review szálakra, egy zsugorodó teendőlistára. A review-kör skillem a lezárt review szálakat számolja, és három eredménytelen kör után leáll, majd embernek adja át, ahelyett hogy a javítás negyedik variációjával próbálkozna. A szám magától fogva tetszőleges; hogy van ilyen, az nem.

Miért a tesztek az ügynökhurok igazságértékei

A hurok csak valamihoz tudja magát igazítani, amitől nem tud vitatkozni. Kódoló ügynököknél ez egy tesztfutás, egy fordító vagy egy típusellenőrző: a környezet kimenete, nem a modell véleménye a saját munkájáról.

A „Building effective agents” szerint az ügynököknek „minden lépésben igazságértékre van szükségük a környezetből (például eszközhívás eredményére vagy kódfuttatásra)”. A gyakorlatban ez két szabályt jelent. Az ügynök maga futtatja a teszteket, a hurkon belül, és elolvassa a kimenetet. És a teszteknek tudniuk kell bukni. Simon Willison piros/zöld TDD mintája ezt kimondja: „Ha kihagyod ezt a lépést, már zölden átmenő tesztet építhetsz.” Saját szabályom a hibajavításra szigorúbb: a regressziós tesztnek a javítással át kell mennie, és el kell buknia, ha csak a javítást vonjuk vissza. Az a teszt, amely így is, úgy is átmegy, nem ad semmi támpontot a huroknak.

Az Anthropic „Effective harnesses for long-running agents” cikke (2025. november) ugyanezt nagyobb léptékben mutatja: egy JSON-ban futó feature-lista, amelyben minden feature "passes": false értékkel indul, sessionenként egy feature, és az utasítás, hogy „elfogadhatatlan a teszteket törölni vagy szerkeszteni”. Az általuk felsorolt hibaformák pontosan azok, amelyek gyenge ellenőrzésnél várhatók: a projekt túl korai befejezetté nyilvánítása, és a feature-ök end-to-end tesztelés nélküli lezárása. A modellt körülvevő teljes ellenőrző rendszer a harness engineering témája.

Külső hurkok: Ralph, /loop és /goal

A külső hurok magát az ügynökhurokot indítja újra: sessionönkénti friss munkamenetet, egy ütemezést vagy egy minden forduló után ellenőrzött feltételt. Így órák munkát tudsz kivenni abból az ügynökből, amelynek egyetlen futása percek alatt véget ér.

A Ralph technika

Geoffrey Huntley „Ralph” technikája (2025. július) a legkisebb változat. A saját szavával: „Ralph egy bash hurok”:

while :; do cat PROMPT.md | claude-code ; done

Minden iteráció új ügynöksessiont indít ugyanazzal a prompttal. Az állapot nem a kontextusban, hanem a lemezen él: specifikációk és egy fix_plan.md a prioritás szerint rendezett fennmaradó munkával, amelyet az ügynök frissít. A központi szabálya „egy tétel egy hurokban”, mert „minél többet használod a kontextusablakot, annál rosszabb lesz az eredmény”. A minden módosítás után futó tesztek tartják tisztességben a hurkot. A határokról nyíltan szól: greenfield projektekhez illik, egy meglévő kódbázisban nem használná.

Claude Code /loop és /goal

A Claude Code két session szintű külső hurkot szállít. Az ütemezett feladatok dokumentációja szerint a /loop egy beépített skill, amely újrafuttat egy promptot, amíg a session nyitva marad. A /loop 5m check the deploy cron ütemezéssé alakítja az időközt (egységek: s, m, h, d, egyperces pontossággal). Ha van prompt, de nincs időköz, a Claude minden iteráció után egy és egy óra közötti késleltetést választ, és kiírja, hogy miért. Egy csupasz /loop beépített karbantartó promptot futtat: folytasd a befejezetlen munkát, ápold az aktuális ág pull requestjét, majd jönnek a takarító körök. Egy .claude/loop.md vagy ~/.claude/loop.md felülírja ezt az alapértelmezett promptot.

A leállítási szabályok az érdekesek. Az ütemezett promtok csak fordulók között, a session üresjárata közben futnak le. Az Esc megállít egy saját tempójú hurkot, és a Claude maga is befejezheti, ha kész a munka. A rögzített időközű hurkok addig futnak, amíg le nem állítod őket, az ismétlődő feladatok pedig hét nap után lejárnak, ami „korlátozza, meddig futhat egy elfelejtett hurok”. Egy session legfeljebb 50 ütemezett feladatot tart.

A /goal nem órával, hanem feltétellel dolgozik. Minden forduló után egy kicsi, gyors modell ellenőrzi, hogy a feltétel teljesül-e; ha nem, a Claude új fordulót indít. A cél teljesül, ha a feltétel megvan, ha az értékelő lehetetlennek ítéli, vagy ha egy olyan hibába ütközöl, amelyet javítani kell. Ha a Claude néhány fordulóban sorban nem használ eszközt, a Claude Code megállítja a hurkot, és visszaadja a vezérlést. A dokumentáció egyetlen mérhető végállapotot, egy megnevezett ellenőrzést és egy korlátot javasol, például „vagy 20 forduló után állj meg”.

Az alügynökök a hurkok beágyazásának másik módja. Egy orkestrator az Anthropic szavával „dinamikusan felbontja a feladatokat, átadja őket dolgozó LLM-eknek, és összefoglalja az eredményüket”. Minden dolgozó a saját hurkát futtatja a saját kontextusában, és csak egy összefoglalót ad vissza, így a szülő kontextusa kicsi marad. Hogyan mérődik ez le a szabályfájlokkal, a skillekkel és az eszközökkel, azt a kontextuskeret-döntési mátrix tárgyalja.

Mikor ne használj ügynökhurokot, és hogyan bukik el

Ne használj ügynökhurokot, ha már tudod a lépéseket. Egy rögzített munkafolyamat olcsóbb, gyorsabb és könnyebben tesztelhető. Az Anthropic tanácsa az, hogy „többlépéses agentikus rendszert csak akkor vezessünk be, ha az egyszerűbb megoldások már nem elegendők”.

Ha az ügynökhurok a megfelelő eszköz, akkor ezeken a módokon megy félre:

• Végtelen körben járás. Ugyanannak a javításnak az újrapróbálása kis módosításokkal. Az ellenszer egy kemény iterációs limit és az előrehaladás-figyelés, nem egy jobb prompt.
• A kontextus felhízik. Minden eszközeredmény az előzményben marad, és a minőség romlik, ahogy a kontextus nő. Huntley „egy tétel egy hurokban” szabálya és az iterációnkénti friss sessionök közvetlen válasz erre; ugyanúgy az alügynökök és a tömörítés.
• A teszt kijátszása. Ha az egyetlen kiút az, hogy „zöldek a tesztek”, akkor a teszt szerkesztése rövidút a kiúthoz. Tiltsd le az utasításokban, védd ahol lehet a tesztfájlokat, és a teszt diffjét külön nézd át, nem együtt a kód diffjével.
• Túl korai győzelemhirdetés. A modell befejezi a fordulóját, de maradt munka. A készről egy külső ellenőrzés dönt (egy értékelő, egy feature-lista, a CI), nem az ügynök.
• Korlátlan mellékhatások. Azok a hurkok, amelyek pusholnak, deployolnak vagy posztolnak, megismételhetik a visszafordíthatatlan műveletet. Mindent, ami nyilvános vagy visszafordíthatatlan, ember hagy jóvá; a hurok előkészíti.

Ügynökhurok-ellenőrzőlista

1. Döntsd el, kell-e hurok egyáltalán. Ha a lépések ismertek, írj munkafolyamatot.
2. Állíts be kemény limiteket a kódban: maximális iterációk, token- vagy költségkeret és valós idő szerinti időlimit.
3. Definiáld az előrehaladást számmal (bukó tesztek, nyitott szálak, hátra maradó tételek), és állj meg N eredménytelen kör után.
4. Adj igazságértéket a huroknak: tesztek, típusok és linterek, amelyeket az ügynök maga futtat, plusz egy regressziós teszt, amely elbukik, ha a javítást visszavonjuk.
5. Tartsd az állapotot a lemezen, ne csak a kontextusban: egy tervfájl, egy haladási napló, git commitok.
6. Egy tétel iterációnként hosszú futásoknál, friss kontextussal vagy alügynökökkel a felderítéshez.
7. Tedd sandboxba az eszközfuttatót, és adj neki szűk hatókörű, rövid életű hitelesítő adatokat.
8. Adj át embernek, ha a hurok elakad, és minden nyilvános vagy visszafordíthatatlan lépés előtt.

A kódoló ügynököm skilleiben így működik a review-kör, és ugyanez a hurok jelenik meg megint, ha az ügynök által írt pull requestek kezeléséről van szó. Ha a saját csapatodnak tervezel ügynökhurkokat, nézd meg az AI engineering oldalt.

Források

1. Anthropic: Building effective agents (2024. december)
2. Yao et al.: ReAct: Synergizing Reasoning and Acting in Language Models (2022)
3. Claude API dokumentáció: Handling stop reasons
4. Anthropic: Effective harnesses for long-running agents (2025. november)
5. Simon Willison: Red/green TDD (Agentic Engineering Patterns)
6. Geoffrey Huntley: Ralph Wiggum as a "software engineer" (2025. július)
7. Claude Code dokumentáció: Run prompts on a schedule (/loop)
8. Claude Code dokumentáció: Keep Claude working toward a goal (/goal)