Procedura

Testy kontraktowe narzędzi

Jeżeli narzędzie ma być bezpieczne w rękach agenta, musi mieć kontrakt i testy. To stara, solidna zasada z integracji systemów — w agentach jest tylko bardziej bezwzględna.

Testy kontraktowe: stabilność na styku LLM ↔ narzędzia

Testy kontraktowe weryfikują, czy narzędzie spełnia oczekiwany kontrakt: schema wejścia/wyjścia, kody błędów, idempotency, limity i zachowanie w scenariuszach brzegowych. W Luage to fundament „tool gateway”.

Co testować (minimum)

  • Schema: walidacja wejścia i wyjścia (w tym pola opcjonalne).
  • Idempotency: powtórne wywołanie nie może robić podwójnych skutków.
  • Timeout: zachowanie przy przekroczeniu budżetu czasu.
  • Rate limit: retry/backoff i komunikat błędu do planera.

Jak budować pakiet testów

  1. Happy path – 3–5 przypadków reprezentatywnych.
  2. Edge cases – granice zakresu, puste wartości, brak uprawnień.
  3. Failure matrix – 4xx/5xx/timeout/rate-limit.
  4. Replay – deterministyczne odtwarzanie kroków (trace → test).
Praktyka: kontrakt testuje się w CI. Jeżeli testy żyją „obok”, to prędzej czy później przestaną być aktualne i staną się martwą dokumentacją.

Format raportu

contract_test_report:
  tool: "ticket.create"
  version: "1.2.0"
  passed: 42
  failed: 1
  failures:
    - id: "idempotency.duplicate"
      trace: "trc_91fc..."
      expected: "no-op"
      got: "created"
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
  • kontrakt narzędzia to schema + semantyka (błędy, retry, idempotency, RBAC)
  • testy muszą mieć część must‑pass i must‑fail
  • bramka CI blokuje wdrożenie przy regresji, a raport jest artefaktem
  • bez testów agent „uczy się” narzędzia na użytkownikach — to kosztowny sport
Jeśli to ma wejść do procesu, proszę traktować ten rozdział jako standard operacyjny.
Standard produkcyjny: narzędzie dostaje dostęp do agenta dopiero wtedy, gdy przejdzie testy kontraktowe. W przeciwnym razie model będzie „testował” narzędzie na użytkownikach.

1. Kontrakt: schema to dopiero początek

Kontrakt narzędzia ma dwa poziomy:

  • syntaktyczny — format wejścia/wyjścia (np. JSON Schema),
  • semantyczny — co oznacza błąd, retry, idempotency, uprawnienia, limity.

W systemach agentowych semantyka jest krytyczna, bo model będzie próbował „kombinować”, dopóki nie dostanie stabilnych reguł.

2. Pakiet testów (must‑pass + must‑fail)

Testy kontraktowe narzędzi — bramki CI
Rodzaj testu Przykład Po co
Schema czy wyjście zawsze spełnia JSON Schema żeby agent nie „pękał” na parserze
Uprawnienia brak scope → 403, bez ujawnienia danych żeby RBAC działał, nie tylko istniał
Idempotency ten sam klucz → ten sam efekt żeby retry nie robił szkód
Failure injection timeout/500 → bezpieczna degradacja żeby model dostał stabilny błąd
Performance p95 latency w budżecie żeby SLO było realne

3. Bramki CI i polityka wdrożeniowa

Klasyczny, solidny wzorzec:

  • narzędzia mają własny pipeline CI,
  • każda zmiana kontraktu podbija wersję,
  • wdrożenie jest blokowane, jeśli testy must‑fail nie failują.

Rzetelne raportowanie (minimum):

{
  "tool": "billing.create_invoice",
  "contract_version": "2.1",
  "tests": { "pass": 142, "fail": 0 },
  "p95_ms": 380,
  "notes": "RBAC + idempotency OK"
}

4. Powiązane rozdziały

Na tej stronie
Spis
Następny krok

Jeśli chcesz utrzymać kontrolę nad wykonaniami, dopnij Tool Gateway i audyt.

Przejdź do Tool Gateway