Sollten Bulk-API-Operationen ihre Ziele zuerst anzeigen?

Ein AI-Agent darf eine vage Anfrage wie «inaktive Konten archivieren» niemals in einen unbeschränkten Schreibaufruf verwandeln. Bevor er viele Datensätze ändert, sollte er die genaue Zielmenge zeigen, die angezeigte Auswahl bewahren und eine Bestätigung verlangen, die nur für diese Auswahl gilt.

Das klingt übertrieben, bis ein fehlerhafter Filter zum ersten Mal einen aktiven Kunden, einen Test-Mandanten oder ein Konto trifft, für das jemand eine Ausnahme vorgesehen hat, die im Ticket nicht erwähnt wurde. Menschen können denselben Fehler machen. Ein Agent kann die Anfrage jedoch mit Maschinengeschwindigkeit senden und nach dem ersten falschen Ergebnis weitermachen. Entscheidend ist keine höfliche Warnung vor der Anfrage. Entscheidend ist eine überprüfbare Grenze zwischen der Entscheidung, wer betroffen ist, und der Änderung dieser Datensätze.

Eine Anzahl beschreibt den Wirkungsbereich nicht

Eine Anzahl sagt, wie viele Datensätze eine Operation betrifft. Sie sagt nicht, welche. «482 Abonnements» kann plausibel klingen und trotzdem einen Enterprise-Mandanten, gesperrte Konten, die aus rechtlichen Gründen bestehen bleiben müssen, oder Datensätze in einer Region enthalten, die in der Anfrage nicht genannt wurde.

Verlange ein Zielmanifest. Bei einer kleinen Operation kann es jede ID mit ausreichend Kontext enthalten, damit ein Prüfer Fehler erkennt. Bei einer größeren Operation sollte die vollständige Liste in einer exportierbaren Prüfoberfläche erscheinen, ergänzt um nützliche Gruppierungen wie Status, Mandant, Region oder Besitzer. Lass Menschen die Zugehörigkeit nicht allein aus einem Filtertext ableiten.

Ein gutes Preview beantwortet fünf konkrete Fragen:

• Welche API-Ressource und welche Umgebung erhalten den Schreibaufruf?
• Welcher Selektor hat diese Menge erzeugt?
• Welche Datensätze gehören zur Menge, identifiziert durch stabile IDs und verständliche Felder?
• Welche Mutation erhält jeder Datensatz?
• Welche Datensätze wurden durch eine ausdrücklich genannte Regel ausgeschlossen?

Der letzte Punkt fängt einen unangenehmen Fehler ab: Eine Anfrage kann technisch korrekt sein und trotzdem gegen die Absicht verstoßen, weil eine versteckte Ausnahme nie im Selektor gelandet ist. Sagt der Bediener «alle unbezahlten Rechnungen außer den bestrittenen», sollte das Preview den Ausschluss der bestrittenen Rechnungen sichtbar ausweisen. Schweigen lässt den Prüfer raten, ob der Agent die Ausnahme verstanden oder vergessen hat.

Verwechsle ein Stichproben-Preview nicht mit einem Manifest. Die ersten 20 Datensätze eines Updates mit 10.000 Einträgen zu zeigen, beweist nur sehr wenig. Stichproben helfen, offensichtliche Probleme zu erkennen. Die gespeicherte Auswahl muss jedoch jeden Datensatz umfassen, der geändert werden kann.

Preview und Commit müssen an dieselbe Auswahl gebunden sein

Ein Preview ist nur dann aussagekräftig, wenn der Commit nachweisen kann, dass er auf der geprüften Menge arbeitet. Zeigt ein Agent um 14:00 Uhr eine Suche an und führt dieselbe Suche um 14:05 Uhr vor dem Schreiben erneut aus, kann eine andere Population betroffen sein. Neue Datensätze können in den Filter gelangen, bestehende ihren Status ändern und die Pagination kann die Reihenfolge verändern.

Am sichersten ist ein serverseitiger Snapshot der Auswahl. Der Preview-Endpunkt gibt eine Auswahl-ID, ihre Gültigkeitsdauer, die Anzahl der Mitglieder und eine Revision oder einen Digest zurück. Der Commit-Endpunkt akzeptiert diese Auswahl-ID und lehnt sie ab, wenn der Snapshot abgelaufen oder verändert ist.

POST /v1/subscriptions/selections
Content-Type: application/json

{
  "filter": {
    "status": "past_due",
    "region": "eu",
    "exclude_tags": ["disputed", "legal_hold"]
  },
  "fields": ["id", "customer_name", "status", "amount_due", "tags"]
}

Eine sinnvolle Antwort sieht etwa so aus:

{
  "selection_id": "sel_7f2c",
  "expires_at": "2025-03-08T15:00:00Z",
  "count": 482,
  "digest": "sha256:4c76...",
  "records": [
    {"id":"sub_104","customer_name":"Northwind Parts","status":"past_due","amount_due":3100,"tags":[]},
    {"id":"sub_219","customer_name":"Orchard Studio","status":"past_due","amount_due":450,"tags":[]}
  ]
}

Das Array records kann über einen Cursor geliefert werden. Die Auswahl-ID muss sich aber auf die vollständige eingefrorene Mitgliedschaft beziehen, nicht nur auf die aktuelle Seite. Die Prüfoberfläche kann durch das Ergebnis blättern, ohne das geprüfte Objekt zu verändern.

Nach der Genehmigung sendet der Agent die gespeicherte Auswahl statt des ursprünglichen Filters:

POST /v1/subscriptions/bulk-actions
Content-Type: application/json
Idempotency-Key: 9b03c6f0-7dfa-4f22-b0e5-4b52ca4f1a51

{
  "selection_id": "sel_7f2c",
  "expected_digest": "sha256:4c76...",
  "action": {"type": "pause_collection", "reason": "approved credit hold review"}
}

Der Server sollte einen nicht passenden Digest mit einer Konfliktantwort ablehnen. Eine erfolgreiche Anfrage sollte eine Aktions-ID und Ergebnisverweise pro Datensatz zurückgeben, nicht nur {\"ok\": true}. Eine pauschale Erfolgsmeldung verschleiert Teilabschlüsse, die bei Bulk-Arbeit der normale Fehlerfall sind.

Kann die Vendor-API keine Snapshots erstellen, kann der Agent die Operation trotzdem binden: durch das Speichern einer geordneten ID-Liste, das Hashen einer kanonischen Darstellung und das Senden dieser ID-Liste an den Schreib-Endpunkt. Das hat Grenzen: URL- und Body-Limits, veraltete Datensätze und APIs, die nur einen Filter akzeptieren. Tu in diesen Fällen nicht so, als wäre die Kontrolle gleichwertig. Erzeuge unmittelbar vor jedem begrenzten Batch ein neues Preview und stoppe, sobald sich die Mitgliedschaft unterscheidet.

Stabile Pagination entscheidet über den Wert der Prüfung

Offset-Pagination ist eine schlechte Grundlage für eine Genehmigungsentscheidung bei veränderlichen Daten. Angenommen, der Agent listet Seite eins auf und sieht die Datensätze 1 bis 100. Danach archiviert ein anderer Prozess 20 Datensätze am Anfang. Fragt der Agent anschließend Offset 100 ab, kann er Datensätze überspringen, die nach oben gerückt sind. Neue Einträge können außerdem Duplikate verursachen. Die geprüfte Anzahl kann weiterhin normal aussehen, während sich einzelne Mitglieder verändert haben.

Verwende einen vom Service ausgegebenen Cursor und frage den API-Anbieter, ob dieser Cursor aus einem Snapshot liest. Ein Cursor, der lediglich eine Sortierposition codiert, kann trotzdem abweichen, wenn sich das sortierte Feld ändert. Die Sortierung nach einem veränderlichen Feld wie updated_at ist besonders problematisch, wenn die geplante Aktion diesen Zeitstempel selbst aktualisiert.

Wenn du die API kontrollierst, solltest du diese Eigenschaften ausdrücklich anbieten:

• Eine Snapshot-ID oder einen unveränderlichen High-Water-Mark.
• Eine deterministische Sortierung nach einer unveränderlichen ID.
• Eine Ablaufzeit, die ein neues Preview erzwingt, statt stillschweigend neuere Daten zurückzugeben.
• Ein Antwortfeld, das angibt, ob der Aufrufer aus einem konsistenten Snapshot liest.

RFC 9110 stuft Methoden wie POST, PUT, PATCH und DELETE als unsicher ein, weil sie den Serverzustand verändern können. Diese Einstufung ist noch kein Workflow-Design. Sie unterstützt aber eine praktische Regel: Behandle einen Listen-Endpunkt gefolgt von einer unsicheren Methode nicht als eine einzige atomare Operation, nur weil der Code beide Aufrufe direkt nacheinander ausführt.

Bietet eine externe API weder stabile Cursor noch Auswahl-Snapshots, verringere den Umfang, bis jemand jede Anfrage prüfen kann. Es ist verlockend, die Einschränkung mit einem agentenseitigen Cache und einer langen Schleife zu umgehen. Damit entsteht oft eine zweite Datenbank ohne Transaktionsgrenze und ohne verbindliche Antwort für den Fall, dass ein Datensatz während des Laufs verschoben wird.

Die Genehmigung muss die Mutation beschreiben, nicht nur die Datensätze

Ein Prüfer muss sowohl die Mitgliedschaft als auch die Wirkung genehmigen. «Änderungen auf 482 Datensätze anwenden» sagt nichts aus, wenn die Oberfläche nicht angibt, ob Datensätze gelöscht, deaktiviert, neu zugewiesen, belastet, veröffentlicht oder einzelne Felder verändert werden. Zeige für jedes zu ändernde Feld den bisherigen und den geplanten neuen Wert. Wenn alle Werte dieselbe Änderung erhalten, reicht zusätzlich eine kurze Zusammenfassung.

Unterscheide absolute von bedingten Schreibvorgängen. Ein absolutes Schreiben sagt status = archived, unabhängig davon, was seit dem Preview passiert ist. Ein bedingtes Schreiben sagt: «Archivieren, aber nur wenn der Status weiterhin inaktiv und die Version weiterhin 17 ist.» Bedingte Schreibvorgänge sind meist sicherer, weil sie die Änderung ablehnen, wenn jemand anderes den Datensatz verändert hat.

Verwende, sofern die API das unterstützt, bei jeder Mutation eine Version, ein ETag oder eine zuletzt bekannte Revision. Das ersetzt das Zielmanifest nicht. Es löst ein anderes Problem: Ein geprüfter Datensatz kann beim Start der Ausführung bereits nicht mehr zulässig sein.

Ein kompakter Genehmigungsdatensatz kann so aussehen:

{
  "request_id": "req_91a8",
  "selection_id": "sel_7f2c",
  "selection_digest": "sha256:4c76...",
  "target_count": 482,
  "action": {
    "type": "pause_collection",
    "precondition": {"status": "past_due"}
  },
  "approved_by": "operator account identifier",
  "approved_at": "2025-03-08T14:16:02Z"
}

Lass einen Agenten diese Genehmigung nicht für eine andere Aktion gegen dieselbe Menge wiederverwenden. Zahlungseinzüge zu pausieren, Gutschriften auszustellen und Datensätze zu löschen hat unterschiedliche Folgen, selbst wenn die Zielliste identisch ist. Binde die Genehmigung neben dem Auswahl-Digest auch an eine kanonische Darstellung der Aktion.

Zeitlimits sind wichtig. Eine Genehmigung, die gültig bleibt, bis der Agent sich für ihre Verwendung entscheidet, verwandelt einen kurzen Moment menschlicher Prüfung in eine dauerhafte Berechtigung. Gib Genehmigungen eine kurze, zur Operation passende Gültigkeit, entwerte sie bei einer veränderten Auswahl und verlange eine neue Entscheidung, sobald der Agent die Aktion wesentlich verändert.

Teilabschlüsse brauchen ein Protokoll und eine Stop-Regel

Jede Bulk-Operation stößt irgendwann auf ein Rate Limit, einen Timeout, einen Validierungsfehler oder eine unterbrochene Verbindung. Gefährlich ist, den gesamten Job erneut zu starten, ohne zu wissen, welche Datensätze bereits geändert wurden. Das führt zu doppelten Belastungen, wiederholten Benachrichtigungen oder einem irreführenden Audit-Trail.

Weise der angeforderten Aktion eine Operations-ID und einen Idempotency-Key zu. Protokolliere das Ergebnis jedes Ziels: erfolgreich, fehlgeschlagen, übersprungen, weil sich eine Vorbedingung geändert hat, oder unbekannt, weil der Service kein dauerhaftes Ergebnis zurückgegeben hat. «Unbekannt» ist nicht dasselbe wie «fehlgeschlagen». Behandle diesen Status vor einem erneuten Versuch als Untersuchungsfall.

Lege die Stop-Regel vor der Ausführung fest. Eine sinnvolle Regel kann nach einem strukturellen Fehler stoppen, etwa bei einer fehlenden Berechtigung oder einer unerwarteten Schema-Antwort, während einzelne Validierungsfehler für eine spätere Prüfung gesammelt werden. Vermeide eine allgemeine Einstellung «bei Fehler fortfahren». Sie verwandelt eine nicht erkannte Änderung am API-Vertrag in eine lange Liste beschädigter Datensätze.

Betrachte einen typischen Fehler. Ein Agent erstellt ein Preview für 800 Benutzerkonten, deren Rolle geändert werden soll, und beginnt anschließend eine Schleife auf Clientseite. Die ersten 300 Anfragen sind erfolgreich. Eine Bereitstellung verändert den Endpunkt, sodass ein fehlendes Feld nun standardmäßig die Administratorrolle statt der vorgesehenen Betrachterrolle setzt. Die nächste Antwort sieht erfolgreich aus. Läuft die Schleife weiter, breitet sich der Fehler aus. Protokolliert der Agent die Form jeder Antwort und stoppt, sobald der Vertrag von der genehmigten Aktion abweicht, endet der Wirkungsbereich bei der ersten ungewöhnlichen Antwort.

Plane bei destruktiven Arbeiten die Kompensation vor der Ausführung. Eine Ausgleichsanfrage braucht den vorherigen Wert für jeden Datensatz, nicht das vage Versprechen, jemand könne die Änderung später rückgängig machen. Auch dann solltest du ein Rollback nicht als harmlos betrachten. Eine spätere legitime Änderung kann eine blinde Umkehr falsch machen, und externe Nebenwirkungen wie E-Mails oder Exporte lassen sich möglicherweise überhaupt nicht zurücknehmen.

Lesezugriff kann so viel offenlegen wie ein fehlerhafter Schreibzugriff

Teams verlangen oft eine sorgfältige Bestätigung beim Löschen, aber keine bei der Auswahl. Dabei kann ein Agent eine vollständige Kundenliste, private Adressen, Zahlungsstatus oder interne Notizen abrufen, um sein Preview zu erstellen. Das Preview sollte genug Daten zeigen, damit ein Mensch Datensätze erkennt, aber nicht jedes Feld, das die zugrunde liegende API anbietet.

Verlange bewusst eine begrenzte Feldmenge. Stabile ID, Anzeigename, Status, Verantwortlicher und die für die geplante Änderung relevanten Werte reichen meist aus. Halte Geheimnisse, Tokens, Freitextnotizen und nicht zugehörige personenbezogene Daten aus der Auswahlantwort heraus. Das macht die Prüfung übersichtlicher und verringert, was der Agent in späteren Nachrichten wiederholen kann.

Dasselbe Prinzip gilt für Filter. Ein Agent darf eine Abfrage nicht erweitern, nur weil er ein Feld mangels Berechtigung nicht prüfen kann. Kann er nicht nachweisen, ob ein Datensatz zur Auswahl gehört, sollte er die Unklarheit anzeigen und auf die Entscheidung eines Menschen warten. Raten ist keine operative Beurteilung.

Behandle die Umgebung als Teil des Manifests. Produktion, Staging und eine Sandbox können identische Ressourcennamen verwenden. Stelle den Ziel-Host oder die Konto-ID neben die Zielanzahl und die Zusammenfassung der Aktion. Ingenieure haben schon eine völlig vernünftige Datensatzliste für die falsche Umgebung genehmigt, weil das Preview die Umgebung wie ein nebensächliches Detail behandelte.

Agenten brauchen Autorität über den Aufruf, nicht Besitz der Zugangsdaten

Ein Agent mit einem weitreichenden API-Token kann den Bulk-Aufruf senden, bevor jemand die Zielmenge gesehen hat. Du kannst diesen Aufbau mit Prompts und Logs umgeben, aber die Zugangsdaten geben dem Prozess weiterhin einen Ausweg. Bewahre die Zugangsdaten bei einem Aktionsausführer auf, der die Anfrage genehmigen oder ablehnen kann, bevor sie die externe API erreicht.

Sallyport verfolgt diesen Ansatz für unterstützte HTTP- und SSH-Aktionen: Der Agent fragt über seine MCP-Verbindung an, während die App die Zugangsdaten behält und die Aktion ausführt. Die Autorisierung pro Sitzung und die optionale Schlüsselgenehmigung pro Aufruf passen zu einem Workflow, in dem ein Agent eine Bulk-Anfrage vorbereiten darf, aber keine wiederverwendbaren Geheimnisse erhalten soll.

Diese Genehmigung ist nicht das gesamte Sicherheitskonzept für Bulk-Arbeit. Eine Genehmigungskarte für einen HTTP-Aufruf kann einem Prüfer nicht sagen, ob ein Filter 10 oder 10.000 Datensätze liefert, sofern der Agent nicht zuvor ein Zielmanifest erstellt und bewahrt hat. Nutze das Gateway zur Kontrolle der Berechtigung. Der Anwendungs-Workflow muss anschließend Preview, Auswahl, Genehmigung und Commit miteinander verbinden.

Auch das Audit-Protokoll braucht zwei Detailebenen. Ein Journal sollte den Agent-Lauf und die genehmigende Person zeigen. Ein weiteres sollte jeden externen Aufruf festhalten, einschließlich Auswahl-Digest, Operations-ID, Endpunkt und Ergebnisstatus. Bei einem Vorfall müssen Ermittler beide Fragen beantworten können: «Welcher Prozess hat die Arbeit angefordert?» und «Welche Datensätze wurden geändert?»

Ein Bulk-Workflow sollte bei unklarer Absicht sicher stoppen

Baue den Agent-Workflow so, dass er nicht direkt von einer natürlichsprachlichen Anfrage zu einer Mutation springen kann. Die folgende Abfolge ist absichtlich unspektakulär, denn Unspektakuläres lässt sich leichter untersuchen.

1. Der Agent übersetzt die Anfrage in einen Selektor, eine geplante Mutation, eine Umgebung und Ausschlüsse. Bleibt etwas davon unklar, bittet er um Präzisierung.
2. Er erstellt eine stabile Auswahl und ruft die Prüffelder für alle Mitglieder ab. Er protokolliert Auswahl-ID, Digest, Abfrage, Zeitpunkt und Vollständigkeit der Seiten.
3. Er zeigt das Manifest und die geplante Wirkung. Ein Mensch genehmigt genau dieses Paar oder lehnt es ab.
4. Er sendet eine Commit-Anfrage mit Auswahlreferenz, erwartetem Digest, Aktionsdaten, Idempotency-Key und, sofern vorhanden, Datensatzversionen.
5. Er meldet abgeschlossene, fehlgeschlagene, übersprungene und unbekannte Ergebnisse getrennt. Ein Teilergebnis wird niemals in eine freundliche Meldung verwandelt, dass der Job beendet sei.

Genehmige keinen Rohbefehl wie «Bereinigungsskript ausführen», wenn der Befehl seine Ziele erst später berechnen kann. Diese Praxis ist beliebt, weil sie schnell und vertraut ist, besonders bei Teams, die ihren Skripten bereits vertrauen. Sie scheitert, weil die Genehmigung den Quelltext abdeckt, nicht die aktuellen Daten. Eine kleine Datenänderung zwischen Bestätigung und Ausführung kann dazu führen, dass der genehmigte Befehl nicht genehmigte Arbeit erledigt.

Definiere für wiederkehrende Jobs enge Selektoren und eine maximale Anzahl. Verlange eine Prüfung, sobald die Auswahl diese Grenze überschreitet oder eine unbekannte Kategorie enthält. Eine maximale Anzahl ist eine Leitplanke, keine Autorisierung. Das Manifest bleibt der Beleg dafür, welche Datensätze der Job tatsächlich berührt hat.

Die erste Implementierungsaufgabe ist einfach: Lass deinen Bulk-Endpunkt eine Auswahl-ID und einen Digest zurückgeben und lehne Commit-Anfragen ab, die nicht beide Werte wiederholen. Sobald dieser Vertrag existiert, haben Agenten, Dashboards und Skripte eine feste Grenze, die sie einhalten können.