Flaga isError

Gdy narzędzie MCP zostaje uruchomione, mogą wydarzyć się dwie rzeczy: narzędzie zadziała albo wystąpi błąd. Model musi wiedzieć która z tych sytuacji nastąpiła — jasno i jednoznacznie — aby zdecydować, co zrobić dalej.

Jeśli niepowodzenie wygląda jak zwykły wynik, agent może potraktować bezwartościowe dane jak prawdę, zmyślić sposób odzyskania działania albo po cichu przejść dalej. Rozwiązaniem jest dedykowany sygnał niepowodzenia: flaga isError.

W tej lekcji dowiedzą się Państwo, jak poprawnie sygnalizować niepowodzenie, aby pętla agentowa mogła inteligentnie wybrać dalsze działanie zamiast zgadywać.

Wynik narzędzia zawiera wartość logiczną isError. Gdy isError ma wartość true, przekazują Państwo Claude informację: to narzędzie nie zwróciło prawidłowego wyniku — treść należy traktować jako raport o błędzie, a nie dane.

Jest to strukturalnie oddzielone od zwykłego wyniku narzędzia. Model może wybrać odpowiednią gałąź bez analizowania tekstu opisowego: ścieżkę powodzenia albo ścieżkę niepowodzenia. Właśnie na tym polega znaczenie tego rozdzielenia.

Klasycznym antywzorcem jest ogólny komunikat o błędzie, taki jak "Operation failed". Informuje on model, że coś poszło nie tak, ale nie zawiera żadnej informacji, na podstawie której można podjąć działanie.

Czy można spróbować ponownie? Czy dane wejściowe były nieprawidłowe? Czy użytkownik nie miał uprawnień? Czy są częściowe dane, które można wykorzystać? Ogólny komunikat nie odpowiada na żadne z tych pytań, więc agent zatrzymuje się albo improwizuje w niewłaściwy sposób.

Ogólne błędy blokują odzyskiwanie działania. Ustrukturyzowane błędy umożliwiają inteligentne kierowanie dalszym przebiegiem.

Poprawnie utworzony błąd MCP łączy isError: true z ustrukturyzowaną treścią. Pola wymagane w zadaniach egzaminacyjnych to:

• errorCategory — jedna z wartości transient, validation, business, permission
• isRetryable — czy to samo wywołanie może się powieść po ponowieniu?
• message — wyjaśnienie czytelne dla człowieka
• attempted_query — dokładny opis tego, co narzędzie próbowało zrobić
• partial_results — wszystkie użyteczne dane, które udało się zebrać

Razem pola te pozwalają modelowi zdecydować, czy ponowić próbę, przeformułować żądanie, eskalować problem czy kontynuować z częściowymi danymi.

Cztery kategorie nie są ozdobnikiem — każda wskazuje inne następne działanie:

• transient — tymczasowa usterka (przekroczenie limitu czasu, ograniczenie liczby żądań). Zwykle można ponowić próbę; problem należy rozwiązać lokalnie.
• validation — nieprawidłowe dane wejściowe. Nie należy bezmyślnie ponawiać próby; najpierw trzeba poprawić argumenty.
• business — naruszono regułę biznesową (np. zwrot przekracza limit określony w zasadach). Często wymaga to eskalacji, a nie ponowienia próby.
• permission — wywołujący nie ma dostępu. Ponowienie próby nie pomoże; należy eskalować problem lub poprosić o dane uwierzytelniające.

Kategoria zmienia niejasne niepowodzenie w instrukcję kierowania dalszym działaniem, za którą model może podążyć.

Na podstawie samego tekstu komunikatu często nie da się stwierdzić, czy warto ponowić próbę po niepowodzeniu. Należy wyraźnie określić to za pomocą isRetryable.

Przekroczenie limitu czasu (transient) można obsłużyć przez ponowienie próby. Nie dotyczy to nieprawidłowego argumentu (validation) — ponowienie tego samego błędnego żądania zakończy się kolejnym niepowodzeniem. Odmowy uprawnień nie można obsłużyć przez ponowienie próby bez nowych danych uwierzytelniających.

Bezpośrednie określenie isRetryable sprawia, że decyzje o ponawianiu prób są deterministyczne, zamiast zależeć od probabilistycznej interpretacji tekstu.

Gdy model decyduje, jak odzyskać działanie, musi wiedzieć, czego faktycznie próbowano. Dołączenie attempted_query pozwala agentowi inteligentnie przeformułować żądanie zamiast powtarzać to samo nieudane wywołanie.

Jest to element poprawnego propagowania błędów: ustrukturyzowany kontekst obejmuje typ niepowodzenia, wykonane zapytanie, częściowe wyniki i alternatywy. Im bogatszy kontekst, tym lepsze kierowanie procesem odzyskiwania działania.

Narzędzie może zakończyć się niepowodzeniem, a mimo to zebrać pewne użyteczne informacje. Wyszukiwanie w wielu źródłach może na przykład zwrócić 3 z 5 rekordów, zanim upłynie limit czasu dla czwartego źródła.

Zwrócenie partial_results razem z błędem pozwala agentowi kontynuować pracę z dostępnymi danymi, oznaczyć brakujące informacje i uniknąć rozpoczynania od zera. Odrzucanie częściowych danych przy każdym niepowodzeniu marnuje wykonaną pracę i pogarsza jakość odpowiedzi.

Trzeba rozróżnić dwie istotnie różne sytuacje: niepowodzenie dostępu i prawidłowy pusty wynik.

• isError: true — narzędzie nie mogło ukończyć działania (przekroczenie limitu czasu, odmowa dostępu, nieprawidłowe dane wejściowe). Można spróbować ponownie lub eskalować problem.
• isError: false z pustą treścią — narzędzie zadziałało poprawnie, a prawidłowa odpowiedź brzmi „brak dopasowań”.

Mylenie tych sytuacji jest częstym błędem: puste wyszukiwanie oznaczone jako błąd wywołuje bezcelowe ponowienia prób, natomiast prawdziwe niepowodzenie oznaczone jako pusty wynik ukrywa problem. Należy je wyraźnie rozdzielać.

Ustrukturyzowany sygnał wskazuje, gdzie powinno nastąpić odzyskanie działania. W systemie wieloagentowym podagent powinien lokalnie obsługiwać tymczasowe usterki — ponawiać próbę po przekroczeniu limitu czasu i ponownie wykonywać wywołanie — a przekazywać dalej tylko te błędy, których rzeczywiście nie może rozwiązać.

Gdy eskaluje problem, powinien przekazać ustrukturyzowany błąd wraz z częściowymi wynikami, aby koordynator mógł zdecydować, czy skierować sprawę gdzie indziej, poprosić o dodatkowe identyfikatory czy ujawnić brakujące informacje. Nie należy po cichu pomijać niepowodzenia ani przerywać całego przepływu pracy z powodu jednej usterki, którą można naprawić.

W module obsługi narzędzia MCP należy opakować wykonywaną pracę i w razie niepowodzenia zwrócić ustrukturyzowany błąd, zamiast pozwalać, aby wyjątek przedostał się jako ogólny komunikat tekstowy.

Proszę zauważyć, że każda gałąź ustawia isError, kategorię i wskazówkę dotyczącą ponowienia próby — dzięki temu pętla agentowa otrzymuje wszystkie informacje potrzebne do deterministycznego wybrania następnego kroku.

Najważniejsze wnioski dotyczące flagi isError:

• isError: true to strukturalny sygnał, że narzędzie nie zwróciło prawidłowych danych — jest oddzielony od zwykłego wyniku.
• Należy połączyć go z polami errorCategory (transient / validation / business / permission), isRetryable, message, attempted_query i partial_results.
• Ogólne błędy, takie jak „Operation failed”, blokują odzyskiwanie działania; ustrukturyzowane błędy umożliwiają inteligentne kierowanie dalszym przebiegiem.
• Należy odróżniać niepowodzenie dostępu od prawidłowego pustego wyniku — nigdy nie oznaczaj „brak dopasowań” jako błędu.
• Tymczasowe usterki należy obsługiwać lokalnie, a te, których nie można naprawić, eskalować wraz z częściowymi wynikami. Należy unikać cichego pomijania błędów oraz przerywania całego przepływu pracy z powodu jednej usterki.