Skip to content

Agent harness: miért akad el az AI Agent?

Mi az az agent harness, és miért ezen múlik az AI Agent viselkedése? Eszközök, agent loop, hibakezelés, ciklusfigyelés és egy minimális Python harness.

2026. 11. 19. 10 perc olvasás

Egy eszközöket használó AI Agent-ben a nyelvi modell választja ki a következő lépést. A fájlolvasást, a parancsfuttatást vagy az adatbázisba írást a köré épített kód, az agent harness végzi el.

Ha az első teszteken jól működő AI Agent egy valódi feladatnál ugyanazt a sikertelen javítást ismétli, vagy ellenőrzés nélkül késznek mondja a munkát, kézenfekvő lehet a modellcsere. Előbb azonban érdemes megvizsgálni a harness-t: ez szabályozza azt is, milyen visszajelzést kap a modell egy sikertelen lépés után.

Mi az az agent harness, és hol ér véget a modell?

Az eszközhasználat lépéseiben jól látszik a modell és a harness közötti munkamegosztás. A modell köré épített harness az a réteg, amely:

  • eszközöket (például fájlolvasást vagy webes keresést) ad neki a leírásukkal együtt,
  • meghatározza, milyen formában kérheti a használatukat,
  • felismeri a kérést, és ténylegesen végrehajtja,
  • és visszajuttatja hozzá az eredményt.
Központi választóegység köré épített gépkeret mechanikus karja dokumentumot húz egy olvasóba.

A harness azonban az eszközhasználatnál tágabb: a modellen kívül minden kód, beállítás és végrehajtási logika ide tartozik. Főbb részei:

  • a rendszerprompt, vagyis a modell állandó alaputasítása,
  • az eszközök és a leírásuk,
  • a sandbox, vagyis az elkülönített futtatókörnyezet,
  • a fájlrendszer,
  • a lépések összehangolása,
  • és a működés egyes pontjain lefutó hook-ok és middleware-ek.

A harness módosításával tehát a modell cseréje nélkül is változhat az AI Agent teljesítménye.

Ugyanaz a modell, más harness: mit mutatnak a mérések?

A LangChain a saját, programkódot író AI Agent-jével végzett kísérletet.

Az eredménye a parancsfuttatási fejlesztői feladatokból álló Terminal Bench 2.0 tesztsoron 52,8 százalékról 66,5 százalékra javult, és a ranglistán a Top 30-on kívülről a Top 5-be került.

A modell végig ugyanaz a gpt-5.2-codex maradt, csak a rendszerprompt, az eszközök és a middleware-ek változtak.

Ha különböző harness-eket hasonlítunk össze, a szórás még nagyobb. Daniel Vaughan blogbejegyzésében a Terminal Bench 2.0 ranglistájának adatait idézi:

ezek szerint a Claude Opus 4.6 a Claude Code kódolóalkalmazásban 58,0 százalékot ért el, más harness-ekben pedig 69,9 és 81,8 százalék között teljesített.

Négy eltérő tesztpanelen ugyanaz a chip, mögöttük különböző magasságig világító LED-oszlopok

Ha az AI Agent elakad, hibázik vagy ugyanazt a sikertelen lépést ismételgeti…

akkor érdemes megvizsgálni a modell körüli keretet: az eszközöket, a ciklust, a hibakezelést és a leállási feltételeket.

A ranglisták értelmezésénél a mérés bizonytalansága és a modell szerepe is számít. Egy LessWrong-elemzés szerint a kevés feladat miatt a szomszédos ranglistahelyek közötti különbség 25 párból 24-ben lényegében a véletlen műve, a Gemini 3 Pro eredménye pedig alig változott, amikor másik harness-ben futott.

A LangChain szerint a Claude Code és a Codex modelljeit ráadásul a hozzájuk tartozó végrehajtási kerettel együtt tanítják tovább, így a modell rá is tanulhat egy adott keretre.

A kérdésre, hogy melyik harness-t érdemes választani, ezért a saját feladatodon végzett mérés ad választ, a ranglista ehhez legfeljebb kiindulópont. Hogy mit érdemes mérni és hangolni, az a harness felépítéséből derül ki.

Hogyan működik egy agent harness?

Az agent loop az a ciklus, amelyben a modell eszközhívást kér, a harness végrehajtja, majd visszaküldi az eredményt. A modell ennek alapján választja ki a következő lépést.

A Claude API-ban minden eszközhívás saját azonosítót kap, így a harness a megfelelő kéréshez kapcsolva küldi vissza az eredményt.

A ciklus végleges válasznál lezárul, a harness-ben beállított korlát pedig akkor is megszakíthatja, ha a modell tovább dolgozna.

Eszközök: gyakran a kevesebb a jobb

A Vercel adatelemző AI Agent-jének eszközkészletét 17 eszközről kettőre, bash-re és SQL-re szűkítették. Ugyanazzal a modellel 3,5-szer gyorsabb futást és 37 százalékkal kisebb tokenhasználatot mértek. A mérés mindössze öt tesztkérdésre épült, ezért saját feladatsoron érdemes ellenőrizni, segít-e az eszközkészlet szűkítése.

Az eszközök száma mellett a leírásuk is számít: ebből választja ki a modell, melyiket hívja meg és milyen paraméterekkel. Az Anthropic útmutatója ezért részletes eszközleírást javasol, és azt, hogy az eszközök a feladathoz szükséges adatokat adják vissza.

Hibakezelés és leállás: mindkettő a harness döntése

A javítható eszközhibát a harness visszaküldheti a modellnek, hogy az újabb lépést választhasson. A Claude API-ban a harness külön jelzi a modellnek, hogy az eszközhívás hibával végződött.

Üvegtáblára rajzolt agent loop: piros hibanyíl tér vissza a döntési ponthoz, egy kéz új ágat rajzol

A hibaüzenet mondja meg, mi történt, és mi lehet a következő lépés: „Túl sok kérés érkezett, 60 másodperc múlva próbáld újra.”

A futásnak legyen felső korlátja is: a Claude Agent SDK-ban beállítható a körök maximális száma. Nyitott feladatnál költségkorlátot is érdemes megadni, hogy a futás a rendelkezésre álló keret elérésekor leálljon.

Amikor az AI Agent körbe jár

Az ismétlésfigyelés már a lépéskorlát elérése előtt jelezheti, hogy az AI Agent ugyanazt a sikertelen megoldást próbálja újra. Két nyílt forrású megoldás eltérő szabályokkal figyeli az elakadást:

  • az OpenHands például négy azonos akció-eredmény párnál vagy három azonos, hibával végződő akciónál jelez,
  • a Gemini CLI pedig öt ismétlődő eszközhívásnál.

Saját harness-ben az eszköz nevét és a paramétereit is figyelheted: ismétlődéskor először figyelmeztetést küldhetsz, tartós elakadásnál pedig leállíthatod a futást.

Az első jelzés azért figyelmeztetés, mert a felismerés tévedhet, és egy szándékos ismétlést is beragadásnak nézhet.

Négy egyforma papírlap az asztalon, a negyediket egy kéz piros csipesszel fogja le.

Hosszú futás: kontextus és állapot

Hosszabb futásnál azt is kezelni kell, milyen előzményeket kap meg a modell, és hol marad meg az elvégzett munka állapota.

A Chroma kutatói 18 modellen vizsgálták, hogyan változik a teljesítmény a bemenet hosszával: azonos nehézségű feladatnál is tapasztaltak romlást.

Ez indokolja az előzmények tömörítését és a rövid, releváns eszközválaszokat.

Az Anthropic hosszú futású AI Agent-jeinél a túl korai befejezés ellen funkciónként rögzítették, mi készült el és mi vár még ellenőrzésre. A folytatást haladási napló és git commit-ok segítették.

A harness engineering ennek a teljes végrehajtási keretnek a tervezése és méréssel követett javítása, az eszközhasználattól az állapot megőrzéséig.

Egy minimális agent harness felépítése

Az eddig külön-külön bemutatott elemek egy kis Python harness-ben állnak össze: az eszközleírás, a ciklus, a hibavisszajelzés, az ismétlésfigyelés és a lépéskorlát. Ha egy fájlolvasási feladaton végigköveted a működését, az is látszik, melyik tünetnél a harness melyik részéhez érdemes nyúlni.

A kód négy részből áll:

  • beállítások: a használt modell, a lépéskorlát és az ismétlési küszöb,
  • eszközleírás és bemeneti séma: a fájlolvasó eszköz szöveges fájlt olvas, és abszolút útvonalat vár,
  • végrehajtó függvény: ellenőrzi az útvonalat, majd beolvassa a fájlt,
  • és a ciklus: meghívja a modellt, végrehajtja az eszközhívást, majd visszaküldi az eredményt vagy a hibát.

Az ismétlésfigyeléshez egy számláló tárolhatja, hányszor érkezett ugyanaz a hívás ugyanazzal a bemenettel. A példában három azonos hívást engedünk, a negyedik kérésre már új megközelítést kérő hibaüzenet érkezik.

Egy beállítófájl összefoglalásához a modell először fájlolvasást kérhet. Relatív útvonalnál a harness jelzi, hogy abszolút útvonal szükséges. A javított hívásra a modell visszakapja a fájl tartalmát. Amikor már nincs szüksége újabb eszközre, megírja az összefoglalót, és a ciklus véget ér.

Hol avatkozz be, ha valami nem működik?

Mivel minden jellemző tünet a harness egy-egy részéhez köthető, a hibakeresést is érdemes a tünetből indítani:

  • rossz eszközválasztásnál nézd át a leírást és az eszközkészletet,
  • ismétlődő hibánál ellenőrizd, használható visszajelzést kap-e a modell,
  • körbejárásnál vizsgáld meg az ismétlésfigyelést és a leállási korlátokat,
  • túl korai befejezésnél pedig iktass be eredményellenőrzést.
AI Agent futási naplójának nyomata három megjelölt hibaszakasszal, egy kéz jelölőfület ragaszt a csonka végére

Ami szándékosan kimaradt a példából

A bemutatott fájlolvasási példa a ciklust, az eszközhívást, a hibakezelést és a leállást mutatja meg, ezért három elem kimaradt belőle.

Ezekre egy rövid, egyetlen fájlt olvasó feladatnál még nincs szükség, egy hosszabb vagy éles futásnál viszont már igen:

  • a kontextustömörítés, mert néhány lépés alatt az előzmények nem nőnek akkorára, hogy a hosszú bemenet okozta romlás számítson,
  • a félbeszakadt modellválaszok külön kezelése, például amikor a válasz a beállított kimeneti tokenkorlát miatt megszakad, és a ciklusnak a folytatásról kell gondoskodnia,
  • és a sandbox, mert a példa egyetlen eszköze csak fájlt olvas, parancsot nem futtat, és semmit nem módosít.

A hozzáférések korlátozásáról az AI security: mikor kell elzárni az AI Agent-et az internettől? cikkben olvashatsz.

AI Agent-fejlesztés Pythonban, mentorral

Az AI Agent-ek és multi-agent rendszerek fejlesztése képzésünkön alkalmazásépítés közben vizsgálod az eszközhasználatot, a ciklusvédelmet és a kimenet minőségét. A hét hét alatt heti 8-12 óra tanulással számolhatsz.

Az eszközhasználattól a kiértékelésig ezekkel dolgozol:

  • LangChain-nel eszközöket használó AI Agent-et építesz, sémaellenőrzéssel és ciklusvédelemmel, a hibákat pedig visszajuttatod az AI Agent-hez,
  • LangGraph-fal több AI Agent munkáját hangolod össze, és kezeled a felhalmozódó kontextust,
  • és Langfuse-zal nyomon követed a futásokat, és kiértékeled a kimenetet ellenőrzött referencia-adathalmazzal, valamint LLM-as-judge módszerrel, vagyis nyelvi modellre bízott bírálattal.

Az AI Agent-ek és multi-agent rendszerek fejlesztése képzésünk saját projektjében egy bemutatott alkalmazást fejlesztesz tovább, amely visszakeresett dokumentumokkal támogatja a válaszadást (RAG), és AI Agent-eket használ.

Boros Gerzson Dávid AI Architect visszajelez a feladataidra, és élő konzultációkon segít feldolgozni az elakadásokat.

Az AI Agent-ek és multi-agent rendszerek fejlesztése képzésünk előfeltételei:

Ha a csapatban több fejlesztő is AI Agent-eken dolgozik, az AI Agent-ek és multi-agent rendszerek fejlesztése képzésünket a vezetődnek is megmutathatod: az adatlapon céges érdeklődésre is van lehetőség.

A lényeg röviden

  • Az AI Agent működését a modell és a köré épített harness együtt határozza meg.
  • Az eszközleírás, a hibavisszajelzés és a leállási feltételek külön-külön is javíthatók.
  • A változtatás hatását saját feladatsoron érdemes mérni.

Gyakori kérdések

Mi az az agent harness?

Az agent harness a nyelvi modell köré épített kód és konfiguráció, amely végrehajtajtja az eszközhívásokat, vezérli a futást és kezeli a kontextust. A modell választja ki a következő lépést, a harness pedig elvégzi a kért műveletet, és visszaadja az eredményt. A működését ezért modellcsere nélkül is javíthatod.

Miért kerül végtelen ciklusba az AI Agent, és hogyan állítható meg?

Az AI Agent akkor ragadhat ismétlődő ciklusba, ha a hibák után sem vált megközelítést, a harness pedig nem szakítja meg a sikertelen próbálkozásokat. Figyeld az ismétlődő eszközhívásokat és eredményeket, majd küldj új megközelítést kérő visszajelzést. Állíts be lépéskorlátot és költségkorlátot is, hogy az elakadt futás biztosan véget érjen.

Mi az az agent loop?

Az agent loop az a ciklus, amelyben a modell eszközhívást kér, a harness végrehajtja, majd visszaküldi az eredményt a modellnek. A modell a kapott visszajelzés alapján választja ki a következő lépést. A ciklus végleges válasznál vagy a harness leállási feltételének teljesülésekor ér véget.

Hogyan kezeljem a hibát egy AI Agent ciklusán belül úgy, hogy a futás ne álljon le?

A javítható eszközhibát a harness hibajelzéssel ellátott eszközeredményként küldje vissza a modellnek, hogy az új lépést választhasson. A hibaüzenetben mondd meg, mi történt, és hogyan javítható a hívás, például hogy relatív helyett abszolút fájlútvonal szükséges. Az újrapróbálkozásoknak szabj felső korlátot, hogy a hibakezelés ne vezessen végtelen ciklushoz.

Miért hibázik az AI Agent, amikor egy saját eszközt kellene meghívnia?

A saját eszköz meghívását pontatlan eszközleírás, hibás paraméterezés vagy a végrehajtás közben fellépő hiba is meghiúsíthatja. Ellenőrizd, hogy a leírásból kiderül-e, mikor használható az eszköz, milyen bemenetet vár, és milyen korlátai vannak. A harness ellenőrizze a paramétereket, és a hibát javítást segítő visszajelzésként adja vissza a modellnek.

Hogyan adhatok saját eszközt egy AI Agent-nek, például adatbázisba mentéshez?

Saját eszközt úgy adhatsz egy AI Agent-nek, hogy megírod a műveletet végző függvényt, és megadod a modellnek az eszköz nevét, leírását és bemeneti sémáját. Adatbázisba mentésnél a függvény hajtja végre az írást, a modell az eszközhívást és annak paramétereit kéri. A harness ellenőrizze a bemenetet, futtassa a függvényt, majd küldje vissza az eredményt vagy a hibát.

Hogyan győződhetek meg róla, hogy az AI Agent által írt kód tényleg működik?

Az AI Agent által írt kód működését a feladat követelményeihez igazított tesztekkel és futtatással ellenőrizheted. A harness a befejezés előtt kérjen ellenőrzést, és juttassa vissza a hibákat a modellnek javításra. A sikerjelzést az ellenőrzések eredményéhez kösd, mert az AI Agent önmagában túl korán is késznek nyilváníthatja a munkát.

Hogyan maradjon meg a kontextus, amikor az AI Agent eszközt választ, és visszakérdez?

A kontextus megőrzéséhez a harness adja át a következő modellhívásnak a releváns beszélgetési előzményeket, az eszközhívásokat és a hozzájuk tartozó eredményeket. Hosszabb futásnál a régebbi előzményeket tömörítheted, a feladat állapotát és az ellenőrzésre váró lépéseket pedig tartós haladási naplóban rögzítheted. Így a folytatás a megőrzött állapotra is támaszkodhat.

Tetszett? Oszd meg!

Segíts másoknak is megtalálni ezt a cikket.