Procedura

Rollback i transakcje kompensacyjne narzędzi

Wzorzec bezpiecznego użycia narzędzi ze skutkami ubocznymi: idempotency key, event log, SAGA oraz tryb approval. Tak utrzymuje się przewidywalność i audyt w systemach LLM.

Czas czytania: ~14 min Aktualizacja: 2026-01-09
W skrócie
  • write‑tools wymagają kontroli
  • idempotency + event log
  • SAGA/kompensacja lub approval

Kiedy potrzebujesz kompensacji

Jeżeli narzędzie ma skutki uboczne (zmienia stan systemu, wysyła e‑mail, tworzy zamówienie), to „zwykły retry” jest ryzykowny. W takich przypadkach potrzebujesz:

  • idempotency key — aby powtórzenie nie tworzyło duplikatu,
  • event log — aby wiedzieć, co się stało,
  • kompensacji — aby naprawić skutki uboczne, gdy proces nie domknął się poprawnie.
Rollback i kompensacja — SAGA
Wzorzec SAGA: idempotency + log zdarzeń + kompensacja zamiast niepewnego „cofania”.

Idempotency i event log

Idempotency key musi być stabilny dla danego zamiaru użytkownika. Praktyczny wariant: 

idempotency_key = hash(trace_id + tool_name + stable_intent + normalized_args)

Gateway zapisuje:

  • event_id, idempotency_key, tool_name, args_hash
  • status (PENDING/SUCCESS/FAILED/COMPENSATED)
  • external_ref (np. id zamówienia)

Wzorzec SAGA

W Saga proces jest sekwencją kroków. Każdy krok ma akcję i kompensację. Przykład:

  • akcja: utwórz zamówienie → kompensacja: anuluj zamówienie
  • akcja: zarezerwuj zasób → kompensacja: zwolnij zasób
Jeżeli nie da się sensownie zdefiniować kompensacji, narzędzie powinno działać w trybie approval (HITL).

Tryb approval

Approval nie jest porażką — to kontrola. W praktyce:

  • model przygotowuje plan i dane wejściowe,
  • człowiek zatwierdza,
  • gateway wykonuje narzędzie, a wynik wraca do modelu.

Obsługa błędów i retry

  • Retry dopuszczalny tylko dla operacji read‑only lub idempotentnych.
  • Timeout traktuj jako stan niepewny: sprawdź event log zanim powtórzysz.
  • Compensate uruchamiaj z limitem i audytem.

Testy

Minimalne testy regresji:

  • powtórzenie żądania z tym samym key nie tworzy duplikatu,
  • awaria w połowie uruchamia kompensacje,
  • log zawiera pełny ślad (trace_id).

Checklist

  • Każde narzędzie opisuje skutki uboczne i ma tryb read‑only / write.
  • Write‑tools wymagają idempotency key i event log.
  • Zdefiniuj kompensacje (SAGA) lub wprowadź approval.
  • Retry tylko dla bezpiecznych operacji; timeout = niepewność.
  • Włącz audyt i testy regresji dla tool gateway.

Powiązane

Skrót operacyjny
  1. Idempotency key → brak duplikatów.
  2. Event log → prawda o stanie.
  3. SAGA/kompensacja lub approval.
Powiązane
Artefakt
Sekwencje wywołań + checklista dla write‑tools.
Tool Gateway