# API-Pagination für KI-Agenten: begrenzte Discovery Ein Agent, der einen Listenendpunkt ohne Seitenlimit aufruft, führt keine Discovery durch. Er startet einen offenen Remote-Aufruf und hofft, dass Rechnung, Rate-Limit und Ergebnismenge freundlich bleiben. Der gegenteilige Fehler ist genauso problematisch: Seite eins abrufen, eine plausible Antwort sehen und stillschweigend annehmen, dass sie das gesamte System abbildet. Pagination verändert, was ein Agent ehrlich behaupten kann. Ein zurückgegebener Datensatz beweist, dass dieser Datensatz existiert. Er beweist nicht, dass es keine weiteren gibt. Ein fehlender Datensatz sagt nur wenig aus, solange der Agent nicht zeigen kann, welchen Bereich er geprüft hat, auf welcher Sortierung die Suche beruhte und warum der Server das Ende angezeigt hat. Ich habe Agenten erlebt, die eine harmlose Anfrage wie «finde veraltete Zugriffstoken» in Tausende von Aufrufen verwandelten, weil niemand festgelegt hatte, wo Discovery endet. Ich habe auch erlebt, dass ein Inventar mit nur einer Seite zur Bereinigung von Konten führte, die auf Seite zwei standen. Die Lösung ist keine ausgefeilte Prompt-Formulierung. Gib dem Agenten einen begrenzten Traversierungsvertrag und sorge dafür, dass sein Abschlussbericht die Grenze sichtbar macht. ## Discovery-Aufrufe brauchen ein ausdrückliches Budget Jeder paginierte Discovery-Aufruf braucht Grenzen, die der Agent nicht stillschweigend ausweiten kann. Lege vor der ersten Anfrage eine maximale Seitenzahl, eine maximale Zahl zurückgegebener Datensätze, eine Frist und ein Rate-Limit-Budget fest. Die passenden Werte hängen von der Aufgabe ab, die Existenz solcher Grenzen jedoch nicht. Behandle Discovery als eigene Phase, getrennt von Aktionen. Während der Discovery sammelt der Agent IDs und Fakten. Er sollte Objekte nicht löschen, rotieren oder verändern, nur weil eine Seite etwas Verdächtiges enthält. Sobald genügend Belege vorliegen, kann er einen abgegrenzten Plan vorlegen oder eine separat autorisierte Aktionsphase beginnen. Ein sinnvoller Vertrag hat vier Bestandteile: - Den Endpunkt und alle Filter, einschließlich der Sortierreihenfolge, sofern die API eine solche erlaubt. - Eine Seitengröße und eine Obergrenze für Seiten oder Datensätze. - Eine von der API definierte Abschlussbedingung, etwa das Fehlen eines nächsten Cursors. - Eine Bedingung für den vorzeitigen Abbruch, zum Beispiel das Auffinden eines benannten Objekts oder das Ausschöpfen des Budgets. Verwechsle ein Datensatzlimit nicht mit einem Seitenlimit. Wenn der Dienst 100 Datensätze pro Seite erlaubt und der Agent auf 500 Datensätze begrenzt ist, können fünf Aufrufe genügen. Verringert der Dienst die effektive Seitengröße wegen Filtern oder Berechtigungen, kann dieselbe Aufgabe mehr Aufrufe benötigen. Eine gute Implementierung prüft beide Grenzen nach jeder Antwort. Wenn ein Agent beispielsweise ein Repository namens `billing-service` finden soll, kann er bei einem exakten Treffer aufhören, sofern Filter und Sortierung des Endpunkts diese Schlussfolgerung sicher machen. Soll er dagegen jedes Repository ohne Branch-Schutz identifizieren, darf er nicht beim ersten Treffer stoppen. Diese Aufgabe verlangt eine vollständige Aufzählung oder ein ausdrücklich als teilweise gekennzeichnetes Ergebnis. Das Wort «alle» sollte etwas kosten. Ein Agent darf es erst verwenden, wenn die Traversierung die vom Server definierte Abschlussbedingung erreicht, ohne sein Seiten-, Datensatz-, Zeit- oder Fehlerbudget zu überschreiten. Wird eine dieser Grenzen erreicht, muss der Bericht «teilweiser Scan» sagen und die Grenze nennen. ## Die Seitengröße steuert die Kosten, nicht die Vollständigkeit Der Parameter `limit`, `per_page` oder `page_size` teilt dem Dienst mit, wie viele Datensätze er in einer Antwort zurückgeben soll. Er sagt nicht, wie viel von der Sammlung der Agent prüfen muss. Der Maximalwert verringert zwar manche Umläufe, kann aber jede Antwort so teuer machen, dass ein Timeout eintritt, das Kontextbudget überschritten wird oder wichtige Details in einer großen Menge irrelevanter Daten untergehen. Beginne mit der kleinsten Seite, die die Entscheidung ermöglicht. Braucht ein Agent ein bestimmtes Konto, sind 20 kurze Datensätze meist besser als 1.000 vollständige Objekte. Muss er ein Inventar erstellen, verwende eine größere unterstützte Seitengröße erst, nachdem du bestätigt hast, dass der Endpunkt eine begrenzte und nützliche Darstellung zurückgibt. Felder sind genauso wichtig wie die Seitengröße. Viele APIs bieten `fields`, `include`, `expand` oder eine ähnliche Möglichkeit. Eine Discovery-Abfrage sollte IDs, Namen, Status, Zeitstempel und die eine Eigenschaft anfordern, die für die Entscheidung maßgeblich ist. Vollständige Details werden nur für Kandidaten abgerufen, die genauer geprüft werden müssen. Das verringert den Datenverkehr und gibt dem Modell weniger beiläufigen Text, den es falsch interpretieren könnte. Wenn der Anbieter Cursor-Pagination unterstützt, kann eine Anfrage so aussehen: ```http GET /v1/projects?state=active\u0026limit=50\u0026sort=id HTTP/1.1 Authorization: Bearer injected-by-gateway Accept: application/json ``` Die Antwort sollte Datensätze und Fortsetzungsstatus getrennt ausgeben: ```json { "data": [ {"id": "prj_104", "name": "billing-service", "state": "active"} ], "next_cursor": "eyJvcmRlciI6ImlkIiwicG9zIjoiMTA0In0" } ``` Der Agent sollte festhalten, dass er 50 Datensätze angefordert und einen erhalten hat. Aus dem kurzen Array darf er nicht auf das Ende schließen. Das einzige brauchbare Abschlusssignal in diesem Beispiel ist das Fehlen von `next_cursor` oder sein dokumentierter Nullwert. Vermeide eine willkürliche Regel wie «immer 100 verwenden». Die maximale Seitengröße unterscheidet sich je nach API. Manche Dienste rechnen außerdem eingebettete untergeordnete Objekte oder Antwort-Bytes gegen andere Limits. Fordere die dokumentierte Maximalgröße nur an, wenn die Aufgabe davon profitiert. Bei breiten Scans liefert eine mittlere Seitengröße oft bessere Zwischenstände, einfachere Wiederholungen und Berichte, die ein Mensch prüfen kann. ## Cursor als undurchsichtigen Serverstatus behandeln Ein Cursor ist kein Offset mit einem ausgefallenen Namen. Der Server bestimmt seine Bedeutung, und der Agent muss ihn Byte für Byte in die nächste Anfrage kopieren. Er kann eine Sortierposition, eine Snapshot-ID, eine Berechtigungsgrenze oder eine Signatur enthalten. Dass er wie Base64 aussieht, berechtigt niemanden dazu, ihn zu dekodieren, zu bearbeiten oder selbst zu erzeugen. Die sichere Schleife ist einfach: Fordere die erste Seite mit stabilen Filtern und Sortierparametern an, speichere den Cursor dieser Antwort und sende dieselbe Abfrage mit diesem Cursor erneut. Behalte alle ursprünglichen Parameter bei, sofern die API-Dokumentation nicht ausdrücklich etwas anderes sagt. Eine Änderung des Filters zwischen zwei Anfragen kann den Cursor ungültig machen oder, schlimmer noch, eine plausible, aber nicht zusammenhängende Ergebnismenge erzeugen. ```text request = { state: "active", limit: 50, sort: "id" } seen_ids = set() pages = 0 while pages < 10 and len(seen_ids) < 500: response = GET /v1/projects with request record response status, request, and response cursor for item in response.data: if item.id in seen_ids: report "duplicate record encountered" with item.id stop or apply the provider's documented recovery method seen_ids.add(item.id) pages += 1 if response.next_cursor is absent: report "complete" break request.cursor = response.next_cursor else: report "partial: traversal budget reached" ``` Die Prüfung auf Duplikate ist kein Schmuck. Veränderliche Sammlungen können sich verschieben, während der Agent sie durchläuft, und fehlerhafte Pagination-Implementierungen gibt es ebenfalls. Ein Duplikat bedeutet nicht immer, dass der Dienst fehlerhaft ist. Es bedeutet aber, dass der Agent nicht länger so tun sollte, als habe er eine saubere Aufzählung. Bietet der Anbieter ein Snapshot-Token, einen `as_of`-Parameter oder einen dokumentierten Konsistenzmodus, sollte der Agent dies für Aufgaben verwenden, die zu einer folgenreichen Aktion führen. Für den Ablauf eines Cursors braucht es eine ausdrückliche Regel. Manche Dienste lassen Cursor nur kurze Zeit gültig, andere binden sie an eine Sitzung oder machen sie ungültig, wenn sich die Abfrage ändert. Bei einer Antwort mit abgelaufenem Cursor sollte der Agent den Fehler bewahren und entweder mit einem stabilen Prüfpunkt neu beginnen oder den Scan als unvollständig beenden. Er darf nicht durch Raten eines neuen Cursors vorspringen. Auch ein Neustart kann ein falsches Gefühl von Vollständigkeit erzeugen. Wenn sich Datensätze zwischen dem ersten Durchlauf und dem Neustart geändert haben, kann eine zusammengeführte Liste Lücken oder Duplikate enthalten. Berichte über den Neustart und die Bedingung, mit der fortgesetzt wurde, etwa `created_at >= last_observed_timestamp`. Gibt es keine stabile Methode zur Wiederaufnahme, muss der Bericht festhalten, dass sich die Sammlung während der Traversierung verändert hat. Verwende das Ergebnis dann nicht als Löschliste. ## Offset-Pagination driftet bei veränderlichen Sammlungen Bei Offset-Pagination wird eine Zahl wie `offset=200\u0026limit=50` oder `page=5\u0026per_page=50` verwendet. Das lässt sich leicht skripten und erklären, weshalb diese Methode weiterhin verbreitet ist. Sie wird aber unzuverlässig, wenn neue Datensätze hinzukommen oder alte verschwinden, während der Agent die Sammlung durchläuft. Angenommen, Seite eins gibt bei absteigender Sortierung nach Aktualität die Datensätze 1 bis 50 zurück. Bevor der Agent Seite zwei anfordert, kommen zehn neue Datensätze hinzu. `offset=50` beginnt nun nach den neu eingefügten Datensätzen und überschneidet sich mit Objekten, die der Agent bereits gesehen hat. Wenn Datensätze dagegen aus Seite eins verschwinden, kann derselbe Offset Objekte überspringen, die nach oben gerückt sind. Durch das Entfernen doppelter IDs lässt sich das nicht beheben, denn damit werden Wiederholungen erkannt, aber keine Auslassungen. Wenn die API eine stabile Sortierung erlaubt, wähle eine deterministische Sortierung mit eindeutigem Tie-Breaker. `created_at` allein reicht oft nicht, weil mehrere Datensätze denselben Zeitstempel haben können. Eine Sortierung wie `created_at,id`, sofern der Anbieter sie dokumentiert, ermöglicht es dem Agenten, eine High-Water-Mark zu speichern und vorsichtiger fortzusetzen. Liefert die API nur einen Offset und weder Snapshot noch stabile Sortierung, sollten Schlussfolgerungen aus mehreren Seiten zurückhaltend ausfallen. Für eine Aufgabe, die eine vollständige Antwort verlangt, verwende diese Ansätze in absteigender Reihenfolge ihrer Verlässlichkeit: 1. Bitte den Dienst um einen Snapshot, einen Exportlauf oder einen Cursor, der eine stabile Ansicht dokumentiert. 2. Beschränke die Abfrage auf einen unveränderlichen Zeitraum und verwende eine dokumentierte stabile Sortierung. 3. Führe einen zweiten Scan durch, vergleiche die IDs und berichte über jede Abweichung. 4. Bitte einen Menschen, einen engeren, klar definierten Umfang freizugeben, statt eine breite Änderung vorzunehmen. Verwandle eine schlechte Schnittstelle nicht in einen destruktiven Ablauf. Ein Agent kann Offset-Seiten weiterhin zum Stichproben, zum Finden eines bestimmten Objekts oder für ein unvollständiges Inventar verwenden. Einen instabilen Offset-Scan darf er jedoch nicht als Beleg dafür verwenden, dass jedes passende Token, Projekt oder jeder passende Benutzer gefunden wurde. ## Der Abschluss muss aus dem Protokoll kommen, nicht aus einer Vermutung Verschiedene APIs geben den Pagination-Status an unterschiedlichen Stellen aus. Ein JSON-Body kann `next_cursor`, `has_more` oder eine URL für die nächste Seite enthalten. Andere APIs verwenden den HTTP-Header `Link`. RFC 8288 definiert Web Linking und den Parameter `rel`, der Beziehungen wie `next` bezeichnet. Der Header liefert eine Beziehung, aber keine Garantie, dass der Antwort-Body ein vertrautes Cursor-Feld enthält. Ein Agent braucht eine endpunktspezifische Abschlussregel. Schreibe sie neben die Definition der Anfrage. Zum Beispiel: «Abgeschlossen, wenn `next_cursor` null ist.» Oder: «Abgeschlossen, wenn keine Link-Beziehung mit `rel="next"` vorhanden ist.» Schreibe nicht: «Abgeschlossen, wenn weniger als 100 Datensätze zurückkommen.» Diese Abkürzung scheitert bei gefilterten Seiten, gekürzten Berechtigungen, Dienstlimits und APIs, die absichtlich unterschiedlich große Seiten zurückgeben. Ein typischer Link-Header kann so aussehen: ```http Link: ; rel="next", ; rel="first" ``` Der Agent sollte nur die Beziehung auswählen, die er versteht. Er darf den Header nicht einfach zusammenfügen, den `first`-Link nicht als sicher fortsetzbaren Prüfpunkt ansehen und aus einem fehlenden `last`-Link nicht folgern, dass es keine letzte Seite gibt. Die eigene Dokumentation der API bestimmt den Pagination-Vertrag. RFC 8288 beschreibt nur, wie Link-Beziehungen in HTTP-Headern übertragen werden. Manche APIs liefern `has_more: true` zusammen mit einer leeren Seite. Das klingt absurd, bis man auf einen Berechtigungsfilter, eine parallele Löschung oder einen verzögerten Index trifft. Dokumentiert die API dieses Verhalten, fahre mit dem Fortsetzungstoken fort, solange das Budget reicht, und protokolliere die leere Seite. Ist das Verhalten nicht dokumentiert, stoppe und kennzeichne die inkonsistente Pagination-Antwort. Ewig weiterzulaufen, weil `has_more` weiterhin wahr ist, ist ein Programmierfehler und keine Ausdauer. Unterscheide außerdem eine abschließende Antwort von einem erfolgreichen HTTP-Status. `200 OK` sagt, dass die konkrete Anfrage erfolgreich war. Es sagt nicht, dass die Sammlung endet. Ein `404` kann einen abgelaufenen Cursor, einen falschen Endpunkt oder eine verschwundene Ressource bedeuten. Bewahre Status, Antwort-Body und letzten Cursor im Laufprotokoll auf, damit ein Mensch erkennen kann, welcher Fall eingetreten ist. ## Ein Teilergebnis braucht eine Grenzerklärung Ein Agent sollte Discovery so berichten, wie ein sorgfältiger Operator einen Vorfallsbericht schreiben würde: Er muss angeben, was er angefragt, was er beobachtet und was er nicht geprüft hat. Die meisten schlechten Agentenberichte scheitern am letzten Punkt. Sie listen Ergebnisse auf, lassen aber den Cursor, das Limit oder den Fehler weg, der diese Ergebnisse unvollständig macht. Verwende ein Berichtsformat, mit dem ein Mensch handeln kann, ohne die Sitzung rekonstruieren zu müssen: ```text Scope: GET /v1/projects?state=active\u0026sort=id Requested page size: 50 Pages fetched: 10 Records received: 487 Completion: partial Stop reason: page budget reached Last continuation cursor: eyJvcmRlciI6ImlkIiwicG9zIjoiNTg3In0 Observed finding: 12 projects matched the review rule Uninspected scope: records after the last continuation cursor Action taken: none ``` Die letzte Zeile ist wichtig. Ein Discovery-Lauf sollte sagen, ob er etwas verändert hat. Ein Mensch, der den Bericht prüft, darf nie erschließen müssen, ob der Agent Objekte nur aufgelistet oder auch Aktionen ausgeführt hat. Gib einen sensiblen Cursor nicht in einem Chatprotokoll aus, wenn der Anbieter ihn als Bearer-Berechtigung behandelt oder sein Inhalt Kontostrukturen offenlegen kann. Speichere das exakte Token in geschützten Laufmetadaten und zeige im Bericht für Menschen einen Fingerabdruck oder ein gekürztes Präfix. Der Agent braucht genügend Status, um die Traversierung fortzusetzen oder zu prüfen. Menschen brauchen Fortsetzungstoken jedoch nicht verstreut in Tickets und Terminals. Die Wortwahl steuert hier das Risiko. «Ich habe in den ersten 500 geprüften Datensätzen keine passenden Einträge gefunden» ist korrekt. «Es gibt keine passenden Datensätze» ist erst nach einer vollständigen Traversierung unter einer ausreichend stabilen Ansicht korrekt. Der Unterschied klingt kleinlich, bis eine Bereinigungs- oder Compliance-Entscheidung davon abhängt. ## Rate-Limits und Wiederholungen brauchen eigene Abbruchregeln Pagination verstärkt Fehler bei Rate-Limits, weil aus einer einzelnen Anfrage eine Schleife wird. Ein Agent, der `429 Too Many Requests` erhält, sollte den Endpunkt nicht mit demselben Cursor bombardieren. Beachte `Retry-After`, wenn der Server es liefert, rechne die Wartezeit gegen die Frist des Laufs und stoppe, wenn das Wiederholungsbudget erschöpft ist. Bei vorübergehenden Fehlern wie einem Timeout oder einer `5xx`-Antwort muss dieselbe Seite vor dem Weitergehen wiederholt werden. Unterstützt die API bei Listenaufrufen eine Idempotenz- oder Anfrage-ID, verwende sie gemäß der Dokumentation. Gehe nach einer unsicheren Antwort niemals zum nächsten Cursor weiter, nur weil die Anfrage möglicherweise erfolgreich war. Dadurch entsteht eine stille Lücke. Eine begrenzte Wiederholungsrichtlinie könnte lauten: - Wiederhole die aktuelle Seite nach vorübergehenden Transport- oder Serverfehlern höchstens zweimal. - Beachte `Retry-After` bei Rate-Limits, wenn die verbleibende Frist dies zulässt. - Wiederhole Authentifizierungs- oder Autorisierungsfehler nicht ohne eine Änderung des Autorisierungsstatus. - Stoppe bei fehlerhaften Pagination-Daten, einem wiederholten Cursor oder einer undokumentierten Fortsetzungsantwort. Ein wiederholter Cursor verdient besondere Aufmerksamkeit. Wenn Seite drei denselben `next_cursor` zurückgibt, den der Agent gesendet hat, kann die Schleife unendlich weiterlaufen. Vergleiche jeden neuen Cursor mit dem gesendeten Cursor und mit einer Menge bereits verwendeter Cursor. Stoppe bei einer Wiederholung, sofern der Anbieter nicht ausdrücklich einen Fall dokumentiert, in dem Wiederholungen erwartet werden. Das ist selten und sollte mit einer anbieterspezifischen Regel behandelt werden. Der Agent sollte genügend Antwortmetadaten bewahren, um eine Wiederholung zu diagnostizieren, ohne Geheimnisse zu speichern. Protokolliere Statuscode, Anfragepfad, ausgewählte nicht sensible Header, Seitennummer, Cursor-Fingerabdruck, Zeitstempel und, sofern die Richtlinien es erlauben, einen Digest des Antwort-Bodys. Schreibe keine Authorization-Header, vollständigen Bearer-Tokens oder Zugangsdaten enthaltende URLs in Logs, nur weil eine Anfrage fehlgeschlagen ist. ## Ein Fehlerbeispiel zeigt, warum Seite eins gefährlich ist Stell dir einen Agenten vor, der jede inaktive Integration deaktivieren soll, die älter als ein bestimmtes Datum ist. Der Integrationsendpunkt verwendet standardmäßig 25 Einträge, sortiert nach dem Zeitpunkt der letzten Aktualisierung und liefert `next_cursor` nur, wenn weitere Seiten vorhanden sind. Der Agent ruft die erste Seite ab, findet drei inaktive Integrationen, deaktiviert sie und berichtet anschließend, er habe die inaktiven Integrationen bereinigt. Dieser Bericht ist in zweierlei Hinsicht falsch. Der Agent hat nicht jede Integration geprüft und während der Discovery eine Aktion ausgeführt. Die drei gefundenen Kandidaten sagen nichts über Seite zwei und die folgenden Seiten aus. Noch problematischer: Durch die Deaktivierung ändert sich `updated_at`. Wenn der Endpunkt nach diesem Feld sortiert, kann sich die Sammlung neu ordnen. Der Agent hat seine eigene Traversierung weniger stabil gemacht. Ein sicherer Lauf beginnt mit einem ausdrücklichen Filter und einer stabilen Sortierung, sofern die API dies unterstützt: ```http GET /v1/integrations?status=inactive\u0026updated_before=2024-01-01\u0026limit=50\u0026sort=id HTTP/1.1 ``` Der Agent sammelt die IDs seitenübergreifend, ohne die Objekte zu verändern. Er stoppt erst, wenn der Server keinen nächsten Cursor mehr liefert oder das Discovery-Budget greift. Anschließend berichtet er entweder eine vollständige oder eine teilweise Kandidatenmenge. Eine separate Aktionsanfrage kann die gesammelten IDs verwenden, idealerweise nachdem ein Mensch Anzahl und Umfang gesehen hat. Unterstützt der Listenendpunkt keine stabile Sortierung, sollte der Agent das sagen. Er kann weiterhin Kandidaten sammeln, darf aber keine vollständige und gegen Änderungen geschützte Menge behaupten. Der beliebte Rat «handle, sobald du Objekte findest» wirkt effizient, weil er einen zweiten Durchlauf spart. Bei veränderlichen Listen ist er falsch, wenn die Aktion Sortierposition, Berechtigung oder Eignung verändert. Dasselbe Muster gilt für Sicherheitsfunde, Benutzerkonten, Deployment-Datensätze und Build-Artefakte. Erst lesen und den Umfang feststellen, dann ändern. Ausnahmen gibt es bei dringender Eindämmung, etwa beim Widerruf eines konkret benannten kompromittierten Zugangsschlüssels. Das ist jedoch kein paginierter Bereinigungsjob, sondern eine gezielte Aktion mit einer bekannten ID. ## Zugangsdaten und Beobachtbarkeit außerhalb des Agenten halten Ein Agent sollte das API-Geheimnis nicht allein zum Paginieren benötigen. Die Komponente, die HTTP-Anfragen ausführt, kann Zugangsdaten einfügen, erforderliche menschliche Freigaben erzwingen und die tatsächliche Folge von Anfragen protokollieren. So konzentriert sich der Agent auf den Aufbau und die Interpretation der Abfrage, statt Tokens zu verwalten, mit denen er anderswo unbegrenzte Aufrufe ausführen könnte. Für Teams, die Sallyport verwenden, können HTTP-Aufrufe über das Action Gateway laufen, während die Zugangsdaten im verschlüsselten Tresor bleiben. Das Activity Journal protokolliert einzelne Aufrufe. Dieser Nachweis hilft einem Prüfer, die vom Agenten behauptete Seitenzahl mit den tatsächlich ausgeführten Anfragen zu vergleichen. Er ersetzt jedoch keine Seitenlimits in den Anweisungen des Agenten. Halte die Traversierungsrichtlinie nahe an der Aufgabendefinition. Lege erlaubte Endpunkte, Filter, Felder, maximale Seitenzahl, Wiederholungsverhalten und die erforderliche Grenzerklärung fest. Eine allgemeine Autorisierungsschicht kann nicht entscheiden, ob ein Scan nach einem Repository nach einer Seite vollständig ist oder ob ein Compliance-Inventar jede Seite benötigt. Sallyports Sitzungsjournal und die Aktivitätsspur pro Aufruf können Widerruf und Prüfung praktikabel machen, wenn ein Agentenlauf aus dem vorgesehenen Rahmen gerät. Trotzdem muss der Agent angewiesen sein, bei einer unbekannten Cursorform, einem erschöpften Budget oder einer API-Antwort zu stoppen, die dem dokumentierten Vertrag des Endpunkts widerspricht. Einen fehlerhaften Crawl nachträglich zu protokollieren ist besser als keinerlei Nachweis, macht unnötige Aufrufe oder eine falsche Aktion aber nicht rückgängig. ## Die Traversierung mit problematischen Pagination-Fixtures testen Ein reibungsloser Pagination-Verlauf verbirgt die wichtigen Fehler. Bevor du einem Agenten-Workflow vertraust, teste ihn mit Fixtures, die eine leere erste Seite mit Cursor, eine kurze Seite mit weiteren Ergebnissen, ein doppeltes Objekt, einen wiederholten Cursor, einen abgelaufenen Cursor und eine Rate-Limit-Antwort zwischen zwei normalen Seiten zurückgeben. Das erwartete Verhalten sollte unspektakulär und eindeutig sein. Der Agent setzt nach einer leeren Seite nur dann fort, wenn der dokumentierte Fortsetzungsstatus dies verlangt. Bei wiederholten IDs entfernt er Duplikate oder stoppt entsprechend der Konsistenzanforderung der Aufgabe. Nach einem Ablauf erfindet er niemals einen Cursor. Wenn ein Sicherheitslimit den Lauf beendet, berichtet er die teilweise Abdeckung. Verwende diese Abnahmetabelle zur Prüfung einer Aufrufschleife: | Fixture | Erwartetes Ergebnis | | --- | --- | | 12 Datensätze, kein nächster Cursor | Nach einer Anfrage vollständig | | 12 Datensätze, nächster Cursor vorhanden | Trotz der kurzen Seite fortsetzen | | Derselbe Cursor wird zweimal zurückgegeben | Stoppen und eine Pagination-Schleife melden | | `429` mit `Retry-After` | Nur innerhalb der Frist warten und die aktuelle Seite wiederholen | | Cursor als abgelaufen zurückgewiesen | Nur über einen dokumentierten Prüfpunkt neu starten oder Unvollständigkeit melden | Prüfe neben dem abschließenden Text auch die Rohaufrufe. Ein sauber formulierter Bericht kann einen übersprungenen Cursor oder eine zusätzliche Anfrage nach der Abbruchbedingung verbergen. Das Ausführungsprotokoll sollte eine erste Anfrage, jede Fortsetzungsanfrage, jede Wiederholung desselben Cursors und keine Aufrufe nach der abschließenden Antwort zeigen. Setze für explorative Arbeiten ein kleines Standardbudget und verlange für eine breite Aufzählung eine ausdrückliche Änderung der Aufgabe. Diese eine Einschränkung verhindert die beiden Fehler, die am meisten Zeit kosten: Agenten, die endlos scannen, und Agenten, die stillschweigend die erste Seite mit der vollständigen Antwort verwechseln.