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
Rozszerzenie praktyczne

Operacyjny skrót

Ten rozdział należy do rodziny Wdrożenie i governance i ma formę Procedura. Poniższe dopowiedzenie ma jeden cel: przełożyć treść na działania, które da się wdrożyć, zmierzyć i utrzymać.

Checklista

  • Ustal właścicieli (RACI) dla polityk, szablonów i danych.
  • Wersjonuj i publikuj zmiany (changelog) z uzasadnieniem.
  • Prowadź rejestr wyjątków i decyzji (ADR) dla odstępstw.
  • Zdefiniuj SLO i monitoring (jakość, koszty, bezpieczeństwo).
  • Zaplanuj rollout: środowiska, feature flags, rollback.
  • Ustal rytm przeglądów i audytów (np. co kwartał).

Najczęstsze pułapki

  • „Wdrożenie na wczoraj” bez ownerów – po miesiącu nikt nie utrzymuje standardu.
  • Brak changelogu – użytkownicy nie wiedzą, czemu odpowiedzi się zmieniły.
  • Brak rollbacku – błąd w polityce rozlewa się na całą organizację.
  • Brak procesu wyjątków – wszyscy robią „po swojemu”, standard się rozpada.

Artefakty w Luage

raci policy_versioning changelog exception_log rollback_plan

Standard działa dopiero wtedy, gdy ma właściciela, wersję, ślad (trace) oraz test regresyjny.

Szablon do skopiowania

Wpis do changelogu (przykład)

date: 2026-01-18
change:
  id: language.standard@0.10
  summary: "Ujednolicenie terminologii i doprecyzowanie stylu"
  owner: "Content/AI Governance"
  impact: "Wsparcie, dokumentacja, marketing"
  rollback: "powrót do 0.9"

Governance to powtarzalność: jasne role, wersje, rejestry i kontrola jakości przed zmianą.

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