Przewodnik

Niezawodność narzędzi chatbota: timeouts, retry, idempotency i audyt

Jak projektować wywołania narzędzi tak, aby system był stabilny w produkcji: kontrola czasu, powtórzeń, uprawnień, walidacji oraz pełny trace.

Niezawodność jako kontrakt

Integracje narzędzi (API, bazy, systemy ticketowe, CRM) są najczęstszym źródłem degradacji jakości chatbota. Dobra praktyka to traktowanie niezawodności jako kontraktu: z jawnie opisanymi limitami, polityką retry/timeout, idempotency oraz audytem decyzji wykonawczych.

Klasy awarii, które trzeba projektować „z góry”

  • Timeout (zależność wolna lub przeciążona) – wymaga budżetu czasu na krok.
  • Transient errors (5xx, sieć, rate limit) – wymagają retry z backoffem i jitterem.
  • Permanent errors (4xx, walidacja) – nie retry; naprawa danych wejściowych.
  • Duplikacja (powtórne wywołanie) – wymaga idempotency key i deduplikacji po stronie narzędzia.
  • Niejawny stan (kolejki, procesy) – wymaga korelacji (trace/correlation id).
Reguła klasyczna: retry nie może być „magiczne”. Każdy retry powinien mieć powód, limit i wpis w śladzie. Jeżeli nie potrafisz wyjaśnić retry w audycie, to retry jest ryzykiem, nie mechanizmem jakości.

Minimalny standard timeout + retry

tool_policy:
  timeout_ms: 3500
  retries:
    max: 2
    backoff: "exponential"
    jitter: true
    retry_on: ["timeout", "429", "5xx"]
  no_retry_on: ["schema_error", "4xx_validation"]
  circuit_breaker:
    enabled: true
    open_after: 8
    window_s: 60

Idempotency i dokładność skutków

W środowisku LLM powtórzenia są normalne (retry, ponowne planowanie, użytkownik „dopytał”). Dlatego narzędzia powinny wspierać idempotency key (najlepiej deterministyczny: trace + step), a odpowiedzi narzędzi powinny zawierać identyfikator wykonania i stan (created/updated/no-op).

Audyt i obserwowalność

  • Trace ID wspólny dla rozmowy i narzędzi (end-to-end).
  • Step log: wejście → walidacja → wykonanie → wynik → post-processing.
  • Redakcja danych (PII, sekrety) w logach; przechowywanie zgodne z polityką retencji.
  • Metryki: latency p95/p99, success rate, retry rate, duplicate rate, fallback rate.

Checklista wdrożeniowa

  • Każde narzędzie ma: schema, limity, timeout, retry, idempotency, log audytu.
  • Każda odpowiedź narzędzia jest „samopopisowa” (status, id, timestamp, wersja).
  • Każda degradacja ma plan B: fallback, „manual review”, kolejka, komunikat do użytkownika.
Rozszerzenie praktyczne

Operacyjny skrót

Ten rozdział należy do rodziny Wdrożenie i governance i ma formę Przewodnik. 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 tym rozdziale
  • kontrakt wywołania narzędzia
  • retry/backoff/circuit breaker
  • walidacja i sanitacja
  • telemetria i audyt
  • checklist praktyczny

Dlaczego „niezawodność narzędzi” jest osobnym tematem

W systemach narzędziowych (function calling, tool use) większość awarii produkcyjnych nie wynika z „modelu”, tylko z klasycznych problemów integracyjnych: timeouts, retry storms, brak idempotency, błędy walidacji, zbyt szerokie uprawnienia. Dobre Luage traktuje narzędzia jak API, a nie jak „opcję w promptcie”.

Zasada: narzędzie musi być bezpieczne w wykonaniu, deterministyczne w kontrakcie i obserwowalne w telemetrii.

Kontrakt wywołania

  • Schema wejścia i wyjścia (typy, wymagane pola, walidacja).
  • Idempotency key dla operacji, które mogą być powtórzone.
  • Time‑budget: timeout per call + globalny budżet przebiegu.
  • Rozróżnienie read vs write (write zwykle wymaga approvals).

Retry, backoff, circuit breaker

  • Retry tylko dla błędów przejściowych (np. 429/503), z wykładniczym backoff.
  • Circuit breaker dla kaskadowych awarii (zatrzymaj „burzę retry”).
  • Fallback: tryb degradacji (np. odpowiedź bez narzędzia + jasny komunikat o ograniczeniu).

Walidacja i sanitacja danych

  • Waliduj wejście przed wywołaniem narzędzia (schema + reguły biznesowe).
  • Waliduj wyjście narzędzia (typy, zakresy, brak PII jeśli nie jest dozwolone).
  • Loguj błędy walidacji jako osobną kategorię incydentów.

Telemetria i audyt

  • trace_id, tool_name, duration_ms, status, retry_count
  • wyniki bramek (schema/RBAC/DLP/approval)
  • idempotency_key (hash) i korelacja request/response

Checklist (skrót)

  • Schema wejścia/wyjścia + testy kontraktu.
  • Retry policy + circuit breaker.
  • Idempotency dla write.
  • Limity: concurrency, rate limits, timeouts.
  • Pełny trace + audyt bramek.
Powiązane
Na tej stronie
Spis
    Nawigacja
    ← Poprzedni Następny →
    Status merytoryczny
    Ten rozdział jest częścią Compendium. Metryka (wersja, owner, terminy przeglądu) jest wypełniana automatycznie na podstawie manifestu.