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"
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