Fehlerbehandlung für KI-Agenten: Retry, Timeout, Backoff und Circuit-Breaker-Muster

Ihr Agent ruft eine API auf. Die API gibt eine 429 zurück. Ihr Agent versucht es sofort erneut, erhält eine weitere 429, versucht es erneut, und nun haben Sie eine Schleife, die einen gedrosselten Dienst bombardiert, bis der Lauf stirbt oder die Rechnung explodiert. Niemand hat diese Schleife absichtlich geschrieben. Sie ergibt sich aus der naiven Version der „Fehlerbehandlung“, und es ist die häufigste Frage, die Entwickler auf dem Anthropic SDK Diskussionsforum stellen.

Die Fehlerbehebung ist der Teil des Agentenaufbaus, der eine saubere Demo von etwas trennt, wegen dem man jemanden alarmieren muss. Das Modell ist nicht das Problem. Das Problem ist, was Ihr Code tut, wenn ein Tool-Aufruf langsam, gedrosselt oder fehlerhaft zurückkommt. Wenn die Wiederherstellung richtig gemacht wird, wird eine wackelige Abhängigkeit zu einer kurzen Pause, die der Benutzer nie bemerkt. Wenn sie falsch gemacht wird, wird ein einziger 500er zu einem Vorfall. Dieser Leitfaden behandelt die vier Muster, die den Großteil der Last tragen: Wiederholungsversuche mit Backoff, Timeouts, Circuit Breaker und Idempotenzschlüssel. Anschließend wird gezeigt, wie man sie gegen einen Mock testet, bevor ein Benutzer die Lücken für Sie findet. Für ein umfassenderes Bild, wie Agenten scheitern, beginnen Sie mit warum KI-Agenten in der Produktion ausfallen.

Sie können die Wiederherstellung nicht gegen eine fehlerfreie API testen

Hier ist die Falle. Ihre Abhängigkeit funktioniert in der Entwicklung einwandfrei. Sie schreiben Ihren Agenten, die Aufrufe sind erfolgreich, die Demo ist sauber, und Sie liefern aus. Der Wiederherstellungscode lief nie, weil eine fehlerfreie API niemals die Fehler zurückgibt, die sie eigentlich behandeln sollte. Das erste Mal, dass Ihre Backoff-Logik läuft, ist in der Produktion, bei einem echten Ausfall, mit echten Benutzern, die zusehen. Das ist der schlimmste Ort, um einen Tippfehler in einer Wiederholungsschleife zu entdecken.

Die Regel ist also einfach. Um die Wiederherstellung zu testen, erzeugen Sie die Fehler absichtlich. Stellen Sie einen Mock der API bereit, die der Agent aufruft, programmieren Sie ihn so, dass er eine 429, eine 500, ein Timeout oder einen fehlerhaften Body zurückgibt, richten Sie den Agenten darauf und beobachten Sie, was er tut. Der Fehler wird zu etwas, das Sie in einem Test auslösen, anstatt zu etwas, das Sie um 3 Uhr morgens auslöst. Apidog erstellt diesen Mock und skriptet die Antworten, und es wird am Ende im Testabschnitt durchlaufen.

Wiederholung mit exponentiellem Backoff und Jitter

Ein Wiederholungsversuch ist die erste Verteidigungslinie, und die naive Version ist die Falle. Fangen Sie den Fehler ab, rufen Sie sofort erneut an. Gegen einen vorübergehenden Aussetzer funktioniert das. Gegen einen überlasteten Dienst verschlimmert es die Dinge, weil jeder fehlgeschlagene Client im selben Moment erneut versucht und der Ansturm den Dienst außer Betrieb hält.

Zwei Lösungen stapeln sich. Exponentielles Backoff verteilt die Versuche: Warte 1 Sekunde, dann 2, dann 4, dann 8, verdoppelt bis zu einer Obergrenze. Der Dienst bekommt Raum zur Erholung, anstatt einer Wand sofortiger Wiederholungsversuche. Jitter fügt jeder Wartezeit einen zufälligen Versatz hinzu, sodass tausend Clients, die alle im selben Moment fehlgeschlagen sind, nicht alle im selben Moment erneut versuchen. Ohne ihn erzeugt Backoff immer noch synchronisierte Wellen.

Begrenzen Sie zwei Dinge: die Verzögerung, damit Sie nicht Minuten zwischen den Versuchen warten, und die Anzahl der Versuche, damit ein dauerhafter Fehler aufgibt, anstatt für immer zu wiederholen. Drei bis fünf Versuche decken fast jeden vorübergehenden Fehler ab. Danach versuchen Sie normalerweise etwas erneut, das nicht erfolgreich sein wird. Das Anthropic SDK übernimmt einen Teil davon für seine eigenen Aufrufe: Es versucht Verbindungsfehler und spezifische Statuscodes mit exponentiellem Backoff erneut, und Sie legen die Obergrenze mit einer max-retries-Option fest. Es deckt nicht die anderen APIs ab, die die Tools Ihres Agenten treffen, daher müssen Sie diese selbst umschließen. Teams, die Geld über ihre Wiederholungen abwickeln, lernen dies früh, und unsere Aufschlüsselung der Wiederholungslogik für hochriskante APIs zeigt, wo eine sorglose Wiederholung echten Schaden anrichtet.

Legen Sie für jeden Aufruf ein Timeout fest

Ein Wiederholungsversuch hilft nur, wenn die Anfrage fehlschlägt. Der unangenehmere Fall ist eine Anfrage, die nie zurückkommt: Eine Abhängigkeit akzeptiert Ihre Verbindung und hängt dann. Ohne Timeout blockiert der Tool-Aufruf und der gesamte Lauf stockt hinter einem toten Socket. Kein Fehler, keine Wiederherstellung, nur ein feststeckender Agent, der Echtzeit und Token-Budget für nichts verbrennt.

Jeder ausgehende Aufruf benötigt ein Timeout. Legen Sie ein Verbindungs-Timeout für den Verbindungsaufbau und ein Lese-Timeout für das Warten auf die Antwort fest, dann ein Gesamtbudget für den gesamten Agentenlauf, damit eine Kette von langsamen, aber zulässigen Aufrufen die Geduld des Benutzers nicht überdauern kann. Wenn ein Timeout ausgelöst wird, behandeln Sie es wie jeden anderen wiederholbaren Fehler: Machen Sie einen Backoff und versuchen Sie es erneut, bis zu Ihrer Obergrenze.

Wählen Sie die Zahlen basierend auf der tatsächlichen Latenz, nicht auf einer Schätzung. Stellen Sie jedes Timeout über dem p99 der Abhängigkeit mit Puffer ein. Zu eng und Sie brechen Aufrufe ab, die erfolgreich gewesen wären. Zu locker und eine hängende Abhängigkeit bindet den Agenten weit über den Punkt der Nützlichkeit hinaus. Geben Sie Streaming-Antworten ihr eigenes Budget, da eine lange Fertigstellung legitim langsam ist und ein kurzes festes Timeout sie mitten im Stream beendet.

Lösen Sie einen Schutzschalter aus, wenn eine Abhängigkeit ausgefallen ist

Backoff handhabt einen Dienst, der kurzzeitig beschäftigt ist. Es ist das falsche Werkzeug für einen Dienst, der komplett ausgefallen ist. Wenn eine Abhängigkeit eine Minute lang fehlschlägt, wird die nächste Anfrage mit ziemlicher Sicherheit auch fehlschlagen, und ein erneuter Versuch belastet etwas, das bereits kaputt ist, zusätzlich, während der Benutzer auf einen Fehler wartet, den Sie hätten vorhersagen können.

Ein Schutzschalter behebt dies mit drei Zuständen. Geschlossen ist normal: Anfragen fließen und der Schalter zählt Fehler. Wenn Fehler eine Schwelle überschreiten, schaltet er auf offen: Er stoppt das Senden von Anfragen und schlägt schnell fehl für ein Abkühlungsfenster, sodass Sie das Timeout nicht bei jedem Aufruf eines toten Dienstes bezahlen. Nach dem Fenster geht er halb-offen und lässt eine einzelne Sonde durch. Wenn die Sonde erfolgreich ist, schließt der Schalter und der Verkehr wird fortgesetzt; wenn sie fehlschlägt, öffnet er sich wieder und wartet.

Für einen Agenten verwandelt der Schutzschalter „die Zahlungs-API ist ausgefallen“ in einen schnellen, sauberen Fehler, über den der Agent nachdenken kann, anstatt in vierzig langsame Timeouts, die das Token-Budget und die Zeit aufbrauchen. Verdrahten Sie ihn pro Abhängigkeit, nicht global, damit eine tote Such-API den Agenten nicht daran hindert, eine funktionierende Abrechnungs-API zu verwenden.

Wiederholungen mit Idempotenzschlüsseln sicher machen

Jedes bisherige Muster geht davon aus, dass ein erneuter Versuch sicher ist. Oft ist das nicht der Fall. Ihr Agent sendet POST /charge, der Server verarbeitet es, und die Antwort bricht auf dem Rückweg ab. Der Agent hat den Erfolg nie gesehen, also versucht er es erneut, und nun wird dem Kunden zweimal Geld abgebucht. Der erneute Versuch tat genau das, worum Sie gebeten haben. Das Design war der Fehler.

Ein Idempotenzschlüssel schließt die Lücke. Der Client generiert pro logischer Aktion einen eindeutigen Schlüssel und sendet ihn mit der Anfrage, normalerweise als Idempotency-Key Header. Der Server speichert den Schlüssel beim ersten Empfang und gibt, wenn er denselben Schlüssel erneut sieht, das ursprüngliche Ergebnis zurück, anstatt die Arbeit zweimal zu erledigen. Ein erneuter Versuch ist nun konstruktionsbedingt sicher: der zweite POST /charge mit demselben Schlüssel ist ein No-Op, der die erste Abbuchung zurückgibt.

Der Schlüssel muss über Wiederholungsversuche derselben Aktion stabil bleiben und sich zwischen verschiedenen Aktionen ändern. Generieren Sie ihn einmal, wenn Sie die Anfrage erstellen, nicht innerhalb der Wiederholungsschleife, sonst erhält jeder Versuch einen neuen Schlüssel und die Deduplizierung wird nie ausgelöst. Jeder Tool-Aufruf, der einen Zustand erstellt oder ändert (Abbuchungen, Bestellungen, E-Mails, Datensätze), benötigt einen. Unser Leitfaden zu Idempotenzschlüsseln behandelt die Generierung und serverseitige Handhabung vollständig.

Ratenbegrenzungen und die RateLimitError-Schleife überleben

Ratenbegrenzungen verdienen eine eigene Behandlung, da sie mit Anweisungen kommen. Eine Antwort bei überschrittener Ratenbegrenzung kommt normalerweise als 429 mit einem Retry-After Header an, der Ihnen genau sagt, wie lange Sie warten müssen, in Sekunden oder als Datum. Respektieren Sie dies. Wenn der Server sagt, warten Sie 30 Sekunden und Sie versuchen es in 2 Sekunden erneut, erhalten Sie eine weitere 429, und Sie haben die RateLimitError-Schleife gebaut, die das SDK-Diskussionsforum füllt: Limit abfangen, zu früh erneut versuchen, stärker begrenzt werden, wiederholen, bis der Lauf stirbt. Ein separater SDK-Thread behandelt dieselbe Hürde, auf die Entwickler hier stoßen.

Die Lösung besteht darin, den Server das Tempo bestimmen zu lassen. Wenn Sie eine 429 erhalten, lesen Sie Retry-After und warten Sie mindestens so lange, bevor Sie es erneut versuchen. Wenn der Header fehlt, greifen Sie auf exponentielles Backoff mit Jitter zurück. Begrenzen Sie die Versuche, sodass eine dauerhafte Begrenzung in einem sauberen Fehler statt in einem unendlichen Warten endet. Das Anthropic SDK berücksichtigt bereits Retry-After für seine eigenen Aufrufe; die Aufgabe besteht darin, dieselbe Regel auf die anderen ratenbegrenzten APIs anzuwenden, die Ihr Agent berührt.

Es gibt auch eine proaktive Seite. Wenn ein Anbieter eine festgelegte Anzahl von Anfragen pro Minute zulässt, messen Sie Ihre eigenen Aufrufe mit einem Token-Bucket, damit Sie unter der Obergrenze bleiben, anstatt sie durch Drosselung zu finden. Die Wiederherstellung handhabt die Limits, auf die Sie stoßen; die Taktung verhindert, dass Sie sie überhaupt erreichen.

So testen Sie den Wiederherstellungspfad

Nun setzen wir es zusammen. Die oben genannten Muster sind nur so gut wie Ihr Beweis, dass sie funktionieren, und der Beweis ist ein Test, der die Fehler erzwingt, die eine gesunde API Ihnen nicht geben wird. Die Form wiederholt sich in jedem Szenario:

1. Mocken Sie die Abhängigkeit. Erstellen Sie einen Mock der API, die das Tool Ihres Agenten aufruft, sodass Sie jeden Statuscode, Header, Body und jede Verzögerung steuern können und während des Tests keine echten Abbuchungen oder E-Mails ausgelöst werden.
2. Programmieren Sie eine Sequenz. Skripten Sie den Mock so, dass er eine Reihe von Aufrufen der Reihe nach beantwortet: zuerst eine 429 mit Retry-After: 2, dann eine 500, dann eine 200 mit einem gültigen Body. Ein Endpunkt, drei geskriptete Antworten, ein vollständiger Wiederherstellungsbogen in einem einzigen Lauf.
3. Führen Sie den Agenten zum Mock. Richten Sie das Tool des Agenten auf die Mock-URL anstelle des echten Dienstes und führen Sie das Szenario Ende zu Ende aus.
4. Verhalten überprüfen. Überprüfen Sie, was wichtig ist: Der Agent wartete mindestens 2 Sekunden nach der 429, bevor er es erneut versuchte, versuchte es nach der 500 erneut, war beim dritten Aufruf erfolgreich und überschritt niemals Ihr Versuchslimit.

Dieses eine Szenario beweist Backoff und Retry-After in einem einzigen Durchlauf. Fügen Sie ein zweites Szenario für den Abbruchpfad hinzu: Skripten Sie den Mock so, dass er jedes Mal fehlschlägt, und stellen Sie sicher, dass der Agent am Limit stoppt und einen sauberen Fehler zurückgibt, anstatt in einer Schleife zu laufen. Fügen Sie ein drittes für den Schutzschalter hinzu: Veranlassen Sie genügend aufeinanderfolgende Fehlschläge und stellen Sie sicher, dass der Agent auslöst und schnell fehlschlägt, anstatt bei jedem Versuch ein Timeout zu bezahlen.

Die Idempotenzprüfung ist diejenige, die die Leute überspringen, und sie ist diejenige, die Geld spart. Skripten Sie den Mock so, dass er einen mutierenden Aufruf akzeptiert, die Antwort verwirft, sodass der Agent denkt, er sei fehlgeschlagen, und dann den erneuten Versuch akzeptiert. Überprüfen Sie nun die Form der Anfrage: Beide Anfragen trugen denselben Idempotency-Key, und der Mock sah eine logische Aktion, nicht zwei. Ein neuer Schlüssel beim erneuten Versuch oder ein doppelter Aufruf bedeutet, dass Sie einen doppelten Versand gefunden haben, bevor ein Kunde es tat. Die umfassendere Methode zum Testen von Agenten, die Ihre APIs aufrufen, richtet das End-to-End-Gerüst ein.

Die Checkliste zur Fehlerbehebung

Bevor ein Agent in Produktion geht, gehen Sie diese Liste durch:

• Jeder ausgehende Aufruf hat ein Verbindungs-Timeout, ein Lese-Timeout und ein Gesamt-Laufbudget.
• Wiederholungsversuche verwenden exponentielles Backoff mit Jitter, begrenzt sowohl in der Verzögerung als auch in der Anzahl der Versuche.
• 429-Antworten lesen und respektieren Retry-After, mit Backoff als Fallback.
• Ein Schutzschalter löst pro Abhängigkeit aus, sodass ein toter Dienst schnell fehlschlägt, anstatt in einer Schleife zu laufen.
• Jeder statusändernde Aufruf trägt einen stabilen Idempotenzschlüssel, der Wiederholungsversuche überlebt.
• Der Abbruchpfad gibt einen sauberen Fehler zurück, keine unendliche Wartezeit.
• Jeder dieser Punkte wird durch einen Test, der den Fehler gegen einen Mock erzwingt, bewiesen, nicht angenommen.

Kreuzen Sie alle sieben Punkte an, und Ihr Agent erholt sich absichtlich, anstatt durch Glück.

Wo Apidog passt (und wo nicht)

Das gibt ihm drei Aufgaben. Es mockt die Abhängigkeiten, auf die Ihr Agent trifft, sodass Sie einen steuerbaren Ersatz anstelle des Live-Dienstes erhalten. Es programmiert die Fehlermeldungen (429 mit Retry-After, 500, Timeout, fehlerhafter Body), die eine echte API nicht auf Befehl erzeugen wird, sodass Sie die Wiederherstellung proben können. Und es validiert die Anfragen, die der Mock empfängt (Idempotenzschlüssel vorhanden und stabil, korrekte Form, erwartete Aufrufanzahl), sodass ein doppelter Versand oder ein fehlender Header einen Test fehlschlagen lässt anstatt einen Kunden. Das ist die ehrliche Passung: Apidog mockt die Fehler, die Ihr Agent überleben muss, und überprüft, was er zurücksendet.

Häufig gestellte Fragen

Übernimmt das Anthropic SDK die Wiederholungsversuche für mich? Für seine eigenen Aufrufe, ja. Das SDK versucht bestimmte Fehler mit exponentiellem Backoff erneut und berücksichtigt Retry-After, und Sie legen die Obergrenze mit einer max-retries-Option fest. Es deckt jedoch nicht die anderen APIs ab, die die Tools Ihres Agenten aufrufen. Diese erfordern die gleichen Muster, die von Ihnen angewendet werden.

Wann benötige ich einen Idempotenzschlüssel? Bei jedem Aufruf, der einen Zustand erstellt oder ändert: Abbuchungen, Bestellungen, gesendete Nachrichten, neue Datensätze. Nur-Lese-Aufrufe können ohne einen sicher erneut versucht werden. Generieren Sie den Schlüssel einmal pro Aktion, damit er bei Wiederholungsversuchen stabil bleibt.

Proben Sie diese Woche einen Fehler

Sie müssen nicht alle vier Muster gleichzeitig erstellen. Wählen Sie dasjenige aus, das am meisten schmerzen würde, normalerweise die Ratenbegrenzungsschleife oder ein nicht-idempotenter Wiederholungsversuch, und proben Sie es gegen einen Mock. Programmieren Sie die 429, lassen Sie eine Antwort fallen und beobachten Sie, was der Agent sendet. Das erste Mal, wenn Sie einen sauberen Backoff und einen einzigen Idempotenzschlüssel sehen, wo Sie eine doppelte Abbuchung befürchteten, werden Sie dem Agenten aus einem besseren Grund vertrauen als einer grünen Demo.

Laden Sie Apidog herunter, um die Fehler zu simulieren, die Sequenz zu skripten und zu überprüfen, was Ihr Agent tut, wenn die API Widerstand leistet.