## Pętla agenta

*Agenci*

*Ostatnia zmiana: 28 września 2026*

Agent to model w pętli: dostaje cel i narzędzia, wybiera wywołanie, twój kod je wykonuje i odsyła wynik, aż model odpowie bez wywołania. Od workflow różni się jednym: kolejny krok wybiera model, a nie twój kod.

**Po ludzku:** Workflow to lista kroków dla stażysty: zrób to, potem tamto, a jak coś nie pasuje, przyjdź do mnie. Agent to asystent, który dostaje cel, telefon i kalendarz, a kolejne kroki wymyśla sam. Poradzi sobie z niespodzianką, ale nie wiesz z góry, ile mu to zajmie i co zrobi po drodze.

*Interaktywny widżet na stronie: Wybierz workflow albo agenta i to, co jest w piątek w kalendarzu, potem naciśnij ▶. Patrz, kto wybiera kolejny krok i jak z każdą turą rośnie kontekst.*

### Pętla w kodzie

- Pętla to kilkanaście linijek zwykłego kodu. Wyślij do modelu kontekst i definicje narzędzi. Jeśli odpowiedź zawiera wywołania, dopisz do kontekstu odpowiedź modelu bez zmian, wykonaj wywołania, dopisz wyniki i wyślij całość znowu. Jeśli nie zawiera, koniec. Model niczego nie uruchamia, tylko pisze, co chce wywołać (temat „Narzędzia (function calling)”).
- W API Anthropic taka odpowiedź ma `stop_reason: "tool_use"` i bloki `tool_use` z identyfikatorem. Wyniki wracają w następnej wiadomości, po turze asystenta, jako bloki `tool_result` z tym samym `tool_use_id`, a błąd oznaczasz `is_error: true`. W Responses API OpenAI to elementy `function_call` i `function_call_output` łączone przez `call_id`. Kilka wywołań z jednej odpowiedzi wykonujesz równolegle i odsyłasz wszystkie wyniki naraz.
- Model myśli też między wywołaniami (interleaved thinking; w Claude Opus 5.5 myślenia nie da się wyłączyć, stan na wrzesień 2026). API Anthropic wymaga, by bloki thinking z tury z narzędziami wróciły kompletne i niezmienione, a zmienione odrzuca błędem 400. W Responses API odsyłasz reasoning items razem z wynikami albo łączysz requesty przez `previous_response_id` (temat „Modele rozumujące”).
- Odpowiedź bez wywołania to tylko ocena modelu, że skończył. Kod dokłada twarde warunki stopu: limit tur, budżet tokenów i kosztu, limit czasu, wykrywanie powtórzonych wywołań. Obsługuje też inne powody zatrzymania i żaden z nich nie jest końcem zadania: odpowiedź ucięta na limicie tokenów (`max_tokens`) albo okna kontekstu (`model_context_window_exceeded`) to błąd do obsłużenia, `pause_turn` (pętla narzędzi po stronie dostawcy doszła do limitu) znaczy, że trzeba odesłać odpowiedź, żeby model kontynuował, a `refusal` wymaga osobnej ścieżki.

### Workflow czy agent

- W workflow kroki zapisuje programista, a model robi w nich wąskie zadania, np. wyciąga dane z polecenia albo pisze wiadomość. W agencie kod daje cel i narzędzia, a kroki wybiera model. Workflow jest tańszy, szybszy, powtarzalny i łatwy do testowania, ale obsłuży tylko to, co ktoś przewidział. Agent radzi sobie z niespodziankami, ale płaci tokenami, czasem i przewidywalnością. Kolejność: jedno wywołanie modelu, potem workflow, agent dopiero wtedy, gdy kroków nie da się wypisać z góry.
- Wzorce z tekstu Anthropic „Building effective agents” (2024): łańcuch wywołań ze sprawdzeniami w kodzie między nimi, routing (klasyfikacja, potem osobna ścieżka albo tańszy model), równoległość (niezależne części naraz albo kilka prób i głosowanie), orchestrator–workers (model dzieli zadanie na podzadania, których nie znasz z góry) i evaluator–optimizer (jeden model pisze, drugi ocenia, aż wynik przejdzie). Na produkcji często wygrywa workflow z jednym agentowym krokiem w środku.
- Te same idee pod innymi nazwami. ReAct (Yao i in., 2022) to właśnie ta pętla: myśl to tekst albo myślenie modelu, akcja to wywołanie narzędzia, obserwacja to jego wynik. Cztery wzorce agentowe Andrew Nga (2024) są w tym przewodniku jako evaluator–optimizer (refleksja), „Narzędzia (function calling)” (użycie narzędzi), lista zadań w długich zadaniach (planowanie) i „Wielu agentów” (współpraca agentów).

### Awarie długich zadań

- Błąd narzędzia oddajesz modelowi jako zwykły wynik, z podpowiedzią: nie „błąd 409”, tylko „konflikt z Przeglądem kwartalnym, sprawdź wolne terminy”. Model zmienia wtedy podejście, jak w przykładzie z konfliktem. Wyjątek, który zabija pętlę, marnuje całą dotychczasową pracę. Błędy, których model nie naprawi, jak brak uprawnień czy wyczerpany budżet, obsługuje kod.
- W długiej historii agent gubi cel. Pomagają plan (lista zadań, którą agent odhacza i przepisuje na koniec kontekstu), notatki w plikach i kompakcja historii (temat „Context engineering i pamięć”).
- Agent utyka: ponawia to samo wywołanie, krąży między dwoma krokami, ogłasza sukces, którego nie było. Na to są limity i wykrywanie powtórek w kodzie, nie prośby w prompcie. Przerwany agent zostawia świat zmieniony w połowie, np. spotkanie przeniesione, a wiadomość niewysłana. Dlatego narzędzia zmieniające stan są idempotentne, stan pętli zapisujesz po każdym wywołaniu, żeby wznowić pracę po awarii, a człowiek dostaje raport z tego, co zdążyło się stać.

### Koszt, uprawnienia i ocena

- Każda tura wysyła cały kontekst od nowa, więc łączna liczba tokenów wejściowych rośnie mniej więcej z kwadratem liczby tur. Opóźnienia się sumują: każda tura to pełne wywołanie modelu plus czas narzędzia. Rachunek pokazuje temat „Okno kontekstowe i agent”. Dopóki historię tylko się dopisuje, wszystko poza najnowszą częścią tury to stały prefiks, więc dzięki „Prompt caching” czyta się go z cache’u za ok. jedną dziesiątą ceny wejścia. Krzywa zostaje kwadratowa, tylko tańsza.
- Agent działa w twoim imieniu, więc dostaje najmniejsze potrzebne uprawnienia. Akcje nieodwracalne albo wychodzące na zewnątrz (wysyłka, płatność, kasowanie) zatwierdza człowiek, a pilnuje tego kod, nie prompt: w przykładzie kod wstrzymuje pętlę przed wysłaniem wiadomości. Maile, strony i wyniki narzędzi mogą zawierać polecenia (temat „Prompt injection”).
- Agenta oceniasz po stanie końcowym, nie po jego podsumowaniu: czy spotkanie naprawdę jest w piątek i czy wiadomość wyszła. Trace, czyli zapis każdej tury z narzędziami, argumentami, wynikami i tokenami, pokazuje, gdzie agent błądzi i ile kosztuje. Ten sam przypadek raz przechodzi, raz nie, więc liczysz pass^k: czy agent zrobi zadanie za każdym z k razy (temat „Ewaluacje”).
- Zadanie, które dzieli się na niezależne części, główny agent może rozdać subagentom z osobnym kontekstem, za cenę wielokrotnie większej liczby tokenów. Zobacz „Wielu agentów”. Jak agent kodujący składa te elementy w całość (uprawnienia, sandbox, plan, kompakcja, subagenci), opisuje temat „Harness agenta kodującego”.

### Sprawdź się

**Pytanie:** Kiedy zbudujesz agenta zamiast workflow i jak zabezpieczysz jego pętlę na produkcji?

**Krótka odpowiedź:** Agent to model w pętli: dostaje cel i narzędzia, wybiera wywołanie, twój kod je wykonuje i dopisuje wywołanie z wynikiem, aż model odpowie bez wywołania. W workflow kroki zapisujesz ty, a model robi w nich wąskie zadania, więc workflow jest tańszy, szybszy i powtarzalny. Agent opłaca się dopiero, gdy kroków nie da się wypisać z góry. Wtedy kod pilnuje limitu tur, budżetu i czasu, daje najmniejsze uprawnienia, wstrzymuje akcje nieodwracalne do zgody człowieka i zapisuje stan po każdym kroku. Jakość mierzy się stanem końcowym, a każde zadanie puszcza się kilka razy.

### Pytania pogłębiające

- **Skąd agent wie, że skończył?** Nie wie, tylko tak ocenia: odpowiada bez wywołania narzędzia. Bywa, że ogłasza sukces, którego nie było. Dlatego kod ma twarde limity (tury, tokeny, czas), a wynik sprawdzasz testem stanu końcowego, nie podsumowaniem modelu.
- **Agent w kółko wywołuje to samo narzędzie. Co robisz?** Doraźnie kod wykrywa powtórzone wywołanie z tymi samymi argumentami, dopisuje modelowi uwagę, a przy kolejnym powtórzeniu przerywa pętlę. Przyczyna leży zwykle w narzędziu: niejasny komunikat błędu albo wynik, z którego nie widać postępu. Taki przebieg trafia do zestawu ewaluacyjnego jako nowy przypadek.
- **Agent przerwał w połowie zadania. Jak się na to przygotować?** Zakładasz, że to się zdarzy. Narzędzia zmieniające stan przyjmują klucz idempotencji, a stan pętli zapisujesz po każdym wywołaniu, więc da się wznowić pracę bez powtarzania skutków. Człowiek dostaje listę tego, co już zmieniono, a tam, gdzie się da, akcję odwracającą.
- **Jak ocenisz, czy agent jest gotowy na produkcję?** Zestaw zadań z prawdziwych przypadków, każde puszczone kilka razy i ocenione po stanie końcowym, plus koszt i czas na zadanie. Liczysz pass^k, bo użytkownik oczekuje, że zadziała za każdym razem: dla zadania, które agent robi w 90% prób, przy niezależnych próbach trzy udane z rzędu wychodzą w ok. 73% przypadków. Dla zestawu liczysz pass^k per zadanie i uśredniasz.
- **Jak klasyfikować awarie agenta?** Za Chip Huyen (2025) w trzech grupach. Planowanie: złe albo nieistniejące narzędzie, złe argumenty, nieosiągnięty cel, fałszywe ogłoszenie sukcesu. Narzędzie: wywołanie poprawne, ale narzędzie zwróciło zły wynik, więc każde testuje się osobno. Efektywność: zadanie zrobione, ale zbyt wieloma krokami, zbyt drogo albo zbyt wolno wobec punktu odniesienia. Oznaczone tak trace’y pokazują, czy poprawiać prompt i opisy narzędzi, samo narzędzie czy limity.
- **Czy do agenta potrzebny jest framework?** Nie. Pętla to kilkanaście linijek na zwykłym API i od tego warto zacząć. Framework pomaga przy trwałym stanie, wznawianiu i trace’ach, ale ukrywa prompt i kontekst, które i tak trzeba rozumieć.

### Źródła

- [Anthropic: Building effective agents](https://www.anthropic.com/engineering/building-effective-agents)
- [Dokumentacja Claude: How tool use works (pętla i powody zatrzymania)](https://platform.claude.com/docs/en/agents-and-tools/tool-use/how-tool-use-works)
- [Anthropic: Demystifying evals for AI agents](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents)
- [Chip Huyen: Agents (2025, m.in. typy awarii)](https://huyenchip.com/2025/01/07/agents.html)
- [Hugging Face: Agents Course (praktyka)](https://huggingface.co/learn/agents-course/unit0/introduction)

Strona interaktywna: https://howaiworks.dev/pl/agent/