Was ein Agent tun sollte, wenn seine Tools versagen

Sieben Fehlertypen und ihre Standardreaktion

Kapseln Sie jedes Tool so, dass es einen typisierten Fehler zurückgibt statt einer rohen Exception oder eines leeren Ergebnisses. Die Reaktion auf jeden Typ wird damit zu einer Designentscheidung, die Sie prüfen und testen können.

• Vorübergehender Lesefehler, etwa ein Timeout, ein 503 oder eine Antwort wegen Ratenbegrenzung: Retry mit Backoff innerhalb eines festen Budgets
• Schreibvorgang mit unbekanntem Ergebnis, etwa ein Timeout beim Buchen: vor jedem Retry das Zielsystem prüfen
• Ungültige Eingabe, etwa ein falsches Datumsformat: eine verwertbare Meldung an das Modell zurückgeben und wenige Korrekturen erlauben
• Fachliche Ablehnung, etwa eine geschlossene Buchungsperiode: kein technischer Fehler, also gilt die Prozessregel für diese Situation
• Unvollständige oder veraltete Daten: das Ergebnis nicht verwenden und wie einen fehlgeschlagenen Aufruf behandeln
• Zugriff verweigert: anhalten und melden, und den Agenten nie ein anderes Tool suchen lassen, das an dieselben Daten kommt
• Längerer Ausfall einer Abhängigkeit: den Fall mit gespeichertem Zustand parken und später fortsetzen

Retries gehören an genau eine Stelle

Der Artikel der Amazon Builders' Library zu Timeouts und Retries nennt Retries egoistisch: Jeder verbraucht mehr Kapazität der Abhängigkeit für eine bessere Erfolgschance. Er zeigt, wie sich Retries über mehrere Schichten vervielfachen: Macht jede von fünf Schichten drei Versuche, kann die unterste Ebene für eine einzige Anfrage 243 Aufrufe erhalten, drei hoch fünf. Empfohlen wird, an einer einzigen Stelle zu wiederholen, mit begrenztem exponentiellem Backoff und Jitter, und Client-Fehler in der Regel nicht zu wiederholen. Wenden Sie das pro Endpunkt an: Ungültige Eingaben oder eine fehlgeschlagene Autorisierung werden durch einen Retry nicht erfolgreich, aber eine Antwort 429 Too Many Requests zeigt eine Ratenbegrenzung an, und RFC 6585 erlaubt dazu einen Retry-After-Header mit der Wartezeit. Halten Sie sich an die Wartezeit, die der Anbieter dokumentiert.

Ein Agent fügt eine leicht übersehene Schicht hinzu: Das Modell selbst ruft das Tool nach einem Fehler womöglich erneut auf. Rechnen Sie diese Aufrufe auf dasselbe Budget an. Frameworks helfen bei der Mechanik. Die RetryPolicy von LangGraph dokumentiert zum Beispiel als Standard drei Versuche, ein Anfangsintervall von 0,5 Sekunden, einen Backoff-Faktor von 2 und Jitter und wiederholt HTTP-Fehler aus requests und httpx standardmäßig nur bei 5xx-Antworten. Prüfen Sie die Standardwerte Ihrer eingesetzten Version, statt sie vorauszusetzen.

Der Schreibvorgang mit Timeout

Ein Timeout bei einem Schreibvorgang sagt nur, dass keine Antwort kam. Die Buchung kann erfolgreich gewesen, gescheitert oder noch in Arbeit sein. Ein blinder Retry riskiert eine zweite Buchung. Gehen Sie stattdessen in dieser Reihenfolge vor:

1. 1

   Mit demselben Schlüssel wiederholen

   Nur wenn die Ziel-API dokumentiert, dass eine Wiederholung mit demselben Schlüssel dedupliziert und nicht erneut ausgeführt wird, wiederholen Sie mit dem ursprünglichen Schlüssel. Fehlt diese dokumentierte Zusage, gehen Sie zum nächsten Schritt.

2. 2

   Sonst zurücklesen

   Suchen Sie im Zielsystem nach einer mitgesendeten fachlichen Referenz, etwa der Fall-ID im Buchungstext, und gleichen Sie den Fall mit dem Befund ab, bevor Sie über eine Wiederholung entscheiden.

3. 3

   Wenn weiter unklar, anhalten

   Markieren Sie den Fall als Ergebnis unbekannt und übergeben Sie ihn an eine Person. Dieser Status braucht eine eigene Warteschlange, denn sowohl ein Retry als auch ein stilles Schließen können falsch sein.

Checkpoints im Agenten-Framework lösen das nicht. Sie halten den Fortschritt des Agenten fest, nicht, ob ein externes System die Änderung übernommen hat.

Unvollständige Daten müssen wie ein Fehler aussehen

Die schlimmsten Tool-Fehler sehen wie Erfolg aus: eine leere Liste, weil eine Suche intern in ein Timeout lief, die erste Ergebnisseite ohne Hinweis auf weitere, ein Datensatz mit fehlenden Feldern, die der Agent dann durch Raten füllt. Gestalten Sie Tool-Ergebnisse so, dass Vollständigkeit ausdrücklich erkennbar ist, mit Gesamtanzahl, Cursor für die nächste Seite und dem Zeitpunkt, zu dem die Daten gelesen wurden. Das Model Context Protocol erlaubt einem Tool, ein outputSchema zu deklarieren, gegen das Clients Ergebnisse prüfen sollen, und trennt Protokollfehler von Tool-Ausführungsfehlern mit isError, damit das Modell auf Letztere reagieren kann. Der Leitfaden von Anthropic zum Schreiben von Tools ergänzt, dass Fehlermeldungen sagen sollen, was zu korrigieren ist, statt undurchsichtige Codes zu liefern.

Parken, kompensieren und übergeben

Wenn eine Abhängigkeit ausfällt, kann ein Fall mit dauerhaft gespeichertem Zustand warten. LangGraph kann einen Lauf zum Beispiel an einer Schrittgrenze anhalten und später aus einem Checkpoint fortsetzen. Scheitert ein Fall auf halbem Weg, müssen erledigte Schritte unter Umständen rückgängig gemacht werden. Das Compensating-Transaction-Muster von Microsoft empfiehlt, zuerst zu wiederholen, nur zu kompensieren, wenn kein Fortschritt mehr möglich ist, jeden Kompensationsschritt idempotent zu gestalten und mit den Fehlerdetails zu alarmieren, wenn eine Person eingreifen muss.

Die Übergabe selbst sollte auflisten, was der Agent erledigt hat, was gescheitert ist, was unbekannt ist und was er als Nächstes getan hätte.

Fehlerbehandlung testen, bevor sie gebraucht wird

Bauen Sie Fehler gezielt in das Testset ein: eine Abfrage, die zweimal in ein Timeout läuft und dann antwortet, ein Schreibvorgang, der nach dem Ausführen in ein Timeout läuft, eine Suche, die eine von drei Seiten liefert. Prüfen Sie dann das Ergebnis, nicht nur, ob der Lauf endete. Ein guter erster Schritt ist eine kurze Tabelle mit jedem Tool des Agenten und der Bedeutung eines Timeouts für dieses Tool. Wo die Antwort bei einem Schreibvorgang lautet, dass es niemand weiß, fangen Sie an.