Rate-Limit der KI-Agenten-API: sichere Wiederholungen

Ein Agent, der ein Kontingent erreicht, sollte langsamer werden, jeden zusätzlichen Versuch erfassen und stoppen, bevor aus einer vorübergehenden Ablehnung ein größeres Betriebsproblem wird. «Bei einem Fehler wiederholen» ist für jemanden, der auf eine Schaltfläche klickt, ausreichender Rat. Für einen Prozess, der schneller Anfragen stellen kann, als ein Mensch sie überwacht, ist dieser Rat gefährlich.

Die Schwierigkeit besteht nicht darin, ein paar Sekunden zu warten. Entscheidend ist, die Bedeutung der ursprünglichen Aufgabe zu bewahren, wenn die erste Anfrage den Anbieter möglicherweise nicht erreicht hat, nachdem der Anbieter sie bereits ausgeführt hat oder weil mehrere Agentenläufe ein gemeinsames Kontingent erschöpft haben. Ein sicheres Design trennt diese Fälle und macht menschliches Eingreifen zu einem definierten Ergebnis statt zu einer peinlichen Ausnahme.

429 ist eine Anweisung zur Planung, kein Fehler, den man hartnäckig wiederholen sollte

HTTP 429 bedeutet, dass der Server die Anfrage ablehnt, weil der Client innerhalb eines vom Server kontrollierten Zeitraums zu viele Anfragen gesendet hat. RFC 6585 definiert den Statuscode und besagt, dass eine Antwort die Bedingung erklären und einen Retry-After-Header enthalten kann. Diese Formulierung ist wichtig: 429 sagt einem Agenten nicht, dass eine sofortige Wiederholung derselben Anfrage Erfolg verspricht.

Ein Agent sollte zunächst Anbieter, Endpunkt, Identität der Zugangsdaten oder des Kontos, Anfrageklasse, Antwortstatus und vorhandene Rate-Limit-Header erfassen. Danach sollte er die Arbeit in einen verzögerten Zustand versetzen. Lass das Sprachmodell diese Entscheidung nicht nach jedem Fehler in Prosa treffen. Die Transportschicht braucht deterministisches Verhalten, weil ein Modell unter Aufgabendruck oft einen ähnlichen Endpunkt ausprobiert, einen Filter ändert oder einen zweiten Anfragepfad erzeugt. Solche Improvisationen können die Zahl der Aufrufe vervielfachen und trotzdem dieselbe Ablehnung erzeugen.

Eine Ablehnung gilt häufig für einen größeren Bereich als nur die aktuelle Anfrage. Anbieter setzen Limits oft pro Konto, Projekt, Token, IP-Adresse, Endpunktfamilie oder nach einer Kombination dieser Kriterien. Ein Agent kann 429 erhalten, während ein anderer Agent mit denselben Zugangsdaten noch kurz weiterarbeitet. Das beweist nicht, dass der erste Agent sicher wiederholen kann. Es kann bedeuten, dass der Anbieter mehrere Kontingente führt oder dass der zweite Prozess die letzte verfügbare Kapazität verbraucht.

Führe für jeden bekannten Bereich ein lokales Register. Dokumentiert der Dienst ein Limit pro Token, gruppiere Anfragen nach Token. Gibt es nur Hinweise auf Kontoebene, gehe davon aus, dass alle Worker dieses Kontos dasselbe Kontingent teilen, bis Belege für das Gegenteil vorliegen. Ein lokales Register bildet den internen Zähler des Anbieters nicht perfekt ab, verhindert aber, dass deine Worker blind miteinander konkurrieren.

Die IETF-Spezifikation zu RateLimit-Feldern, RFC 9333, definiert RateLimit-Limit, RateLimit-Remaining und RateLimit-Reset. Diese Felder beschreiben den Zustand des Kontingents, machen eine bereits erhaltene 429-Antwort jedoch nicht ungeschehen. Nutze sie, um künftige Anfragen zu takten und zu verhindern, dass die Warteschlange schneller wächst, als der Anbieter sie annehmen kann. Lege ihren Geltungsbereich anhand der Dokumentation des Anbieters aus, denn ein Header allein zeigt möglicherweise nicht, ob er für einen Endpunkt oder ein ganzes Konto gilt.

Ein nützlicher Zustandsdatensatz sieht so aus:

{
  "provider": "billing-api",
  "scope": "account:ops-team",
  "request_class": "write:invoice",
  "next_allowed_at": "2025-04-08T14:12:31Z",
  "remaining": 0,
  "reset_after_seconds": 60,
  "source": "HTTP 429 Retry-After"
}

Der Agent-Runner sollte diesen Datensatz lesen, bevor er einen weiteren Aufruf ausführt. Bei einem kleinen Kommandozeilenlauf ist Warten innerhalb eines Request-Handlers akzeptabel. Sobald mehrere Worker, Tools oder fortgesetzte Aufgaben existieren, ist eine Warteschlange mit sichtbarem next_allowed_at besser. Der Scheduler kann dann andere Arbeiten auswählen, statt einen Prozess zu blockieren, und ein Operator erhält eine klare Erklärung für die Verzögerung.

Wiederholungsbudgets verhindern, dass ein kleiner Fehler zur Flut wird

Ein Wiederholungsbudget setzt eine harte Obergrenze für zusätzliche Arbeit, die eine Aufgabe nach einem fehlgeschlagenen Aufruf erzeugen darf. Zähle sowohl Versuche als auch verstrichene Wartezeit. Eine feste Anzahl allein reicht nicht, wenn der Dienst mehrere Minuten Wartezeit verlangt. Eine reine Zeitbegrenzung reicht nicht, wenn eine schnelle Schleife innerhalb von Sekunden das Kontingent eines Kontos aufbraucht.

Verwende getrennte Budgets für jede Aufgabe und jeden gemeinsam genutzten Anbieterbereich. Das Aufgabenbudget beantwortet: «Wie viel Unsicherheit kann dieses Ziel tolerieren?» Das Bereichsbudget beantwortet: «Wie viel Belastung dürfen alle aktuellen Arbeiten bei diesem Anbieter verursachen?» Wenn zehn Aufgaben jeweils drei Wiederholungen erhalten, können beim Konto trotzdem dreißig zusätzliche Anfragen ankommen. Genau so wird aus einer angeblich vorsichtigen Regel ein Anforderungsstoß.

Für gewöhnliche Leseanfragen verwende ich ein kleines Budget mit einer Frist, die kürzer ist als der geschäftliche Wert der Antwort. Bei Schreibvorgängen räume ich blinden Wiederholungen viel weniger Budget ein. Es kann günstiger sein, auf einen Menschen zu warten, als eine Zahlung zu duplizieren, doppelte Benachrichtigungen zu versenden oder ein Deployment zweimal auszuführen.

Formuliere die Regel als Daten, die der Agent nicht beiläufig überschreiben kann:

request_classes:
  read:
    max_attempts: 4
    max_wait_seconds: 90
    retry_statuses: [408, 429, 500, 502, 503, 504]
  idempotent_write:
    max_attempts: 3
    max_wait_seconds: 120
    retry_statuses: [408, 429, 502, 503, 504]
  uncertain_write:
    max_attempts: 1
    max_wait_seconds: 0
    retry_statuses: []
shared_scope:
  max_delayed_requests: 25
  max_concurrent_requests: 2

Dieses Fragment verhindert einen typischen Fehler: Ein Agent erhält nach dem Absenden einer Schreiboperation einen Timeout, nimmt an, dass nichts passiert ist, und sendet die Anfrage erneut an einen bereits belasteten Anbieter. Die Klasse uncertain_write erzwingt stattdessen eine Statusprüfung oder Eskalation. Sie belohnt den Agenten nicht für Beharrlichkeit, wenn diese das Ergebnis verändert.

Das Budget muss jeden tatsächlichen Versuch belasten, auch Wiederholungen von Bibliotheken. Ich habe erlebt, dass in einer Anwendung Wiederholungskontrollen definiert waren, während HTTP-Client, Workflow-Runner und Proxy darunter jeweils erneut versuchten. Die resultierende Zahl der Anfragen wirkte rätselhaft, bis jemand alle drei Voreinstellungen prüfte. Bestimme eine Schicht als Besitzer der Wiederholungen. Konfiguriere alle anderen Schichten so, dass sie Fehler ohne Wiederholung nach oben melden, oder mache ihr Verhalten explizit und rechne es in das Gesamtbudget ein.

Das Ausschöpfen des Budgets sollte ein finales Ergebnis mit Kontext erzeugen, keinen allgemeinen Fehler. Das Ergebnis sollte angeben, ob die ursprüngliche Anfrage gesendet wurde, ob eine Antwort einging, wie viele Versuche stattfanden, wie lange die Aufgabe wartete und was als Nächstes sicher ist. Der Agent kann dann mit unabhängigen Arbeiten fortfahren oder eine genaue Eskalation vorlegen, statt sich wiederholt selbst zum «Erneut versuchen» aufzufordern.

Backoff braucht Jitter und eine Obergrenze

Exponentielles Backoff verringert den Druck nach wiederholten Ablehnungen, indem die Abstände zwischen Versuchen größer werden. Jitter verhindert, dass viele gleichzeitig fehlgeschlagene Worker in derselben synchronisierten Welle zurückkehren. Beides gehört in den Client, selbst wenn der Anbieter eine Reset-Zeit veröffentlicht, weil die interne Nebenläufigkeit ihre eigene Anforderungswelle erzeugen kann.

Für die Versuchnummer n, wobei die erste Wiederholung n = 1 ist, berechne eine Obergrenze und wähle daraus eine zufällige Verzögerung:

import random

BASE_SECONDS = 1.0
MAX_SECONDS = 60.0

def retry_delay(attempt_number: int) -> float:
    cap = min(MAX_SECONDS, BASE_SECONDS * (2 ** attempt_number))
    return random.uniform(0, cap)

Das ist vollständiger Jitter. Er verhindert, dass jeder Worker genau 2, 4, 8 und 16 Sekunden wartet. Gleichbleibende feste Verzögerungen sind beliebt, weil sie Protokolle übersichtlich machen. Zugleich machen sie koordinierte Wiederholungen leicht vorhersehbar, also genau das Gegenteil dessen, was ein ausgelasteter Dienst braucht.

Wenn eine Antwort Retry-After enthält, hat dieser Wert Vorrang vor einer lokal berechneten kürzeren Verzögerung. RFC 9110 erlaubt Retry-After entweder als Verzögerung in Sekunden oder als HTTP-Datum. Verarbeite beide Formen. Liegt das Datum wegen einer abweichenden Uhr der Maschine bereits in der Vergangenheit, wende eine moderate Mindestverzögerung an, statt in eine enge Schleife zu geraten.

Verwende Backoff nicht als Ersatz für eine Ratensteuerung. Backoff beginnt nach einem Fehler. Ein Token-Bucket, Leaky-Bucket oder eine einfache Scheduler-Grenze steuert die Rate vor dem Fehler. Wenn ein Anbieter eine bekannte Zahl von Anfragen in einem bekannten Zeitraum erlaubt, takte die Anfragen unterhalb dieses veröffentlichten Limits und halte Kapazität für interaktive Arbeit frei. Der Scheduler sollte außerdem die Nebenläufigkeit begrenzen. Zwanzig gleichzeitige Anfragen können die Kapazität eines kurzen Intervalls aufbrauchen, bevor ein Worker eine Antwort mit RateLimit-Remaining liest.

Eine praktische Versandregel ist einfach: Prüfe vor dem Senden den Zeitpunkt des nächsten erlaubten Aufrufs im gemeinsamen Bereich und einen verfügbaren Nebenläufigkeitsplatz. Nach 429 aktualisiere den Bereichsdatensatz, bevor eine Wiederholung eingeplant wird. Diese Reihenfolge ist wichtig. Wenn Worker Wiederholungen einplanen, bevor sie die Ablehnung veröffentlichen, kann jeder annehmen, dass ihm der nächste Platz gehört.

Begrenze die Verzögerung und die gesamte Wartezeit. Eine unbegrenzte exponentielle Kurve kann eine Aufgabe stundenlang aufschieben und einen veralteten Lauf lange nach dem Ende seiner Annahmen aktiv halten. Der Agent sollte die Aufgabe nach Ablauf der Frist abbrechen oder an einen Scheduler übergeben und dabei die ursprüngliche Eingabe für eine spätere Prüfung bewahren.

Idempotenz entscheidet, ob eine Wiederholung sicher ist

Eine idempotente Anfrage hat bei einer Wiederholung dieselbe beabsichtigte Wirkung. Das bedeutet nicht, dass jede HTTP-PUT-Anfrage in jeder Anwendung harmlos ist, und auch nicht, dass jedes POST gefährlich ist. RFC 9110 beschreibt Methoden wie PUT und DELETE ihrer Absicht nach als idempotent, während POST im Allgemeinen nicht idempotent ist. Der tatsächliche API-Vertrag des Anbieters entscheidet über das Betriebsrisiko.

Leseanfragen vertragen Wiederholungen meist, sofern der Agent akzeptiert, dass sich die zurückgegebenen Daten geändert haben können. Auch eine Löschanfrage kann eine Wiederholung vertragen, wenn das Löschen einer bereits nicht vorhandenen Ressource ein bekanntes und akzeptables Ergebnis liefert. Das Anlegen einer Zahlung, Einladung, Supportanfrage, Bestellung oder eines Deployments verträgt blinde Wiederholungen oft nicht. Nach einem Timeout oder einer Verbindungsunterbrechung verdienen diese Aufrufe besondere Vorsicht.

In der Praxis werden zwei Zustände häufig vermischt:

• Eine Anfrage, die den Anbieter nachweislich nicht erreicht hat, kann erneut gesendet werden, wenn die Operation selbst dies erlaubt.
• Bei einer Anfrage mit unbekanntem Ergebnis muss zunächst ein Abgleich erfolgen, bevor der Agent eine weitere Nebenwirkung auslöst.

Ein Verbindungsfehler, nachdem der Client Bytes geschrieben hat, beweist nicht, dass der Anbieter untätig blieb. Der Server kann die Operation abgeschlossen und die Antwortverbindung verloren haben. Aus dem Ausbleiben einer Antwort darf der Agent das Ergebnis nicht ableiten.

Unterstützt ein Anbieter einen Idempotenzschlüssel, generiere ein stabiles Token pro logischer Aktion und verwende es für jede Wiederholung dieser Aktion erneut. Erzeuge nicht für jeden Versuch ein neues Token. Ein neues Token teilt dem Anbieter mit, dass jede Wiederholung eine eigene Operation ist, und hebt den Schutz damit auf.

POST /v1/transfers HTTP/1.1
Idempotency-Key: transfer-7c41b5b9-7f5b-4f51
Content-Type: application/json

{"source":"acct_17","destination":"acct_42","amount":12500,"currency":"USD"}

Speichere das Token zusammen mit Aufgabe und Anfrageinhalt, bevor du den ersten Aufruf sendest. Nach einem Neustart muss der Runner dasselbe Token wiederherstellen. Speichere außerdem die vom Anbieter zurückgegebene Operations-ID. Mit ihr kann eine spätere Abgleichsanfrage nach der ursprünglichen Aktion suchen, ohne sie neu zu erstellen.

Bietet die API keine Idempotenzfunktion, suche nach einem Muster aus Erstellen und anschließender Abfrage. Der Agent kann eine vom Client erzeugte externe Referenz in der Nutzlast mitsenden und nach einem unklaren Fehler anhand dieser Referenz suchen. Bietet die API weder Idempotenz noch eine verlässliche Suche, automatisiere keine wiederholten Schreibvorgänge. Lass einen Menschen die Datensätze des Anbieters prüfen. Das wirkt langsam, bis die erste doppelte Nebenwirkung in einem System landet, in dem sie sich nicht sauber rückgängig machen lässt.

Rate-Limits von Ausfällen und fehlerhaften Anfragen trennen

Eine Wiederholungsregel, die alle nicht erfolgreichen Status gleich behandelt, verbirgt Fehler und verschwendet Kontingent. Klassifiziere die Antwort, bevor du eine Verzögerung wählst. Statuscode, Antworttext, anbieterspezifischer Fehlercode und HTTP-Methode sind alle relevant.

Verwende diese praktische Aufteilung:

• 429 bedeutet: langsamer werden, Vorgaben des Anbieters beachten und das gemeinsame Rate-Limit-Budget belasten.
• 408, Verbindungsabbrüche und manche 5xx-Antworten können eine begrenzte Wiederholung rechtfertigen. Schreiboperationen brauchen jedoch weiterhin einen Idempotenz- oder Abgleichspfad.
• 400, 401, 403, 404 und 422 benötigen meist eine korrigierte Anfrage, geänderte Berechtigungen oder eine menschliche Entscheidung. Sie zu wiederholen ist Verschwendung.
• 409 braucht eine ressourcenspezifische Behandlung. Der Status kann ein Duplikat, einen Versionskonflikt oder eine von einem anderen Workflow gehaltene Sperre bedeuten.
• Ein anbieterspezifischer Fehler wegen erschöpftem Kontingent kann eine Wartezeit bis zu einer Abrechnungs- oder Tagesrücksetzung erfordern, was sich von einer kurzen Burst-Grenze unterscheidet.

Behandle 503 Service Unavailable nicht als austauschbare Form von 429. 503 sagt, dass der Dienst die Anfrage zu diesem Zeitpunkt nicht bedienen kann. 429 sagt, dass der Client ein Limit überschritten hat. Beide können Retry-After enthalten, aber 429 sollte den Scheduler dazu bringen, den lokalen Durchsatz für den betroffenen Bereich zu senken. 503 kann dagegen regional, endpunktspezifisch oder anbieterglobal sein. Bewahre den Unterschied in Metriken und Nachrichten für Operatoren.

Auch das Verhalten eines Agenten kann eine Welle ungültiger Anfragen auslösen. Ein Modell kann nach 422 wiederholt einen Endpunkt mit einem nicht unterstützten Filter aufrufen oder nach dem Widerruf der Zugangsdaten weiter 401 versuchen. Setze einen Circuit Breaker für wiederholte identische Fehler ein. Wenn etwa derselbe Endpunkt, dieselbe Methode und derselbe normalisierte Fehlercode in einem Lauf mehrmals fehlschlagen, stoppe diesen Pfad und gib die Fehlerdetails als Einschränkung an den Agenten zurück. Erlaube ihm nicht, Leerzeichen zu verändern, JSON-Felder neu zu ordnen und dies als neue Option auszugeben.

Ein normalisierter Anfrage-Fingerprint sollte Geheimnisse und veränderliche Header ausschließen. Enthalten sein sollten Methode, Endpunktvorlage, stabile Nutzlastfelder und API-Fehlercode. So kann der Runner eine Schleife erkennen, ohne Zugangsdaten oder vollständige sensible Inhalte zu protokollieren.

Gemeinsame Zugangsdaten brauchen eine Warteschlange, keine höflichen Agenten

Gemeinsam genutzte API-Zugangsdaten schaffen ein Koordinationsproblem, das einzelne Agenten nicht durch gute Absichten lösen können. Jeder Prozess sieht nur seine eigenen Anfragen, sofern ein Scheduler kein gemeinsames Budget bereitstellt. Backoff pro Agent senkt die Wahrscheinlichkeit eines Stoßes, verteilt ein knappes kontoweites Kontingent aber nicht fair.

Stelle eine ausgehende Warteschlange vor den Bereich mit den gemeinsamen Zugangsdaten. Weise Prioritäten bewusst zu. Eine von einem Menschen freigegebene Produktionsänderung kann Vorrang vor einer Inventaraufgabe im Hintergrund benötigen. Ein lang laufender Agent, der zehntausend Datensätze entdeckt, muss sie in der vom Anbieter erlaubten Rate seitenweise abrufen, statt alle Seitenanfragen auf einmal in die Warteschlange zu stellen.

Die Warteschlange braucht eine Abbruchfunktion. Wenn die übergeordnete Aufgabe eines Agenten endet, verwerfe seine verzögerten Anfragen, bevor sie aufwachen. Sonst kann eine beendete Aufgabe später weiterhin Kontingent verbrauchen und die Audit-Spur unverständlich machen. Beim Abbruch muss außerdem jeder reservierte Nebenläufigkeitsplatz freigegeben werden.

Verwende für sichere Lesevorgänge eine Regel zum Zusammenfassen von Anfragen. Wenn fünf Agentenläufe innerhalb eines kurzen Zeitraums denselben unveränderlichen Datensatz anfordern, führe eine Anfrage aus und verteile das Ergebnis an alle wartenden Aufgaben. Fasse keine Lesevorgänge zusammen, bei denen Aktualität die Bedeutung ändert, etwa einen Kontostand oder einen Freigabestatus. Es geht darum, versehentliche Duplikate zu entfernen, nicht um einen Cache zu bauen, der einem Agenten bei Entscheidungen veraltete Fakten liefert.

Rate-Limits weisen oft auf ein tieferes Planungsproblem hin. Ein Agent, der für jedes Element einmal einen Detailendpunkt aufruft, kann seine Anweisung exakt befolgen und trotzdem das falsche Zugriffsmuster verwenden. Suche vor dem Hinzufügen von Wiederholungen nach Batch-Endpunkten, Seitennavigation, bedingten Anfragen, Webhooks, Exportaufträgen oder einer serverseitigen Suchfunktion. Diese Änderungen verringern die Zahl der Aufrufe, bevor der Anbieter sie ablehnen muss.

Sallyport kann API-Zugangsdaten außerhalb des Agentenprozesses halten und zugleich einzelne ausgehende Aufrufe protokollieren. Der Aufrufer braucht trotzdem eine Warteschlange und Wiederholungskontrollen. Die Trennung der Zugangsdaten senkt das Risiko offengelegter Geheimnisse, verändert aber nicht das Kontingent des Anbieters.

Menschliche Eskalation muss die Unsicherheit bewahren

Ein Mensch sollte übernehmen, wenn das System nicht feststellen kann, ob eine Nebenwirkung eingetreten ist, wenn die verbleibende Wartezeit die Frist der Aufgabe überschreitet, wenn das gemeinsame Kontingent erschöpft ist oder wenn wiederholte Limits auf ein Konfigurationsproblem des Kontos hindeuten. Eine Eskalation ist keine allgemeine Meldung «API fehlgeschlagen». Sie ist eine kompakte Fallakte, mit der jemand entscheiden kann, ohne den Lauf aus verstreuten Protokollen rekonstruieren zu müssen.

Sende dem Operator diese Informationen:

• das gewünschte Ergebnis der Aufgabe und die genaue logische Aktion, die beendet wurde;
• Anbieter, Endpunkt, Methode, Kontobereich und bereinigten Anfrage-Fingerprint;
• Zeitpunkte der Versuche, Status, Retry-After- oder Rate-Limit-Header und verbrauchtes Budget;
• ob die Operation ein Idempotenz-Token, eine Operations-ID des Anbieters oder eine Abgleichsanfrage besitzt;
• die nächsten sicheren Optionen, etwa warten, Status abfragen, Kontingent erhöhen, den Plan ändern oder abbrechen.

Füge standardmäßig keinen rohen Anfrageinhalt in eine Freigabekarte ein. Er kann personenbezogene Daten, interne Dokumentinhalte oder einen Wert enthalten, der harmlos wirkt, bis er die falsche Person erreicht. Zeige eine knappe Zusammenfassung und mache den detaillierten Zugriff zu einer bewussten Audit-Aktion.

Eine Freigabe sollte eine Entscheidung anfordern und nicht bloß Zustimmung zum «Fortfahren». Bei einer unklaren Schreiboperation biete «Vorhandene Operation abfragen», «Mit demselben Idempotenz-Token wiederholen», «Abbrechen» und, sofern gerechtfertigt, «Neue Operation senden» an. Die letzte Option muss klar sagen, dass sie eine zweite Nebenwirkung erzeugen kann. Menschen entscheiden besser, wenn die Auswahlmöglichkeiten das tatsächliche Risiko beschreiben.

Eine Freigabe für den weiteren Zugriff und eine Freigabe für eine bestimmte externe Aktion sind unterschiedliche Kontrollen. Eine Sitzung kann weiterhin autorisiert sein, während ein Agent für eine Zahlung, eine Produktionsänderung oder eine erneute Anfrage nach einem Limit-Ereignis trotzdem eine Prüfung pro Aufruf benötigt. Halte diese Entscheidungen sowohl in der Oberfläche als auch im Protokoll getrennt.

Beginne bei der Prüfung einer Eskalation mit dem Abgleich. Frage den Anbieter nach Idempotenzschlüssel, externer Referenz oder Operations-ID. Wiederhole erst, wenn die Abfrage keine abgeschlossene Aktion zeigt oder der Anbieter die Unterdrückung von Duplikaten garantiert. Das ist eine Netzwerk-Rundreise langsamer als blindes erneutes Senden, aber schneller als die Reparatur eines Duplikats in einem nachgelagerten Hauptbuch.

Audit-Datensätze müssen Aktion und Wartezeit erklären

Ein nützlicher Audit-Datensatz beantwortet mehr als «Hat die Anfrage 200 zurückgegeben?». Er sollte zeigen, was der Agent versucht hat, welche Autorisierung dies erlaubt hat, was der entfernte Dienst zurückgab und wie der Wiederholungscontroller reagierte. Ohne den Entscheidungsdatensatz kann eine Folge von Aufrufen wie unvorsichtige Wiederholung aussehen, obwohl der Scheduler einen dokumentierten Retry-After-Wert befolgt hat.

Zeichne vor dem Versand ein Ereignis auf und hänge anschließend Ergebnis- und Planungsevents an. Halte die Anfrage-Metadaten frei von Zugangsdaten im Klartext. Eine kompakte Folge kann so aussehen:

14:11:02 action_requested  task=sync-482 method=POST route=/records
14:11:02 action_sent       attempt=1 idempotency=rec-91f2
14:11:03 action_result     status=429 retry_after=30 scope=account:ops
14:11:03 retry_scheduled   attempt=2 due=14:11:33 budget_wait=30
14:11:33 action_sent       attempt=2 idempotency=rec-91f2
14:11:34 action_result     status=201 provider_id=r_893

Diese Folge trennt eine logische Aktion von ihren Transportversuchen. Wenn ein Mensch fragt, warum zwei POST-Aufrufe erfolgt sind, zeigt der Datensatz, dass sie dasselbe Idempotenz-Token nutzten und eine vom Anbieter vorgegebene Verzögerung einhielten. Wäre die zweite Antwort ebenfalls in einen Timeout gelaufen, sollte das nächste Ereignis reconciliation_required und nicht ein weiteres automatisches action_sent sein.

Manipulationssichere Protokollierung hat bei der Untersuchung von Vorfällen einen praktischen Vorteil: Ein Team kann prüfen, dass ein Lauf unbequeme Versuche nicht nachträglich gelöscht hat. Sallyport erstellt seine Sitzungs- und Aufrufprotokolle aus einem verschlüsselten, hashverketteten Audit-Protokoll, und sp audit verify prüft die Kette offline, ohne einen Tresorschlüssel zu benötigen. Das hilft einem Operator, eine Drosselung durch den Anbieter von einer Agentenschleife oder einer verspäteten manuellen Wiederholung zu unterscheiden.

Auch Protokolle brauchen Aufbewahrungs- und Zugriffsgrenzen. Ein Anfragepfad, eine Kennung des Anbieter-Kontos und ein Zeitmuster können sensible Betriebsaktivitäten offenlegen, selbst wenn das Token nie erscheint. Erfasse genug, um die Entscheidung zu rekonstruieren, und begrenze dann, wer den Datensatz durchsuchen und exportieren darf.

Teste Fehlerpfade, bevor ein Agent sie in der Produktion entdeckt

Ein Rate-Limit-Design ist erst vollständig, wenn ein Test beweist, dass es Aufrufe stoppt, Idempotenz bewahrt und Unsicherheit eskaliert. Das Nachbilden einer einzelnen 429 reicht nicht. Du brauchst nebenläufige Worker und Fehler, die auftreten, nachdem der entfernte Dienst möglicherweise bereits gehandelt hat.

Führe diese Sequenz in einer Testumgebung oder gegen eine kontrollierbare Fake-API aus:

1. Starte drei Agentenaufgaben, die dasselbe simulierte Kontingent verwenden und dieselbe sichere Leseanfrage stellen.
2. Antworte auf die erste Anfrage mit 429 und Retry-After: 10. Prüfe anschließend, dass der Scheduler alle Arbeiten in diesem Bereich verzögert, statt die beiden anderen mit voller Geschwindigkeit fortfahren zu lassen.
3. Gib nach der Verzögerung Erfolg zurück und prüfe, dass sich die Wiederholungszeiten leicht unterscheiden, statt als ein einziger Stoß einzutreffen.
4. Sende eine Schreiboperation mit stabilem Idempotenz-Token, simuliere einen Verbindungsabbruch, nachdem die Fake-API den Datensatz gespeichert hat, und prüfe, dass der Runner den Status abfragt, statt eine neue Erstellung auszulösen.
5. Schöpfe das konfigurierte Zeitbudget aus und prüfe, dass der Operator den bereinigten Eskalationsdatensatz erhält und abgebrochene Arbeiten später nicht wieder aufwachen.

Miss ausgehende Versuche bei der Fake-API und nicht nur Funktionsaufrufe innerhalb des Agenten. Interne Zähler übersehen Wiederholungen von HTTP-Bibliotheken oder Wrappern. Teste auch einen Neustart: Stoppe den Runner nach der ersten unklaren Schreiboperation, stelle seinen gespeicherten Zustand wieder her und bestätige, dass er den Abgleich mit dem ursprünglichen Idempotenz-Token fortsetzt.

Belohne das Agenten-Testsystem nicht dafür, irgendwann eine erfolgreiche Antwort zu erhalten. Belohne es dafür, die richtige Zahl von Aufrufen auszuführen, auf Anweisung zu warten und eine unklare Schreiboperation offen zu lassen, bis Belege vorliegen. Ein Agent, der die Aufgabe durch das Duplizieren externer Aktionen «erledigt», hat den Test nicht bestanden.

Die erste Kontrolle, die du implementieren solltest, ist ein gemeinsames Wiederholungsbudget mit ausdrücklich definierten finalen Ergebnissen. So wird Rate-Limiting von einer Einladung zum Weiterprobieren zu einer betrieblichen Entscheidung mit Protokoll, Frist und einer Person, die eingreifen kann, wenn der entfernte Zustand unklar ist.