Baza wiedzy

Dlaczego agent AI nie działa — diagnostyka

„Agent nie działa” to nie diagnoza. Poniżej cztery najczęstsze objawy i kolejność sprawdzeń, która najszybciej prowadzi do przyczyny — zaczynając od najtańszych testów.

Opublikowano 2026-08-08 · Jakub Butryn, Founder · Lead engineer

Objaw: odpowiada, ale nie wykonuje zadań

Najpierw sprawdź, czy dostawca modelu przyjmuje narzędzia. Wyślij zapytanie z jednym prostym narzędziem i zobacz, czy odpowiedź zawiera wywołanie. Modele lokalne i część tanich końcówek nie obsługują tool-callingu — wtedy żadna zmiana promptu nie pomoże.

Jeśli narzędzia działają, sprawdź listę dozwolonych narzędzi i opisy parametrów. Brak `required` w schemacie kończy się wywołaniami z pustymi argumentami, które agent interpretuje jako porażkę i rezygnuje.

Objaw: gubi kontekst po kilku turach

Sprawdź zapełnienie okna kontekstu po każdej turze i to, co dopisujesz do historii. Typowy błąd: ręczne dopisywanie pary „pytanie/odpowiedź” obok mechanizmu, który już zapisał pełną turę razem z wynikami narzędzi. Historia się dubluje, a limit wyczerpuje dwa razy szybciej.

Drugi typowy błąd: kompresja, która wycina wyniki narzędzi. Model traci wtedy podstawę decyzji i zaczyna powtarzać kroki.

Objaw: zapętla się albo powtarza ten sam krok

Zwykle brakuje limitu iteracji i wykrywania powtórzeń. Dodaj twardy limit kroków na turę i porównuj kolejne wywołania narzędzi — dwa identyczne pod rząd oznaczają, że narzędzie nie zwraca użytecznego wyniku.

Sprawdź też, co wraca z narzędzia przy błędzie. Wynik „” albo cały traceback jednakowo utrudniają modelowi decyzję. Krótki komunikat „co się nie udało i co zrobić dalej” zwykle przerywa pętlę.

Objaw: milczy, wisi albo kończy się nagle

Kolejność: token i autoryzacja (czy 401 nie jest maskowane timeoutem), sieć (czy klient ma timeouty i ponawianie z backoffem), limity kosztu (czy budżet nie został wyczerpany), procesy potomne (czy serwery narzędzi nie zostawiają otwartych potoków przy wyjściu).

Zawsze zaglądaj do dziennika. Agent bez dziennika działań jest niediagnozowalny — w ZAZA-CODE każde uruchomienie pisze do `~/.config/zaza/logs/zaza.log`, a użytkownik widzi tylko czytelny komunikat.

Najczęstsze pytania

Agent AI odpowiada, ale nie używa narzędzi — co sprawdzić?

Po kolei: czy dostawca modelu obsługuje tool calling, czy narzędzia są na liście dozwolonych, czy schematy mają wymagane parametry. Najczęstszą przyczyną jest pierwszy punkt, nie prompt.

Gdzie szukać przyczyny awarii agenta AI?

W dzienniku działań: co agent wywołał, z jakimi argumentami i co dostał w odpowiedzi. Agent bez dziennika jest niediagnozowalny — to pierwsza rzecz do dodania przed nowymi funkcjami.

Omów swój przypadek — konsultacja bezpłatna Telegram @sotius