Antywzorzec: ogólne komunikaty o błędach

Narzędzie w pętli agenta zwraca:

{ "status": "error", "message": "Operation failed" }

Model musi teraz zdecydować: ponowić próbę, użyć innego zapytania, eskalować sprawę do człowieka czy się zatrzymać. Jednak „Operation failed” nie przekazuje żadnych informacji. Nie wiadomo, czy baza danych była chwilowo niedostępna, dane wejściowe miały nieprawidłowy format, czy działanie zablokowała reguła biznesowa.

To antywzorzec ogólnego błędu — po cichu obniża niezawodność agentów.

W pętli agenta model analizuje każdy wynik narzędzia i wybiera kolejne działanie. Decyzja dotycząca odzyskiwania zależy od tego, jaki rodzaj błędu wystąpił:

• Przejściowa awaria → wykonaj lokalnie ponowną próbę
• Nieprawidłowe dane wejściowe → popraw zapytanie i wywołaj ponownie
• Naruszenie reguły biznesowej → NIE ponawiaj próby; eskaluj lub zakończ działanie
• Odmowa dostępu → eskaluj

Ogólny komunikat sprowadza wszystkie cztery przypadki do jednej nierozróżnialnej informacji. Model musi zgadywać — często ponawia próbę wykonania czegoś, co nigdy się nie powiedzie, albo przerywa cały przepływ pracy z powodu błędu, który można było obsłużyć.

Rozwiązaniem jest ustrukturyzowany kontrakt błędu. Wynik narzędzia MCP powinien w przypadku błędu zawierać:

• isError: true — jednoznaczną flagę błędu
• errorCategory — jedną z wartości transient, validation, business, permission
• isRetryable — informację, czy ponowna próba może przynieść efekt
• message — szczegóły czytelne dla człowieka
• attempted_query — informację, co narzędzie faktycznie próbowało wykonać
• partial_results — wszystkie zebrane dotychczas użyteczne wyniki

Każde pole odpowiada bezpośrednio decyzji dotyczącej odzyskiwania, którą model może teraz podejmować w sposób deterministyczny.

Najważniejszym pojedynczym polem jest errorCategory. Informuje ono model, którą gałąź drzewa odzyskiwania wybrać:

• transient → ponów próbę lokalnie w subagencie (chwilowy problem z siecią, przekroczenie limitu czasu)
• validation → dane wejściowe były nieprawidłowe; popraw argumenty i wywołaj ponownie
• business → reguła zablokowała operację (np. zwrot przekracza limit); ponowna próba nie ma sensu — eskaluj
• permission → wywołujący nie ma dostępu; eskaluj i nigdy nie zapętlaj działania

Komunikat „Operation failed” zmusza model do wywnioskowania kategorii na podstawie tekstu, o ile w ogóle jest to możliwe. Typowana kategoria eliminuje zgadywanie.

Ogólny błąd sprzyja niebezpiecznemu zachowaniu: bezrefleksyjnemu ponawianiu prób. Model ponownie wywołuje narzędzie, które zakończyło się błędem, znów otrzymuje „Operation failed” i może zużywać kolejne iteracje na operację, która nigdy się nie powiedzie.

Jednoznaczna flaga isRetryable zamienia zgadywanie w regułę. Model ponawia próbę tylko w przypadku przejściowych błędów, a błędy biznesowe i związane z uprawnieniami natychmiast kieruje na inną ścieżkę.

Proszę pamiętać: limity iteracji to siatka bezpieczeństwa, nigdy podstawowy mechanizm zatrzymywania. To klarowne sygnały błędów faktycznie utrzymują pętlę pod kontrolą.

Istnieje subtelna pułapka: ogólny błąd zaciera różnicę między „nie udało mi się sprawdzić” a „sprawdziłem i niczego nie znalazłem”.

• Awaria dostępu (przekroczenie limitu czasu, błąd uwierzytelniania) → dane mogą istnieć; ponów próbę lub eskaluj.
• Poprawny pusty wynik (zero pasujących wierszy) → odpowiedź rzeczywiście brzmi „brak wyników”; NIE ponawiaj próby.

Jeśli oba przypadki są sygnalizowane jako „Operation failed”, model może bez końca ponawiać próbę dla pustego zbioru albo zrezygnować w przypadku możliwej do usunięcia awarii. Ustrukturyzowany kontrakt zachowuje rozróżnienie między tymi dwoma wynikami.

Błędy rzadko mają charakter całkowicie pomyślny albo całkowicie niepomyślny. Koordynator badań korzystający z wielu agentów może rozesłać zapytania do pięciu źródeł, z których jedno przekroczy limit czasu. Zwrócenie samego komunikatu „Operation failed” odrzuca cztery źródła, które zadziałały poprawnie.

Uwzględnij partial_results, aby model mógł zsyntetyzować dostępne informacje i opisać brak, zamiast przerywać działanie. Zasada architekta brzmi: przejściowe błędy obsługuj lokalnie, a gdy musisz eskalować, eskaluj z dołączonymi częściowymi wynikami — nigdy nie ukrywaj ich po cichu i nie przerywaj całego przepływu pracy z powodu jednej nieudanej gałęzi.

Gdy błąd wynika z walidacji, model musi wiedzieć, co wysłał, aby to poprawić. Pole attempted_query odtwarza dokładnie przekazane dane wejściowe.

Odzwierciedla to ponawianie próby z informacją zwrotną w przypadku ustrukturyzowanych danych wyjściowych: błędy formatu i struktury naprawia się, przekazując modelowi pierwotne żądanie, dokładny błąd oraz informacje o podjętej próbie. Mając do dyspozycji attempted_query, model może wykryć nieprawidłowy SKU lub błędny filtr daty i poprawić kolejne wywołanie — zamiast powtarzać to samo wadliwe żądanie.

Ustrukturyzowane błędy sprawiają, że odzyskiwanie przez model jest inteligentniejsze, ale nadal obsługuje je model probabilistyczny. W przypadku błędów o konsekwencjach finansowych, prawnych lub związanych z bezpieczeństwem należy połączyć je z deterministycznym egzekwowaniem reguł.

Hak PostToolUse może sprawdzić wynik narzędzia, zanim model go zobaczy, a hak outgoing-call może zablokować działanie naruszające zasady (np. zwrot przekraczający 500 USD) z 100% determinizmem. Polecenia i ustrukturyzowane sygnały pomagają w około 90% przypadków; haki gwarantują pozostałe. Ustrukturyzowane błędy umożliwiają inteligentne kierowanie — nie zastępują twardych zabezpieczeń.

Zwykle nie trzeba tworzyć tego kontraktu od zera. W przypadku standardowych integracji preferuj dobrze utrzymywane serwery MCP społeczności zamiast własnych — często już zwracają skategoryzowane błędy, dla których można ponawiać próbę.

Jeśli tworzysz własne narzędzie, opisz kontrakt błędów w opisie narzędzia, obok przeznaczenia, wartości zwracanych, formatów danych wejściowych i przypadków brzegowych. Dobry opis informuje model nie tylko, jak wywołać narzędzie, lecz także jak interpretować jego wynik, gdy coś pójdzie nie tak.

Istotny jest jeszcze jeden aspekt niezawodności: znaczenie ma to, gdzie w kontekście pojawia się błąd. Modele zwracają największą uwagę na początek i koniec kontekstu, a najmniejszą na jego środek („zagubienie w środku”).

Dlatego oprócz ustrukturyzowania błędów należy zadbać o ich zwięzłość: ogranicz rozwlekły wynik narzędzia do odpowiednich pól i wyeksponuj sygnał błędu, zamiast ukrywać errorCategory w ścianie śladu stosu. Zwięzły, typowany błąd umieszczony blisko punktu decyzyjnego jest lepszy niż rozwlekły komunikat zagłuszony szumem.

Ogólne błędy, takie jak „Operation failed”, uniemożliwiają odzyskiwanie, ponieważ ukrywają jedną informację, której model potrzebuje najbardziej — jaki rodzaj błędu wystąpił.

• Zwracaj ustrukturyzowane błędy: isError, errorCategory (transient/validation/business/permission), isRetryable, message, attempted_query, partial_results.
• Kategoria wyznacza kierowanie: ponawiaj próbę w przypadku błędów przejściowych, popraw dane przy błędach walidacji, eskaluj błędy biznesowe i związane z uprawnieniami.
• Odróżniaj awarię dostępu od poprawnego pustego wyniku.
• Przekazuj dalej częściowe wyniki; nigdy nie ukrywaj ich po cichu ani nie przerywaj całego przepływu pracy z powodu jednej gałęzi.
• W przypadku konsekwencji finansowych, prawnych lub związanych z bezpieczeństwem wspieraj ustrukturyzowane błędy deterministycznymi hakami.

Ustrukturyzowane błędy zamieniają ślepą uliczkę w inteligentną decyzję dotyczącą odzyskiwania.