Wie ein Agent dieselbe Geschäftsaktion nicht zweimal ausführt

Fünf Wege, auf denen ein Agent eine Aktion wiederholt

• Ein Retry nach einem Timeout, obwohl die erste Anfrage bereits verarbeitet war
• Das Modell ruft das Tool erneut auf, weil es das erste Ergebnis nicht gesehen oder ihm nicht vertraut hat
• Ein Replay des Frameworks: LangGraph führt einen unterbrochenen Knoten beim Fortsetzen von Anfang an aus, und ein Replay ab einem Checkpoint führt spätere Knoten samt API-Aufrufen erneut aus
• Eine Queue liefert denselben Fall zweimal aus, oder zwei Worker übernehmen ihn
• Dieselbe Anfrage kommt zweimal an, etwa eine Rechnung per E-Mail und zusätzlich über ein Portal

Nur der letzte Fall ist eine fachliche Dublette, die Fachregeln braucht. Die ersten vier sind dieselbe Aktion in einem neuen Versuch, und ein Idempotenzschlüssel deckt sie alle ab, wenn er über alle Versuche gleich bleibt.

Den Schlüssel aus der Geschäftsaktion ableiten

Ein zufälliger Wert, der beim Aufruf erzeugt wird, ändert sich bei jedem Versuch von Modell oder Framework und schützt deshalb nur vor dem engsten Retry. Bilden Sie den Schlüssel im Code aus stabilen Fakten: dem Fall, der Art der Aktion, ihrem Ziel und ihrer Position im Fall. Das Modell wählt ihn nie.

import hashlib
import json

def action_key(case_id: str, action: str, target: str, step: int) -> str:
    """Same business action, same key, across retries, replays and restarts."""
    # A JSON array keeps the fields apart: ("a|b", "c") and ("a", "b|c")
    # produce different strings, which a plain "|".join would not.
    canonical = json.dumps([case_id, action, target, step],
                           ensure_ascii=False, separators=(",", ":"))
    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()[:40]

# action_key("claim-88213", "create_payment", "payee:SUP-2291", 1)
# returns the same 40-character key every time it is called with these values

Kodieren Sie die Felder vor dem Hashing eindeutig. Werden frei formatierte Kennungen mit einem Trennzeichen wie einem senkrechten Strich verbunden, können zwei verschiedene Aktionen dieselbe Eingabezeichenkette erzeugen, etwa wenn eine Fall-ID selbst das Trennzeichen enthält, und erhielten dann denselben Schlüssel. Das ist ein Fehler in der Kodierung und etwas anderes als Kollisionen der Hashfunktion. Ein kanonisches JSON-Array wie oben oder Felder mit vorangestellter Länge vermeiden ihn; ein Trennzeichen ist nur sicher, wenn für jede Kennung geprüft wird, dass sie es nie enthält.

Das Hashing hält Rohwerte wie Bankverbindungen aus dem Schlüssel heraus, macht sie aber nicht anonym: Der Hash einer Kennung lässt sich oft wieder einer Person zuordnen. Behandeln Sie Schlüssel und Aktionsprotokoll daher als pseudonymisierte personenbezogene Daten und stimmen Sie den Umgang damit mit Ihrem Datenschutzbeauftragten ab. Die Stripe-Dokumentation rät zum Beispiel davon ab, sensible Daten als Idempotenzschlüssel zu verwenden. Über die Schrittnummer kann ein Fall rechtmäßig zwei ähnliche Zahlungen auslösen, etwa zwei Raten, ohne dass sie kollidieren.

Die empfangende Seite muss ihn durchsetzen

Ein Schlüssel, den das Zielsystem ignoriert, schützt nichts. Prüfen Sie für jedes schreibende Tool, welche von drei Situationen vorliegt.

Die API unterstützt Idempotenzschlüssel

Lesen Sie die Regeln des Anbieters genau, denn sie unterscheiden sich. Die API v1 von Stripe akzeptiert Schlüssel zum Beispiel bei POST-Anfragen, speichert die erste Antwort einschließlich 500-Fehlern, lehnt einen wiederverwendeten Schlüssel mit anderen Parametern ab und kann Schlüssel nach frühestens 24 Stunden entfernen. Diese Details gelten für Stripe und sagen nichts über Ihr ERP aus. Verlassen Sie sich nur auf die Zusagen, die der Anbieter dokumentiert, einschließlich der Aufbewahrungsdauer von Schlüsseln und des Umgangs mit gleichzeitigen oder fehlgeschlagenen Anfragen.

Sie kontrollieren den Schreibpfad

Schreibt das Tool oder der MCP-Server in eine Datenbank, die Sie kontrollieren, speichern Sie Schlüssel, einen Hash der Parameter und das Ergebnis in derselben Transaktion wie die Änderung. Der Artikel der Amazon Builders' Library zu idempotenten APIs beschreibt dieses Muster: Anfragekennung und Änderung atomar speichern, bei einer Wiederholung eine gleichwertige Antwort liefern und dieselbe Kennung mit anderen Parametern ablehnen. Das funktioniert nur, weil Schlüssel und Änderung gemeinsam festgeschrieben werden. Ein Tool, das einen Aufruf lediglich an eine externe API weiterreicht, kann das nicht: Geht die Antwort verloren, weiß es nicht, ob die Wirkung eingetreten ist.

Beides ist nicht möglich

Nutzen Sie eine natürliche eindeutige Referenz, die das Zielsystem bereits prüft, etwa Lieferant plus Rechnungsnummer, und lesen Sie vor dem Schreiben zurück. Fehlt selbst das, braucht die Aktion eine Person, oder Sie akzeptieren gelegentliche Dubletten und gleichen sie ab. Das Zurücklesen verkleinert das Fenster für Dubletten, schließt es aber nicht, weil die erste Anfrage noch in Arbeit sein kann. Fälle, in denen die Prüfung das Ergebnis nicht klärt, gehen an eine Person oder in den Abgleich.

Lange Pausen überdauern kurzlebige Schlüssel

Agentenläufe können tagelang auf eine Freigabe warten. Bewahrt ein Anbieter Schlüssel nur für begrenzte Zeit auf, fällt ein Fortsetzen nach langer Pause womöglich aus diesem Fenster. Führen Sie ein eigenes Aktionsprotokoll mit Zuständen wie ausstehend, erledigt und fehlgeschlagen und bewahren Sie es mindestens so lange auf, wie ein Fall offen bleiben kann. Ein ausstehender Eintrag, der älter ist als erwartet, bedeutet ein unbekanntes Ergebnis: Prüfen Sie das Zielsystem, bevor Sie es erneut versuchen.

Abgleichen und dann die Fehlerstellen testen

Lassen Sie regelmäßig einen Job laufen, der das Aktionsprotokoll mit dem Zielsystem vergleicht: protokollierte Aktionen ohne Wirkung, Wirkungen ohne Protokoll und doppelte Wirkungen. Dubletten werden über den fachlichen Prozess für diese Aktion korrigiert, etwa eine Stornierung oder Erstattung, und das Compensating-Transaction-Muster von Microsoft weist darauf hin, dass auch solche Korrekturschritte idempotent sein müssen.

Testen Sie dann genau die Fehlerstellen: Beenden Sie den Prozess nach dem externen Aufruf, aber vor jeder Speicherung, setzen Sie fort und prüfen Sie, dass genau ein Datensatz existiert. Liefern Sie denselben Fall gleichzeitig an zwei Worker aus. Ein guter erster Schritt ist eine Liste aller schreibenden Tools mit der Angabe, welche der drei Situationen jeweils gilt.