Inżynieria pętli: budowanie pętli agentów przy użyciu narzędzi weryfikacyjnych i reguł zatrzymywania.
Praktyczny przewodnik po tworzeniu czterech warstwowych pętli agentów: podstawy ReAct, narzędzia oceny według rubryk, mechanizmy routingu LangGraph, umowy pętli, wyzwalacze zdarzeń, metoda wspinaczki po wzgórzach oraz zasady ochrony przed awariami.
Myślenie leżące u podstaw tego wszystkiego jest łatwe do sformułowania. Przestań kierować sztuczną inteligencją krok po kroku, zamiast tego zaprojektuj pętlę, w której będzie funkcjonować. Twierdzenie, które należy przyjąć, brzmi, że to weryfikator, a nie model, ogranicza to, czemu można zaufać, a obraz, który należy mieć na myśli, to cztery pętle nawzajem zawarte w sobie. Oto jak to zbudować: elementy pętli, kod dla każdej warstwy, sposoby, w jakie pętle zawodzą, oraz zasady zatrzymania, które zapobiegają wyczerpaniu budżetu. Na końcu będziesz wiedział wystarczająco dużo, by pozwolić pętli przygotować pull request, podczas gdy ty śpisz.
Przykłady kodu opierają się na udokumentowanych API, identyfikatory modeli są placeholderami, a każdy fragment będący jedynie pseudokodem jest o tym informowany w komentarzu na początku. Przez cały tekst przechodzi jeden przykład, typowy punkt wyjścia w tej dziedzinie: pętla programistyczna, która odtwarza nieudany test, go naprawia, sprawdza tę naprawę za pomocą czegoś innego niż sam agent, i tworzy wstępny PR.
Pięć elementów pętli
Niezależnie od używanego frameworku, każda sprawna pętla składa się z pięciu elementów. Jeśli któryś z nich zabraknie, pętla będzie działać nieskutecznie, zatrzyma się lub będzie trwać w nieskończoność.
- Powód uruchomienia. To, co ją inicjuje – czy to wiadomość od człowieka, zaplanowany sygnał, webhook czy nowa wiersz w tabeli.
- Cel, który maszyna może sprawdzić. „Sprawdzenie, czy testy przeszły” spełnia ten warunek, natomiast „poprawa kodu” – nie. Jeśli oprogramowanie nie może stwierdzić, czy cel został osiągnięty, pętla również nie może tego zrobić.
- Narzędzia dostarczające rzeczywistych informacji zwrotnych. Agent musi działać na świecie zewnętrznym i obserwować wyniki poprzez uruchamianie kodu, czytanie pliku stderr lub wywoływanie API.
- Lekki, zarządzany stan. Należy przechowywać cel, notatki oraz informacje o tym, co zostało już wypróbowane. Nadmierny stan powoduje spowolnienie pętli, jej błądzenie i przekroczenie limitu kontekstu.
Należy planować trzy możliwe wyjścia, a nie dwa. Sukces: weryfikator przeszedł testy, więc można wysłać produkt. Porażka: wyczerpał się budżet lub limit iteracji, więc należy zatrzymać proces i podsumować to, co pozostało. Przekazanie zadania: agent napotkał decyzję, którą powinien podjąć tylko człowiek, więc sprawa jest eskalowana. Częścią projektowania dobrej pętli jest rozpoznanie sytuacji, w których nie powinna ona sama podejmować decyzji.
Pętla 1: pętla agenta
W centrum znajduje się cykl, który już wykorzystują wszyscy agenci – wzorzec ReAct z 2022 roku: myślenie, działanie poprzez wywołanie narzędzia, obserwacja wyniku i powtarzanie tego procesu aż do zakończenia. W 2026 roku został on celowo zaprojektowany i nie jest już kierowany ręcznie. W swojej najprostszej formie składa się z jednego wywołania funkcji:
from langchain.agents import create_agent
def run_tests() -> str:
"""Run the project's test suite and return the raw output."""
…
agent = create_agent(
model="anthropic:claude-opus-5",
tools=[run_tests],
system_prompt="You are a careful Python engineer. Fix failing tests.",
)
# create_agent returns a graph that calls tools in a loop, repeating
# until the model replies with no tool calls. The loop runs on .invoke()
To krótkie wyrażenie kryje w sobie pętlę, którą powinieneś być w stanie sobie wyobrazić. Poniżej znajduje się ta sama struktura sterująca w postaci pseudokodu, bez żadnego frameworka. Zauważ, że każde wyjście jest ograniczone:
# PSEUDOCODE - shows the control structure a harness implements.
# The helper names below are yours to supply, not a real library API.
def run_loop(goal):
state = init_state(goal) # goal + scratchpad + attempt log
for step in range(MAX_STEPS): # hard cap: never loop forever
thought = model.reason(state) # ReAct: reason…
action = model.choose_action(state) # …then pick a tool call
result = tools.execute(action) # touch the real environment
state = update(state, thought, action, result)
state = compact(state) # keep context under budget
if verifier.passes(state): # deterministic check = reward
return success(state)
if no_progress(state) or budget.exhausted():
return escalate_to_human(state) # third exit: hand-off
return escalate_to_human(state)
Ze wszystkich tutaj przedstawionych kształtów zapamiętaj właśnie ten. Pozostałe są jego udoskonaleniami.
Pętla 2: dodanie weryfikatora
Prosty agent sam decyduje, kiedy skończył pracę, a poleganie na tym prowadzi do fałszywie pozytywnych wyników. Dlatego agent jest otoczony narzędziem oceny, które sprawdza jego pracę według określonych kryteriów. Gdy praca nie spełnia wymagań, pojawia się krytyka, a pętla kontynuuje się aż do osiągnięcia maksymalnego limitu. Middleware do weryfikacji znajduje się w pakiecie deepagents.
from deepagents import RubricMiddleware, create_deep_agent
from langchain.messages import HumanMessage
from langgraph.checkpoint.memory import InMemorySaver
RUBRIC = """
- All tests pass in run_tests
- No test is skipped or deleted to force a pass
"""
agent = create_deep_agent(
model="anthropic:claude-opus-5",
system_prompt="You are a careful Python engineer.",
middleware=[
RubricMiddleware(
model="anthropic:claude-haiku-4–5", # a cheap grader is fine
system_prompt="Grade against the rubric. Be strict.",
max_iterations=5, # the stop rule (default is 3)
),
],
checkpointer=InMemorySaver(),
)
# The rubric is passed at invoke time - not to the constructor.
result = agent.invoke(
{
"messages": [HumanMessage("Make the failing tests pass.")],
"rubric": RUBRIC,
},
config={"configurable": {"thread_id": "fix-tests-session"}},
)
Oto jak to działa. Gdy agent jest już prawie gotowy, oddzielny podagent oceniający czyta transkrypcję w porównaniu z kryteriami oceny. Werdykt needs_revision umieszcza informacje zwrotne z powrotem w rozmowie jako HumanMessage, a agent kontynuuje pracę. Jedynymi możliwymi wynikami są satisfied, failed, max_iterations_reached oraz grader_error, dzięki czemu pętla zostaje zamknięta i zawsze kończy się. Jeśli oceniający musi przeprowadzić własne sprawdzenia, należy mu dostarczyć narzędzia w postaci instancji BaseTool.
Istnieją dwa rodzaje weryfikatorów, a właściwy wybór stanowi istotę umiejętności w tym zakresie.
- Deterministyczne: przeprowadzają testy, walidują schemat i potwierdzają wynik. Są tanie, szybkie i niemożliwe do oszukania, dlatego należy je wypróbować najpierw.
Zmień to na graf
Gdy zadanie staje się bardziej złożone niż proste, wyraźny graf jest lepszy od ukrytego pętli – węzły, krawędzie oraz miejsce decydowania o zatrzymaniu są w pełni widoczne. Agent badawczy mieści się w trzech węzłach, a każda decyzja o zatrzymaniu jest podejmowana przez routera:
from typing import Literal, TypedDict
from pydantic import BaseModel, Field
from langgraph.graph import END, StateGraph
class ResearchState(TypedDict):
question: str
draft: str
verdict: str
feedback: str
iterations: int
class Verdict(BaseModel):
status: str = Field(description='"verified" or "needs_work"')
feedback: str = Field(description="claims lacking support, if any")
def decide(state: ResearchState) -> Literal["research", "__end__"]:
if state["verdict"] == "verified": # success exit
return "__end__"
if state["iterations"] >= MAX_ITERATIONS: # surrender exit
return "__end__"
return "research" # else: loop again with the feedback
builder = StateGraph(ResearchState)
builder.add_node("research", research_node) # generator
builder.add_node("verify", verify_node) # verifier
builder.add_edge("research", "verify")
builder.add_conditional_edges(
"verify", decide, {"research": "research", "__end__": END}
)
builder.set_entry_point("research")
graph = builder.compile()
W tym kodzie nie ma żadnego sprytnego polecenia. Mądrość tkwi w strukturze: jeden węzeł generuje, drugi weryfikuje, a router przekształca wynik albo w kolejną próbę z informacjami zwrotnymi, albo w zatrzymanie procesu. LangGraph traktuje znaczniki __end__ i END jako to samo.
Umowa pętli
Tutaj zmiana sposobu myślenia staje się konkretna. Zamiast pisać instrukcje, piszemy specyfikację „zakończenia”, czyli funkcję nagrody wraz z regułą zatrzymania. To właśnie ten dokument przeglądamy, porównujemy i komitujemy:
Cel: zielone build CI na gałęzi payments-refactor. Uznaje się to za ukończone, gdy wszystkie testy przeszły i żaden nie został pominięty ani usunięty w celu oszustwa. Kroki: przeczytać nieudany test, naprawić prawdopodobną przyczynę i uruchomić proces ponownie. Pamięć: rejestr prób już podjętych, aby nic nie powtarzało się. Zatrzymać się przy wyniku „zielonym”, otwierając projekt PR, po sześciu rundach podsumowując to, co pozostało, lub w każdym momencie, gdy praca dotyczy logiki autoryzacji lub płatności, przekazując ją innemu osobie.
Ani jedna instrukcja nie trafiła do modelu. Zapisano cel, sprawdzenia, zasadę dotyczącą pamięci oraz trzy sposoby wyjścia, a ten kontrakt stanowi element inżynierii pętli.
Pętle 3 i 4: budowanie warstw zewnętrznych
Jedna dobrze zaprojektowana pętla już pomaga. Korzyści się mnożą, gdy otacza się ją kolejnymi pętlami, z których każda działa przy wolniejszym tempie. Pętle 1 i 2 realizują właściwą pracę, natomiast pętle 3 i 4 sprawiają, że proces jest ciągły i samodoskonalący się.
Pętla 3: wydarzenia
Zewnętrzne wydarzenie zmienia twoją pętlę z narzędzia, które uruchamiasz ręcznie, na usługę działającą samodzielnie. Jest to również naturalne miejsce na mechanizm zatwierdzenia przez człowieka przed wypuszczeniem jakiejkolwiek funkcji:
# Loop 3: an event turns the loop into a service
from pydantic import BaseModel
class CIEvent(BaseModel):
branch: str
@app.post("/webhook/ci-failed")
def on_ci_failure(event: CIEvent):
if not event.branch.startswith("fix/"): # cheap triage first
return {"skipped": True}
result = agent.invoke(
{
"messages": [HumanMessage(
f"Fix the failing test on {event.branch}.")],
"rubric": TEST_GREEN_RUBRIC,
},
config={"configurable": {"thread_id": event.branch}},
)
open_draft_pr(result) # a human approves the merge, not the loop
return {"opened_pr": True}
Pętla 4: wspinaczka po wzgórzach
Najzewnętrzniejsza pętla jest najwolniejsza i działa na samej pętli. Każdy jej przebieg pozostawia ślad. Agent analityczny odczytuje te ślady, znajduje błędy, które się powtarzają, i proponuje zmiany w narzędziach: instrukcjach, toolach oraz kryteriach oceny sprawdzanych przez ludzi. Wyobraźmy sobie strzałkę powrotną – zamiast wracać tylko do początku, dociera ona do wewnętrznej pętli i ją zmienia. System poprawia sam siebie.
Jedna uwaga: zewnętrzne pętle mnożą wszystko, co znajduje się w ich wnętrzu. Należy je dodawać dopiero wtedy, gdy wewnętrzny sprawdzacz jest silny, ponieważ czwarta pętla wokół słabego sprawdzacza jedynie automatyzuje masowe generowanie błędnych wyników.
Dlaczego to można zaliczyć do inżynierii
Bariery mogą wyglądać jak biurokracja. Przestają tak wyglądać, gdy spojrzy się na agenta jako na kontroler z zamkniętym obiegiem sprzężenia zwrotnego, czyli na mapowanie dokonujące przekładu punkt po punkcie. Celem jest wartość ustalona, agentem jest kontroler, a narzędzia wraz z otoczeniem tworzą układ. Sprawdzacz pełni rolę czujnika, a jego werdykt „wymaga poprawek” stanowi sygnał błędu, który uruchamia kolejną korektę. Ukończony zadanie oznacza konwergencję. Kontroler jest napędzany różnicą pomiędzy wartością ustaloną a odczytem z czujnika, niezależnie od tego, czy układem jest silnik odrzutowy, czy zestaw testowy.
To samo słownictwo opisuje dwa sposoby zakończenia pętli. Może ona oscylować, nieskończenie powtarzając jeden sam błąd, albo odchylać się od celu w miarę wyczerpywania się zasobów. Zabezpieczenia to po prostu warunki stabilności, które utrzymują ją w określonych granicach, a najważniejszą zasadą jest to, że system musi gwarantować zakończenie działania, a nie można polegać na agencie w tym względzie.
Dzień z wszystkimi czterema pętlami
Obserwuj, jak te cztery pętle działają podczas poranka. O godzinie 09:14 test dotyczący funkcji payments-refactor zawodzi i uruchamia się webhook, co stanowi pętlę nr 3, przy czym nikt nic nie wpisuje. Przez następne siedem minut agent czyta informację o błędzie, wprowadza poprawki, ponownie uruchamia test, czyta nowy błąd i znów wprowadza poprawki, prowadząc rejestr prób (pętla nr 1). Po każdej rundzie deterministyczny narzędzie sprawdza cały zestaw testów i upewnia się, że nic nie zostało pominęte w celu wymuszenia pozytywnego wyniku (pętla nr 2). Czwarta runda kończy się wynikiem pozytywnym.
O godzinie 09:22 pętla kończy się prawidłowo, z projektem zmiany pokazującym, co zostało zmienione i dlaczego. Musi to zatwierdzić człowiek, ponieważ zmiana dotyczy płatności. W nocy pętla wykrywa, że to już trzeci błąd związany z strefą czasową w tym tygodniu, i tworzy nową kontrolę zgodności, która przechodzi przez twoją ocenę (pętla 4). Jutrzejsza sesja rozpoczyna się lepiej niż dzisiejsza.
Przespałeś większość tego czasu. Rano jest projekt zmiany i decyzja do podjęcia, a nie ma klawiatury, którą można by uderzać.
Gdy pętle idą nie tak
Pętle wzmacniają sygnały, a proces wzmacniania odbywa się w obu kierunkach. Każdy tryb awarii wpływa na pętlę w określonym miejscu i ma standardowe zabezpieczenia; powtarza się tu jeden temat: to, co generuje sygnał, nie może jednocześnie oceniać jego jakości. Najtańszym sposobem ochrony jest przeprowadzenie weryfikacji na danych, o których wiadomo, że są poprawne, oraz tych, które są błędne, zanim pętla zostanie pozostawiona sama sobie. Należy upewnić się, że odrzuci te błędne dane, ponieważ nieweryfikowany narzędzie to jedynie opinia oparta na założeniach.
Kiedy nie należy budować pętli
Pospieszne stosowanie pętli we wszystkim jest samym w sobie modelem awarii. W takich sytuacjach należy ograniczyć się do pojedynczego wywołania:
- Jeden przepływ danych wystarcza – np. przy tworzeniu streszczenia, tłumaczenia lub czystego wyodrębnienia informacji. Pętla dodaje jedynie koszty i opóźnienia.
- Nie da się zweryfikować żadnego celu. Bez sposobu na sprawdzenie, czy praca została zakończona, nie ma sygnału błędu, co powoduje dalsze marnowanie pieniędzy na niezakończoną pętlę.
Inżynieria pętli oznacza zarówno wiedzę o tym, które problemy wymagają użycia pętli, jak i umiejętność jej budowy.
Buduj ją tak, jakbyś chciał zachować tę pracę
Oto niezbędne narzędzia: analiza struktury, pętla agenta, weryfikator, graf, kontrakt, zewnętrzne pętli oraz katalog błędów. Wyposaż pętlę w silny weryfikator, mechanizm natychmiastowego zatrzymania oraz ograniczenia, których nie może przekroczyć. Dodaj ludzkie punkty kontrolne tam, gdzie stawką są rzeczy ważne, i pamiętaj, że to, że pętla dostarcza rozwiązanie, nie oznacza, że go rozumiesz. Następnie pozwól jej działać, tak jak robi to osoba, która zamierza pozostać inżynierem, a nie tylko osobą, która ją uruchomiła.
Kolejny krok
Jedno pytanie warto zadać, zanim pętla zostanie pozostawiona bez nadzoru: jak słaby może być weryfikator i mimo to pokazywać zielony kolor? Aby to sprawdzić, stworzono punkt odniesienia. Zawiera on zapisane przypadki manipulacji nagrodami oraz ocenia konfiguracje bram według liczby takich manipulacji, które pozwoliły się przeprowadzić. Brama, która ignoruje własny raport agenta i ponownie uruchamia zestaw testów – czyli deterministyczną kontrolę zalecaną wcześniej jako pierwszy krok – nie zatrzymała żadnej z ośmiu prób. Ponowne uruchomienie zestawu testów jedynie potwierdza, że sygnał nagrody został spełniony, a dokładnie to osiąga manipulacja nagrodą.
Jeśli więc weryfikator ogranicza system, staje się oczywista kolejna rzadka umiejętność: projektowanie, wersjonowanie i ulepszanie samych sprawdzeń. Nazywa się to inżynierią oceny – zadaniem polegającym na ustalaniu standardów, które proces musi spełnić. Jeden weryfikator to praca w ramach jednego cyklu. Inżynieria oceny obejmuje natomiast wiele takich cykli, poprzez zestawy danych i kryteria oceny, które pokazują, czy system jako całość się poprawia, czy pogarsza.
Wzmocnienie danego etapu to jak drabina, a jej szczyt jest nieoczekiwany. Okazuje się, że najlepszym rozwiązaniem nie jest żaden skomplikowany kod, lecz zaledwie kilka stwierdzeń, których agent nie miał prawa zobaczyć. Dlatego ograniczenia weryfikacji znajdują się w dość trudnym miejscu. Zależą one mniej od tego, jak dobrze zbudowany jest dany etap, a bardziej od jakości danych zachowanych na boku oraz od tego, czy unika się ich wycieku z powrotem do cyklu.
Literatura pokrewna
- Inżynieria pętli: Projektowanie pętli, która kieruje twoim agentem AI — Dlaczego weryfikator stanowi wąskie gardło w pętlach agentów, jak wyglądają cztery nawarstwione pętle oraz jakie zasady bezpieczeństwa i punkty kontrolne sprawiają, że autonomiczny agent kodujący pozostaje bezpieczny.
- Inżynieria pętli: Cztery nawarstwione pętle dla samodoskonalących się agentów AI — Jak cztery nawarstwione pętle sterujące (ReAct, ponowna próba, kolejka, wspinaczka po wzgórzu) w połączeniu z sędzią, miernikiem budżetu i kontrolą modyfikacji sprawiają, że agent jest niezawodny, przykład zastosowania w procesie oceny ubezpieczeń.