CCAR-F› 1. Architektura agentowa i orkiestracja›Lekcja 1.2 CCAR-11

Antywzorce pętli agenta: czego nie robić

Po tej lekcji rozpoznasz pięć błędów, przez które pętla agenta kończy się za wcześnie, kręci bez końca albo gubi dane — i wiesz, czym każdy z nich zastąpić.

~7 min czytania3 pojęcia4 pytaniasprawdzone ze źródłami 2 lis 2026
Źródła (6)
Nowe pojęcia Punkt odniesienia ze środowiska ground truth Obcinanie wyników truncation Równoległe wywołania narzędzi parallel tool use

W jednej minucie

Ważne

O tym, czy pętla kręci się dalej, decyduje stop_reason. Tekst odpowiedzi, liczba obrotów i pierwszy blok treści to złe sygnały.

Zapamiętaj

Każde wywołanie dostaje swój wynik — zawsze, w całości albo sensownie skrócony, w jednej wiadomości.

Z praktyki

Wszystkie pięć błędów z tej lekcji działa „prawie dobrze” w prostym teście. Wychodzą dopiero przy dłuższych zadaniach, więc testuj na scenariuszach z wieloma krokami.

Koniec rozpoznawany po tekście

Najczęstszy błąd: kod uznaje zadanie za skończone, bo w odpowiedzi pojawił się tekst albo słowo „gotowe”.

Tymczasem Claude często pisze coś od siebie, zanim wywoła narzędzie1. Tekst trzeba traktować jak każdy inny tekst modelu, bez polegania na jego formacie1.

# ŹLE: pierwszy blok to tekst, więc „koniec”?
if response.content[0].type == "text":
    return response
# ŹLE: szukanie słów w odpowiedzi
if "gotowe" in response.content[0].text.lower():
    return response
# DOBRZE: decyduje stop_reason
if response.stop_reason != "tool_use":
    return response

Ta sama odpowiedź może zawierać i tekst, i prośbę o narzędzie. Wartość tool_use mówi jednoznacznie, że Claude woła narzędzie2:

{
  "stop_reason": "tool_use",
  "content": [
    { "type": "text",
      "text": "Gotowe, sprawdzam jeszcze pogodę." },
    { "type": "tool_use",
      "id": "toolu_01",
      "name": "get_weather",
      "input": { "location": "Zakopane" } }
  ]
}
{
  "koniec?": false,
  "powod": "stop_reason == tool_use",
  "dalej": "uruchom get_weather i odeślij tool_result"
}

Limit to bezpiecznik, nie kierownica

Drugi błąd: pętla kończy się po stałej liczbie obrotów, zamiast słuchać modelu.

Limit iteracji jest potrzebny — to Warunek stopu, który pozwala zachować kontrolę3. Ale jako główny sygnał końca przerywa zadania, które potrzebują więcej kroków.

SygnałRolaJako koniec zadania
stop_reasonMówi, czy model czeka na narzędziegłówny sygnał
Limit iteracjiChroni przed pętlą bez końcatylko awaryjnie
Tekst odpowiedziTreść dla użytkownikanigdy

Ocena w ostatniej kolumnie to nasza rada, oparta na źródłach z tej lekcji.

Z praktyki

Gdy limit się wyczerpie, nie zwracaj ostatniej odpowiedzi jak wyniku. Powiedz wprost, że zadanie przerwano po N krokach, i zapisz to w logach.

Nie gub wyników narzędzi

Trzeci błąd: wynik narzędzia nie wraca do modelu, bo był za duży, nieudany albo „niepotrzebny”.

Agent ocenia postęp na podstawie tego, co w każdym kroku dostaje ze środowiska — to jego punkt odniesienia3. Bez wyniku zgaduje.

  1. Odeślij go zawsze — zaraz po prośbie, bez wiadomości pomiędzy4.
  2. Duży wynik skróć u źródła: stronicowanie, filtrowanie albo obcięcie z rozsądnymi domyślnymi wartościami5.
  3. Powiedz modelowi, że obcięto i jak dostać resztę5.
  4. Nieuruchomione wywołanie też dostaje wynik — z is_error: true i krótkim wyjaśnieniem6.
Uwaga — streszczenie zamiast historii

Podmiana historii na streszczenie w środku pętli, „żeby oszczędzić tokeny”, zabiera modelowi wyniki, na których opiera następny krok. Skracaj pojedyncze wyniki, nie całą rozmowę.

Kilka wywołań naraz

Czwarty błąd dotyczy równoległych wywołań: Claude prosi o kilka narzędzi w jednej odpowiedzi, a kod odsyła wyniki w osobnych wiadomościach.

Poprawnie wszystkie wyniki idą razem, w jednej wiadomości użytkownika6. Inaczej uczysz Claude, żeby unikał równoległych wywołań6.

[
  { "role": "assistant",
    "content": ["tool_use A", "tool_use B"] },
  { "role": "user",
    "content": ["tool_result A"] },
  { "role": "user",
    "content": ["tool_result B"] }
]
[
  { "role": "assistant",
    "content": ["tool_use A", "tool_use B"] },
  { "role": "user",
    "content": ["tool_result A",
                "tool_result B"] }
]

Odpowiedź ucięta w połowie narzędzia

Piąty błąd: kod próbuje wykonać wywołanie, którego model nie zdążył dokończyć.

Uwaga — max_tokens w środku tool_use

Gdy odpowiedź urwała się na limicie max_tokens w środku bloku tool_use, ponów żądanie z wyższym max_tokens, żeby dostać całe wywołanie2.

Przykład

Narzędzie dostaje długi tekst jako input, a max_tokens to 1024. Odpowiedź kończy się w połowie JSON-a. Zamiast wykonywać urwane wywołanie, ponów żądanie z większym limitem.

Pytania sprawdzające

Pierwszy blok odpowiedzi to tekst „Gotowe”, a stop_reason to tool_use. Czy pętla się kończy?

Nie. Claude często pisze tekst przed wywołaniem narzędzia; decyduje stop_reason, a tool_use znaczy, że czeka na wynik.

Dlaczego limit iteracji nie powinien być głównym sygnałem końca?

Bo przerywa zadania, które potrzebują więcej kroków. To bezpiecznik przed pętlą bez końca; koniec zadania wyznacza stop_reason.

Narzędzie zwróciło 2 MB tekstu. Co robisz?

Skracasz wynik u źródła (stronicowanie, filtrowanie, obcięcie), mówisz modelowi, że obcięto i jak dostać resztę, i odsyłasz to jako tool_result.

Claude poprosił o dwa narzędzia naraz. Jak odsyłasz wyniki?

Oba tool_result w jednej wiadomości użytkownika. Osobne wiadomości uczą Claude, żeby unikał równoległych wywołań.

Podsumowanie

  • Tekst w odpowiedzi nie znaczy „koniec”; decyduje stop_reason.
  • Limit iteracji to bezpiecznik, nie sposób kończenia zadań.
  • Każde wywołanie dostaje wynik — duży skróć u źródła i powiedz, że obcięto.
  • Wyniki równoległych wywołań idą razem, w jednej wiadomości.
  • Wywołanie urwane na max_tokens ponawiasz z wyższym limitem, nie wykonujesz.

Źródła

  1. Define tools — Claude Docssprawdzone 2026-11-02
  2. Stop reasons and fallback — Claude Docssprawdzone 2026-11-02
  3. Building effective agents — Anthropic Engineeringopublikowano 2024-12-19 · sprawdzone 2026-11-02
  4. Handle tool calls — Claude Docssprawdzone 2026-11-02
  5. Writing effective tools for AI agents — Anthropic Engineeringsprawdzone 2026-11-02
  6. Parallel tool use — Claude Docssprawdzone 2026-11-02