Co powinien zrobić agent, gdy zawodzą jego narzędzia

Siedem typów błędów i domyślna reakcja na nie

Opakuj każde narzędzie tak, żeby zwracało typowany błąd zamiast surowego wyjątku albo pustego wyniku. Reakcja na każdy typ staje się wtedy decyzją projektową, którą można przejrzeć i przetestować.

• Przejściowy błąd odczytu, na przykład timeout, 503 albo odpowiedź o przekroczeniu limitu żądań: ponowienie z backoffem w ramach stałego budżetu
• Zapis o nieznanym wyniku, na przykład timeout podczas księgowania: przed jakimkolwiek ponowieniem sprawdź system docelowy
• Nieprawidłowe dane wejściowe, na przykład zły format daty: zwróć modelowi komunikat, na podstawie którego może działać, i pozwól na kilka poprawek
• Odrzucenie biznesowe, na przykład zamknięty okres księgowy: to nie błąd techniczny, więc obowiązuje reguła procesu dla takiej sytuacji
• Niepełne albo nieaktualne dane: nie korzystaj z wyniku i traktuj go jak nieudane wywołanie
• Brak uprawnień: zatrzymaj się i zgłoś to, nigdy nie pozwalaj agentowi szukać innego narzędzia, które dotrze do tych samych danych
• Dłuższa awaria zależności: odłóż sprawę z zapisanym stanem i wznów ją później

Ponowienia powinny być w jednym miejscu

Artykuł z Amazon Builders' Library o timeoutach i ponowieniach nazywa ponowienia egoistycznymi: każde zużywa więcej przepustowości zależności w zamian za większą szansę na sukces. Pokazuje, jak ponowienia na kilku warstwach się mnożą: jeśli każda z pięciu warstw wykonuje trzy próby, najniższa warstwa może dostać 243 wywołania dla jednego żądania, czyli trzy do potęgi piątej. Zaleca ponawianie w jednym miejscu, z ograniczonym wykładniczym backoffem i jitterem, oraz zasadniczo nieponawianie błędów klienta. Stosuj to dla każdego endpointu osobno: nieprawidłowe dane wejściowe albo nieudana autoryzacja nie powiodą się przy ponowieniu, ale odpowiedź 429 Too Many Requests oznacza ograniczenie liczby żądań, a RFC 6585 pozwala dołączyć do niej nagłówek Retry-After z czasem oczekiwania. Trzymaj się opóźnienia, które dokumentuje dostawca.

Agent dodaje warstwę, którą łatwo przeoczyć: sam model może po błędzie ponownie wywołać narzędzie. Wliczaj te wywołania do tego samego budżetu. Frameworki pomagają w mechanice. RetryPolicy w LangGraph dokumentuje na przykład domyślne trzy próby, początkowy odstęp 0,5 sekundy, współczynnik backoffu 2 i jitter, a błędy HTTP z requests i httpx domyślnie ponawia tylko dla odpowiedzi 5xx. Sprawdź wartości domyślne w wersji, której używasz, zamiast je zakładać.

Zapis, który przekroczył limit czasu

Timeout przy zapisie mówi tylko, że nie przyszła odpowiedź. Księgowanie mogło się udać, nie udać albo wciąż trwać. Ślepe ponowienie grozi drugim księgowaniem. Zamiast tego działaj w tej kolejności:

1. 1

   Ponów z tym samym kluczem

   Tylko jeśli docelowe API dokumentuje, że powtórzenie z tym samym kluczem jest deduplikowane, a nie wykonywane ponownie, ponów z pierwotnym kluczem. Bez takiej udokumentowanej gwarancji przejdź do następnego kroku.

2. 2

   W przeciwnym razie odczytaj stan

   Wyszukaj w systemie docelowym referencję biznesową, którą wysłałeś, na przykład identyfikator sprawy w opisie księgowania, i uzgodnij sprawę z tym, co znajdziesz, zanim zdecydujesz o powtórzeniu.

3. 3

   Jeśli nadal niejasne, zatrzymaj się

   Oznacz sprawę jako wynik nieznany i przekaż ją człowiekowi. Ten status potrzebuje własnej kolejki, bo zarówno ponowienie, jak i ciche zamknięcie mogą być błędem.

Checkpointy we frameworku agentowym tego nie rozwiązują. Zapisują postęp agenta, a nie to, czy system zewnętrzny wprowadził zmianę.

Niepełne dane muszą wyglądać jak błąd

Najgorsze błędy narzędzi wyglądają jak sukces: pusta lista, bo wyszukiwanie wewnętrznie przekroczyło limit czasu, pierwsza strona wyników bez znaku, że są kolejne, rekord bez pól, które agent uzupełnia potem na zgadywanie. Projektuj wyniki narzędzi tak, żeby kompletność była jawna: z łączną liczbą, kursorem do następnej strony i czasem odczytu danych. Model Context Protocol pozwala narzędziu zadeklarować outputSchema, względem którego klienci powinni walidować wyniki, i oddziela błędy protokołu od błędów wykonania narzędzia oznaczonych isError, żeby model mógł reagować na te drugie. Przewodnik Anthropic o pisaniu narzędzi dodaje, że komunikaty o błędach powinny mówić, co poprawić, zamiast zwracać nieczytelne kody.

Odkładanie, kompensacja i przekazanie

Gdy zależność nie działa, sprawa z trwale zapisanym stanem może poczekać. LangGraph potrafi na przykład zatrzymać przebieg na granicy kroku i wznowić go później z checkpointu. Gdy sprawa zawodzi w połowie, niektóre wykonane kroki trzeba czasem cofnąć. Wzorzec Compensating Transaction Microsoftu zaleca najpierw ponawiać, kompensować dopiero wtedy, gdy postęp jest niemożliwy, projektować każdy krok kompensacji jako idempotentny i alarmować ze szczegółami błędu, gdy musi wkroczyć człowiek.

Samo przekazanie powinno wymieniać, co agent wykonał, co się nie udało, co jest nieznane i co zrobiłby w następnej kolejności.

Testuj obsługę błędów, zanim będzie potrzebna

Celowo umieść błędy w zestawie testowym: wyszukiwanie, które dwa razy przekracza limit czasu, a potem odpowiada, zapis, który przekracza limit już po wykonaniu, wyszukiwanie zwracające jedną stronę z trzech. Potem sprawdzaj wynik, a nie tylko to, czy przebieg się zakończył. Dobry pierwszy krok to krótka tabela z każdym narzędziem agenta i tym, co dla niego oznacza timeout. Tam, gdzie przy zapisie odpowiedź brzmi, że nikt nie wie, zacznij pracę.