Inżynieria pętli dla agentów AI: pięć elementów, cztery kształty oraz budowa w LangGraph
Inżynieria pętli dla agentów AI: pięć części, cztery powszechne kształty, agent badawczy do weryfikacji i ponawiania prób w LangGraph, zabezpieczenia przed awariami oraz sytuacje, gdy nie należy używać pętli.
Źródła: Loop Engineering with Agents
Każdy agent AI już działa w pętli, a prawie nikt specjalnie nie projektuje tej pętli. To rozbieżność odróżnia agenta, który cicho kończy zadanie, od tego, który w ciągu nocy wyczerpuje budżet, będąc przekonanym, że robi postępy. Istnieje nazwa dla praktyki zamknięcia tej rozbieżności: inżynieria pętli.
Strukturalnie nie jest to skomplikowane. Przy każdej kolejności agent zastanawia się, co robić, wykonuje działanie takie jak wywołanie narzędzia lub wyszukiwanie, sprawdza, co otrzymał, i ponownie się zastanawia. Ten cykl rozumowania, działania i obserwacji leży u podstaw narzędzi takich jak Claude Code i Cursor. Przez jakiś czas poszukiwaną umiejętnością była inżynieria promptów, czyli jak jak najlepiej sformułować prośbę. Modele, które potrafią działać, wyszukiwać i czytać własne wyniki, postawiły większe pytanie: co decyduje o następnym kroku agenta i co każe mu przestać?
Inżynieria pętli to nawyk celowego udzielania takiej odpowiedzi. Projektant wybiera cel, kryteria sprawdzania oraz punkt zatrzymania, a następnie tworzy zwięzły system, który formułuje cel tylko raz i pozwala agencie na dalsze iteracje aż do zakończenia zadania. Odpowiedzialność przenosi się z kierowania agencją krok po kroku na tworzenie rozwiązań odpowiadających tym instrukcjom.
To potężna koncepcja, ale właśnie tutaj zaczyna się trudna część. Niedbale zaprojektowane pętle marnują zasoby, nigdy się nie kończą lub przekonują same siebie, że robią postępy. Dobre pętle są oszczędne, zatrzymują się we właściwym momencie i dostarczają wyników, którym można zaufać. Mądrzejszy prompt nie skraca tej odległości – lepsza pętla tak.
Przykłady poniżej wykorzystują LangGraph, ponieważ ułatwia on widzenie struktury pętli, ale nic tutaj nie jest powiązane z konkretnym frameworkiem. Te same zasady obowiązują w przypadku innego frameworku dla agentów lub zwykłego, ręcznie napisanego kodu. Frameworki się zmieniają, a koncepcje pozostają niezmienne.
Pięć elementów pętli agentowej
Zanim zdecydujemy, kiedy pętla jest odpowiednia, przydatne jest poznanie jej składników. Prawie każda pętla agentowa składa się z pięciu elementów.
- Wyzwalacz. Jakiś zdarzenie uruchamia proces, na przykład osoba wpisuje „start”, uruchamia się planer, przychodzi zgłoszenie lub otwierany jest pull request. Bez wyzwalacza agent pozostaje bezczynny.
- Cel, który można sprawdzić. Pętla musi wiedzieć, jak wygląda zakończenie, najlepiej w formie, którą maszyna może potwierdzić. Poprawa aplikacji skłania do niekończącego się działania – trzeba sprawić, by każdy test się udał lub uzyskać odpowiedź, której twierdzenia wszystkie odnoszą się do źródeł, stanowiąc prawdziwą linię mety.
- Narzędzia. Agent musi być w stanie działać, a także obserwować wynik – uruchamiać kod i czytać błędy, albo przeszukiwać internet i analizować wyniki. Jeśli środowisko nigdy nie odpowiada, agent może jedynie zgadywać.
- Stan. To aktualny obraz zadania: dotychczasowe próby, ustalenia, ile rund minęło. Jest to najtrudniejsza część projektowania pętli, ponieważ zbyt duży stan przykrywa użyteczne informacje szumem.
- Zasady zatrzymania. Określają one, w jaki sposób kończy się pętla, a istnieją trzy możliwości. Sukces oznacza osiągnięcie celu. Rezygnacja oznacza wyczerpanie budżetu prób. Przekazanie zadania oznacza, że pętla napotkała coś ryzykownego lub niejasnego i zamiast zgadywać, przekazała je osobie.
Pozostała część dyskusji, dotycząca tego, kiedy stosować pętlę, a kiedy nie oraz jak to robić, odnosi się do tych pięciu zasad.
Kiedy pętla się opłaca
Pętla ma sens wtedy, gdy jedna przechodzenie przez model nie wystarcza, a zadanie naprawdę wymaga od agenta próbowania, sprawdzania i ponownego próbowania. Cztery sygnały wskazują w tym kierunku.
- Wyniki można zweryfikować. To jest najważniejsze. Gdy rezultat można sprawdzić automatycznie – na przykład poprzez sprawdzenie, czy testy przeszły, czy nie, czy odpowiedź odwołuje się do rzeczywistych źródeł, czy payload JSON jest poprawny, czy nie – pętla może wykorzystać tę weryfikację, aby dotrzeć do prawidłowej odpowiedzi. Weryfikacja pełni rolę kierownicy, natomiast pętla bez niej jedynie marnuje zasoby.
- Pierwsza próba często jest błędna, ale nadal korygowalna. Kod, wersje wstępne badań oraz proces oczyszczania nieuporządkowanych danych poprawiają się dzięki powtarzaniu. Agent tworzy coś, zauważa wady i je naprawia.
- Nikt nie wie, ile kroków to zajmie. Problem danego typu może wymagać dziś dwóch kroków, a jutro siedmiu. Sztywny proces nie może się tak dostosowywać, podczas gdy pętla, która kontynuuje działanie aż do osiągnięcia celu, może to robić.
Przykładem może być agent badawczy, który sprawdza własne ustalenia. Tworzy propozycję odpowiedzi, sprawdza, czy źródła potwierdzają każde twierdzenie, a następnie wraca do głębszego zbadania tych słabszych. Kontynuuje ten proces, dopóki odpowiedź nie będzie solidna lub nie zostanie osiągnięty limit. Wszystkie cztery sygnały są obecne, i to właśnie taki agent jest budowany dalej.
Typowe kształty pętli
Większość pętli agentowych to wariacje kilku podstawowych kształtów. Ich rozpoznanie pomaga określić, jaki kształt preferuje dany problem, zanim cokolwiek zostanie połączone.
Generowanie i weryfikacja, czasami nazywane refleksją. W pierwszym etapie tworzony jest wynik, a w drugim sprawdzany jest on, przy czym ten proces powtarza się, dopóki sprawdzenie nie przejdzie pomyślnie. Sygnał kierowniczy ma postać binarną: sprawdzenie może zatwierdzić wynik lub wskazać, co jest nieprawidłowe. Metoda ta nadaje się do sytuacji, w których można sprawdzić poprawność, takich jak kod, który musi przejść testy, lub badania, których twierdzenia wymagają potwierdzenia. To właśnie taka struktura jest ostatecznie tworzona.
+-----------+ +-----------+
-->| Generate |----->| Verify |----- pass -----> [ done ]
+-----------+ +-----+-----+
^ |
+------- fail ------+
Wybierz tę opcję, gdy istnieje obiektywny test poprawności, a agent powinien kontynuować naprawy aż test się powiedzie. Klasycznym przykładem jest agent tworzący zapytania SQL, który uruchamia swoje zapytanie i powtarza je w pętli, aż zostanie ono wy wykonane i zwróci wiarygodne wyniki.
Ewaluator i optymalizator, nazywani także generatorem i oceniaczem. Oceniacz przyznaje punkty za każdą próbę zamiast podawać tylko „tak” lub „nie”, a pętla dąży do jak najwyższej oceny, a nie tylko do poprawności. Jest to przydatne, gdy nie ma jednoznacznego wyniku „udane” lub „nieudane”, ale nadal można zmierzyć poziom doskonałości, np. przy dostosowywaniu promptów, udoskonalaniu tekstów reklamowych lub sortowaniu wyników.
+-----------+ +-----------+
-->| Generate |----->| Score |--- good enough --> [ done ]
+-----------+ +-----+-----+
^ |
+-- improve --------+
(use the score)
Wybierz to wtedy, gdy jakość można zmierzyć na skali, ale nadal da się jej nadać liczbę. Opracowanie hasła reklamowego produktu, przy którym oceniany jest poziom klarowności i wpływu, a pętla doskonali najlepszą propozycję, ilustruje tę koncepcję.
Planuj, realizuj, planuj ponownie. Planista określa kroki, a wykonawcy je realizują, a gdy któryś z kroków ujawni coś nieoczekiwanego, pętla powraca, aby zmodyfikować plan. Pętla otacza cały plan, a nie tylko jeden wynik, dlatego nadaje się do pracy wieloetapowej o otwartym zakończeniu, takiej jak badania lub projekt oprogramowania.
+-----------+ +-----------+
-->| Plan |----->| Execute |-- all steps done --> [ done ]
+-----------+ +-----+-----+
^ |
+-- replan ---------+
(hit a surprise)
Wybierz tę opcję, gdy zadanie składa się z wielu kroków, a nie wszystkie są znane od razu. Przeniesienie usługi do nowego frameworka jest skuteczne: należy zaplanować kroki, rozpocząć ich wykonywanie i ponownie je zaplanować, gdy jeden z kroków ujawni nieoczekiwaną zależność.
Pętla zaplanowana lub monitorująca. Zamiast iterować w kierunku celu podczas jednego uruchomienia, ta wersja jest aktywowana przez zegar lub zdarzenie w celu obserwacji i reakcji – na przykład sortowania nowych zgłoszeń, sprawdzania uszkodzonych kompilacji lub ponownego próbowania niepewnego zadań. Obejmuje określony czas i nie istnieje w ramach pojedynczego zadania.
+-----------+ +-----------+ +-----------+
-->| Wait |---->| Check |---->| Act |---+
| (timer / | +-----------+ +-----------+ |
| trigger) | |
+-----------+ <-------------------------------------+
(no fixed end — keeps watching over time)
Wybierz tę opcję, gdy nie istnieje żadna ostateczna linia mety, a celem jest ciągłe obserwowanie i reagowanie, podobnie jak sprawdzanie skrzynki pocztowej co kilka minut lub cotygodniowe sprawdzanie przestarzałych żądań pull request.
Te schematy nie są wzajemnie wykluczające. W rzeczywistych systemach często się one nakładają, na przykład zaplanowany pętla, która przy każdym uruchomieniu wykonywa etapy generowania i weryfikacji. Najczęściej spotykanym schematem jest ten składający się z kroków generowania i weryfikacji, który zostanie opisany dalej od początku do końca.
Budowanie pętli za pomocą LangGraph
Agentem, który ma zostać stworzony, jest badacz, który nie ufa swojemu pierwszemu szkicowi. Po otrzymaniu pytania zbiera informacje, pisze odpowiedź, a następnie sprawdza każde twierdzenie w odniesieniu do rzeczywistych źródeł. Twierdzenie bez podstaw jest odsyłane z powrotem w celu dalszych badań. Cykl trwa, dopóki odpowiedź nie będzie kompletna lub dopóki nie zostanie osiągnięty limit prób – wtedy agent zwraca swoją najlepszą wersję i oznacza to, co nadal jest niepewne. Krótko mówiąc, najpierw udziela odpowiedzi, a potem przekonuje samego siebie, że jest ona prawidłowa, zanim ją przekaże.
To zachowanie samokontroli to dokładnie pętla generowania i weryfikacji, dzięki czemu powstaje czysta pierwsza wersja.
LangGraph dobrze pasuje, ponieważ opisuje agenta jako graf. Węzły to elementy, które wykonywają zadania, a krawędzie to strzałki, które określają, co ma nastąpić dalej. Krawędzie mogą wskazywać w tył, co umożliwia powstanie pętli. Prosta liniowa łańcuch nie może się powtarzać, natomiast graf może.
Badacz ma trzy zadania, więc trzy węzły. Pierwsze dwa dzielą pracę między twórcę a sprawdzającego, między wykonawcę a krytyka, co jest typowym wzorcem w pętlach.
+------------------+
START ----------> | Research | <-------------+
| (draft / revise) | |
+--------+---------+ |
| |
v | needs work
+------------------+ | (+ feedback)
| Verify | |
| (check claims) | |
+--------+---------+ |
| |
v |
+-----------+ needs work |
| Decide |-------------------+
| (router) |
+-----+-----+
| verified / out of tries
v
[ END ]
- Badanie polega na zbieraniu materiałów i opracowywaniu odpowiedzi.
- Weryfikacja polega na przejrzeniu projektu i sprawdzeniu, czy każde twierdzenie ma potwierdzenie.
- Decyzja to mały router, który analizuje werdykt i decyduje, co robić dalej: zakończyć pracę lub wrócić i zbadać słabe punkty.
Przykład działa w Pythonie 3.12. Potrzebne są trzy pakiety:
pip install langgraph==1.2.6 langchain-openai==1.3.3 pydantic==2.13.4
langgraphto silnik grafów i pętli, obejmującyStateGraph,STARTorazEND.langchain-openaiotacza model czatowy OpenAI jakoChatOpenAI.pydanticdefiniuje ustrukturyzowane orzeczenie, które zwraca weryfikator.
Aby uruchomić ten kod, w środowisku musi również znajdować się klucz API OpenAI:
export OPENAI_API_KEY="your-key-here"
from typing import TypedDict, Literal
from langgraph.graph import StateGraph, START, END
from langchain_openai import ChatOpenAI
from pydantic import BaseModel, Field
# A model client on OpenAI's Responses API, with the built-in web-search tool
# bound on — so the model can search the web itself, no extra package needed.
# "gpt-5" is a reasoning model; swap it for any current model you have access to.
llm = ChatOpenAI(model="gpt-5", use_responses_api=True)
searcher = llm.bind_tools([{"type": "web_search"}])
MAX_ITERATIONS = 3 # a stop rule, decided up front
# STATE — the shared memory passed between every node
class ResearchState(TypedDict):
question: str # what we're answering
draft: str # the current best answer
verdict: str # "verified" or "needs_work"
feedback: str # what the verifier said to fix
iterations: int # how many times we've looped
# The verifier returns a typed result, so the router gets a clean
# "verified" / "needs_work" to branch on instead of parsing prose.
class Verdict(BaseModel):
status: str = Field(description='"verified" or "needs_work"')
feedback: str = Field(description="claims lacking support, if any")
# NODE 1 — the maker: search the web, then draft (or revise) the answer.
def research(state: ResearchState) -> dict:
prompt = "Search the web, then answer the question. Back every claim with a source.\n"
if state.get("feedback"):
prompt += f"A reviewer flagged these gaps — fix them:\n{state['feedback']}\n"
prompt += f"\nQuestion: {state['question']}"
draft = searcher.invoke(prompt).text
return {"draft": draft, "iterations": state["iterations"] + 1}
# NODE 2 — the checker: search for evidence, then critique the draft.
def verify(state: ResearchState) -> dict:
evidence = searcher.invoke(
f"Search the web for evidence to fact-check claims about: {state['question']}"
).text
checker = llm.with_structured_output(Verdict)
result = checker.invoke(
"You are a fact-checker. Using the evidence below, reply 'verified' "
"only if every claim in the answer is supported; otherwise 'needs_work' "
"and list the unsupported claims as feedback.\n\n"
f"Evidence:\n{evidence}\n\nAnswer:\n{state['draft']}"
)
return {"verdict": result.status, "feedback": result.feedback}
# ROUTER — the heart of the loop. Reads the verdict, picks the next step.
def decide(state: ResearchState) -> Literal["research", "__end__"]:
if state["verdict"] == "verified":
return "__end__" # success: goal met
if state["iterations"] >= MAX_ITERATIONS:
return "__end__" # surrender: out of tries
return "research" # loop back and fix the gaps
# WIRE IT UP
graph = StateGraph(ResearchState)
graph.add_node("research", research)
graph.add_node("verify", verify)
graph.add_edge(START, "research") # trigger
graph.add_edge("research", "verify") # always verify a fresh draft
graph.add_conditional_edges("verify", decide, {
"research": "research", # the backward arrow = the loop
"__end__": END,
})
agent = graph.compile()
result = agent.invoke({
"question": "What were the main causes of the 2008 financial crisis?",
"draft": "", "verdict": "", "feedback": "", "iterations": 0,
})
print(result["draft"])
Dwa aspekty wyróżniają się szczególnie. Po pierwsze: oba węzły uzyskują dostęp do żywej sieci za pośrednictwem wbudowanego narzędzia web_search od OpenAI, podłączonego za pomocą bind_tools. Węzeł research przeprowadza wyszukiwanie przed sporządzeniem projektu, dzięki czemu jego twierdzenia opierają się na rzeczywistych wynikach. Węzeł verify wyszukuje ponownie, aby sprawdzić projekt na podstawie nowych dowodów, a nie pamięci modelu, i to drugie wyszukiwanie dostarcza pętli obiektywnego sygnału. Po drugie: verify polega na użyciu with_structured_output, które wymusza użycie skategoryzowanego verdict wraz z feedback zamiast prozy, dzięki czemu router może w sposób niezawodny kierować przepływem danych bez konieczności analizy tekstu swobodnego.
Pięć elementów pętli odpowiada dokładnie kodowi:
- Trigger: wywołanie
invoke(...)z pytaniem rozpoczyna proces. - Cel do sprawdzenia: zasady
verifymuszą mieć statusverifiedlubneeds_work. - Narzędzia: oba węzły wykorzystują wbudowaną wyszukiwarkę internetową,
researchdo pisania orazverifydo sprawdzania. - Stan: słownik
ResearchStateprzenosi projekt, informacje zwrotne oraz liczbę iteracji między węzłami. - Zasady zatrzymania: router
decidekończy proces w przypadku sukcesu lub po osiągnięciu wartościMAX_ITERATIONS.
Ostatni punkt jest kluczowy dla całego mechanizmu, ponieważ to właśnie router stanowi serce projektowania pętli. Jedna linijka kodu – zatrzymać się po sprawdzeniu, zatrzymać po trzech próbach, w przeciwnym razie wrócić – odróżnia agenta, który skutecznie poprawia swoją odpowiedź, od tego, który bez końca generuje koszty.
Przykład zawiera dwa wyjścia. Pętle produkcyjne zazwyczaj dodają trzecie – przejście do człowieka. Gdy agent napotka coś ryzykownego lub niejasnego, lepiej jest, aby nie zgadywał ani nie zatrzymywał się w ciszy, lecz zatrzymał się i przekazał wszystkie zebrane informacje na wyższy poziom. W routerze jest to po prostu kolejna gałąź: gdy pewność siebie jest niska lub działanie jest delikatne, ścieżka escalate zakończa pętlę i pokazuje projekt, otwarte pytania oraz podjęte próby. Umiejętność rozpoznania sytuacji, w których nie należy podejmować decyzji, stanowi element dobrego projektowania pętli.
Tryby awarii i mechanizmy ochronne
Gdy pętla działa sama, pojawia się krótka lista przewidywalnych awarii, a każda z nich ma standardowy mechanizm ochronny.
- Nieskończony cykl. Agent nigdy nie dochodzi do wniosku, że skończył, i kontynuuje działanie, dopóki coś się nie zepsuje lub nie skończą się pieniądze. Ograniczenie liczby iteracji stanowi twardy limit, np.
MAX_ITERATIONSwymieniony powyżej – to wyjście, które nie opiera się na opinii samego agenta. - Spalanie tokenów. Przy każdym przetworzeniu wysyłany jest coraz większy zbiór kontekstu, a koszt rośnie niezauważalnie. Aby utrzymać stan w minimalnej formie, przechowuj tylko to, co jest potrzebne w następnym kroku – bieżący projekt i konkretne informacje zwrotne, a nigdy pełną historię.
- Wyimaginowany postęp. Agent ogłasza sukces, którego nie osiągnął, na przykład twierdzi, że naprawił coś, czego w rzeczywistości nie zrobił. Nie pozwól mu oceniać własnej pracy pod kątem tego, co jest istotne. Odrębny krok weryfikacji z obiektywnym testem, testami, które faktycznie się uruchamiają, lub źródłami, które rzeczywiście istnieją, sprawia, że „zrobione” oznacza naprawdę „zrobione”.
research otrzymuje feedback od weryfikatora.Kiedy nie należy tworzyć pętli
Pętle są potężne, więc łatwo jest ich nadużywać. W takich sytuacjach lepsze jest coś prostszego.
- Wystarczy jedna iteracja. Streszczanie dokumentu, tłumaczenie tekstu, odpowiadanie na pytanie faktograficzne oraz klasyfikacja e-maila to zadania, które można wykonać za jednym razem. Użycie pętli w tych przypadkach tylko zwiększa koszty, opóźnienia i szanse na błędy. Jeśli wystarczy prosta sekwencja kroków, należy ją użyć.
- Sukces jest nierozpoznawalny. Gdy cel jest subiektywny lub niejasny, albo tylko człowiek może go ocenić, pętla nie ma żadnych wytycznych i może zakończyć się losowo lub błądzić bez końca. Cel, którego nie da się zweryfikować, tworzy automat do gry, a nie pętlę.
Zasada ogólna: jeśli warunki sukcesu oraz warunki rezygnacji nie mogą zostać spisane, pętla nie jest gotowa do implementacji.
Lista kontrolna przed uruchomieniem pętli
Inżynieria pętli przesuwa moment uzyskania korzyści. Napisanie doskonałego promptu ma mniejsze znaczenie niż zaprojektowanie systemu, który kieruje agentem, czyli jego mechanizmu uruchamiania, celu, narzędzi, stanu oraz zasad zatrzymywania. Mimo to pętla jest tylko jednym z narzędzi i nigdy nie stanowi rozwiązania domyślnego. Warto najpierw zadać pięć pytań:
- Czy sukces można sprawdzić automatycznie? Jeśli nie, pomiń pętlę, ponieważ nie będzie miała czego kierować.
- Czy zadanie staje się lepsze przy powtarzaniu? Jeśli jedna próba wystarczy, zachowaj prostotę.
- Co dokładnie oznacza ukończenie zadania? Zapisz warunek sukcesu przed rozpoczęciem programowania.
- Kiedy powinna się zatrzymać? Ustal sztywny limit, aby pętla nie mogła działać wiecznie.
- Czy działania można bezpiecznie powtarzać? Jeśli iteracja może spowodować poważne szkody, dodaj punkt kontroli realizowanego przez człowieka lub nie używaj pętli w tym kroku.
Poprzez uczciwe odpowiedzi na wszystkie pięć pytań wynikiem może być niezawodny cykl, a nie tylko efekt pokazowy. Najlepiej sprawdza się skromny pierwszy projekt: jedna runda badania i weryfikacji, jak opisano powyżej, przy czym zasady zatrzymania muszą być ustalone już na początku, zanim cokolwiek się rozwinie.
Ostatnia kwestia: cykl służy nie tylko przyspieszeniu pracy. Wzmacnia wszelkie decyzje podjęte przy jego tworzeniu, powtarzając zarówno dobre, jak i złe decyzje z prędkością maszyny. Celem zatem nie jest tylko uruchomienie go i porzucenie. Dyscyplina polega na pozostawaniu na tyle blisko, by stale rozumieć, co robi cykl po tym, jak zacznie działać samodzielnie, tak aby jego twórca pozostał jego inżynierem, a nie tylko osobą, która naciska przycisk start.
Literatura pokrewna
- Harness, Loop i Graph: Trzy nawarstwione warstwy systemu agentów programistycznych — Objawy awarii wskazują na warstwę wymagającą naprawy. Jak się nawarstwiają harness, loop i graph, gdzie przydaje się podejście wieloagentowe, czego nie mogą zagwarantować metody przeciwdziałania atakom oraz lista kontrolna.
- Inżynieria Loop: Cztery nawarstwione pętle dla samodoskonalących się agentów AI — Jak cztery nawarstwione pętle sterujące (ReAct, retry, queue, hill climbing) w połączeniu z sędzią, miernikiem budżetu i kontrolą modyfikacji sprawiają, że agent jest niezawodny, na przykładzie procesu oceny ubezpieczeń.