Testy odporności agentów na dane brudne: 9 klas błędów wejścia (daty, waluty, OCR) i jak je symulować

1. Wprowadzenie: dlaczego „brudne dane” psują automatyzacje i jak testować odporność agentów

Automatyzacje oparte na agentach (regułowych, workflowowych i tych z elementami AI) zakładają, że dane wejściowe mają określoną strukturę, format i znaczenie. W praktyce dane z systemów transakcyjnych, arkuszy, e-maili, skanów, integracji i ręcznych wpisów są często „brudne”: niejednoznaczne, niekompletne, niespójne lub zniekształcone. To właśnie te odstępstwa od założeń powodują większość awarii procesów: od cichych błędów po kosztowne decyzje oparte na złej interpretacji.

„Brudne dane” są szczególnie groźne, bo nie zawsze prowadzą do widocznego wyjątku. Zamiast tego mogą wywołać poprawnie wyglądający, ale błędny wynik (np. niewłaściwa data, waluta czy jednostka), który przechodzi przez kolejne kroki automatyzacji, a problem ujawnia się dopiero w rozliczeniach, raportach lub u klienta. W środowiskach wieloźródłowych problem narasta: różne standardy zapisu, lokalizacje, skróty, kodowania znaków, a także błędy OCR i kopiowania sprawiają, że „to samo” pole ma wiele wariantów.

W efekcie automatyzacje psują się na trzy typowe sposoby:

• Awaria twarda – proces przerywa działanie, bo nie umie sparsować lub zwalidować wejścia (np. nieoczekiwany format daty).
• Awaria miękka – proces działa dalej, ale wprowadza błędne wartości (np. mylna interpretacja separatorów tysięcy i dziesiętnych), co bywa trudniejsze do wykrycia.
• Degradacja jakości – agent podejmuje decyzje na podstawie niepełnych lub zniekształconych danych, co obniża trafność klasyfikacji, dopasowań i rekomendacji.

Dlatego odporność na brudne dane nie jest „miłym dodatkiem”, tylko częścią definicji poprawności systemu. W tym kontekście testowanie odporności oznacza sprawdzenie, jak agent zachowuje się, gdy wejście odbiega od ideału: czy potrafi odrzucić dane z jasnym komunikatem, czy umie je naprawić w kontrolowany sposób, czy zachowuje się przewidywalnie i bezpiecznie przy niejednoznaczności.

Kluczowa różnica względem klasycznych testów funkcjonalnych polega na tym, że nie wystarcza sprawdzić „szczęśliwej ścieżki”. Trzeba badać:

• Granice i warianty formatów – nie tylko poprawne wartości, ale też ich realistyczne odmiany i przekłamania.
• Stabilność interpretacji – czy agent rozumie dane tak samo w różnych kontekstach (np. lokalizacja, kanał pozyskania, źródło).
• Bezpieczeństwo decyzji – czy w sytuacjach niepewnych agent woli eskalować, poprosić o doprecyzowanie lub zatrzymać krok, zamiast „zgadywać”.

Odporność agentów warto traktować jako połączenie trzech warstw:

• Wejście – walidacja, normalizacja i detekcja anomalii na danych przed właściwą logiką.
• Rdzeń decyzyjny – spójne reguły interpretacji oraz zachowanie przy brakach i niejednoznacznościach.
• Wyjście i ślady – możliwość wykrycia, że doszło do naprawy, degradacji lub odrzucenia (np. poprzez czytelne logi i atrybuty jakości danych).

W praktyce celem testów odporności jest udzielenie odpowiedzi na proste pytania biznesowo-techniczne: jak często automatyzacja się wykolei, jakie typy błędów są dla niej krytyczne oraz czy potrafi bezpiecznie „przyznać, że nie wie”. Dobrze zaprojektowane testy nie próbują udowodnić, że dane są czyste; zakładają, że brud jest nieunikniony i mierzą, czy agent potrafi działać w warunkach rzeczywistych.

2. Strategia testów odporności: generatory danych, mutacje wejść i zestawy regresyjne

Odporność agenta na „brudne dane” najłatwiej budować i weryfikować w trzech uzupełniających się strumieniach: generatorach danych (tworzą szeroki przekrój realistycznych wejść), mutacjach wejść (celowo psują konkretne fragmenty danych) oraz zestawach regresyjnych (utrwalają znane przypadki i chronią przed powrotem błędów). Podczas szkoleń Cognity ten temat wraca regularnie – dlatego zdecydowaliśmy się go omówić również tutaj. Razem dają pokrycie zarówno „typowych” wariantów, jak i rzadkich anomalii, a także stabilność w czasie.

Generatory danych: szerokość pokrycia i realizm

Generatory służą do wytwarzania dużej liczby przykładów wejść o kontrolowanej różnorodności. Ich główną rolą jest sprawdzenie, czy agent działa poprawnie w wielu wariantach formatów, kolejności pól i sposobów zapisu, nawet jeśli pojedyncze różnice wydają się nieistotne.

• Kiedy są najlepsze: na początku pracy nad przepływem (żeby szybko odkryć braki w walidacji), przy zmianach w parserach/normalizacji oraz gdy chcesz pokryć wiele kombinacji wejść bez ręcznego pisania przypadków.
• Co powinny kontrolować: zakresy wartości, rozkłady (częste vs. rzadkie przypadki), zależności między polami (np. suma pozycji a wartość całkowita), warianty językowe i regionalne.
• Pułapka: generator, który tworzy „zbyt czyste” dane, daje fałszywe poczucie bezpieczeństwa. W praktyce warto od razu planować generator tak, by potrafił tworzyć również dane graniczne i nietypowe, ale nadal plausybilne.

Mutacje wejść: celowe psucie danych i testowanie odporności

Mutacje to podejście „bierzemy poprawne wejście i psujemy je na określony sposób”. Różni się od generatorów tym, że startuje od przykładu referencyjnego, a następnie wprowadza pojedyncze lub skumulowane odchylenia. Dzięki temu łatwiej ocenić, czy agent potrafi: rozpoznać problem, naprawić go, poprosić o doprecyzowanie albo bezpiecznie przerwać przetwarzanie.

• Kiedy są najlepsze: gdy chcesz przetestować konkretne ryzyka (np. formaty liczb, niejednoznaczne daty, artefakty OCR), gdy ważne jest zachowanie w sytuacjach „prawie poprawnych”, oraz w testach odporności na degradację jakości danych.
• Co mutować: zarówno treść (wartości), jak i strukturę (brak pola, dodatkowe pole, zamiana kolejności), a także warstwę prezentacji (spacje, separatory, kodowanie znaków).
• Pułapka: mutacje losowe bez kontroli mogą produkować dane, których system nigdy nie zobaczy. Lepsze są mutacje oparte o obserwacje z produkcji oraz o znane mechanizmy psucia danych (np. kopiuj-wklej z PDF, skan, eksport CSV z lokalnymi ustawieniami).

Zestawy regresyjne: pamięć organizacji i stabilność zmian

Zestawy regresyjne to kolekcje przykładów wejść (często wraz z oczekiwanym zachowaniem), które odzwierciedlają to, co już raz poszło nie tak albo było trudne do obsłużenia. Ich celem nie jest maksymalna różnorodność, tylko powtarzalność i ochrona przed ponownym pojawieniem się tych samych błędów po zmianach w promptach, narzędziach, walidatorach czy logice biznesowej.

• Kiedy są najlepsze: przy każdej zmianie w agentach, integracjach i regułach walidacji; jako „bramka jakości” w CI/CD; przy refaktoryzacjach parserów i normalizatorów.
• Co powinny zawierać: minimalny zestaw przypadków krytycznych (te o najwyższym wpływie), przypadki z incydentów produkcyjnych, oraz reprezentatywne przykłady głównych typów wejść.
• Pułapka: regresja, która rośnie bez ładu, spowalnia pracę i trudniej ją utrzymać. Lepiej świadomie kuratorować zestaw: usuwać duplikaty, scalać podobne przypadki i priorytetyzować te o największym ryzyku.

Jak połączyć trzy podejścia w jedną, praktyczną strategię

Najlepsze efekty daje połączenie tych metod w cykl: generatory budują szerokie pokrycie, mutacje punktowo stresują system w obszarach ryzyka, a regresja utrwala najważniejsze lekcje. W praktyce warto dążyć do tego, by:

• Generatory odpowiadały na pytanie: „czy agent działa poprawnie w wielu realistycznych wariantach danych?”
• Mutacje odpowiadały na pytanie: „czy agent zachowuje się bezpiecznie, gdy dane są częściowo uszkodzone lub niejednoznaczne?”
• Regresja odpowiadała na pytanie: „czy po zmianie systemu nie popsuliśmy tego, co już działało?”

Taka struktura pozwala utrzymać równowagę między wykrywaniem nowych problemów a stabilnością w czasie, bez nadmiernego rozrastania testów i bez polegania wyłącznie na ręcznie przygotowanych przykładach.

3. 9 klas błędów wejścia – przegląd i przykłady

„Brudne dane” to nie tylko literówki. To powtarzalne wzorce odchyleń od formatu i znaczenia, które sprawiają, że agent: (1) błędnie interpretuje wartości, (2) wybiera złą gałąź logiki, (3) zapisuje niespójny rekord lub (4) wykonuje nieodwracalne akcje (np. błędny przelew, zła data księgowania). Poniżej znajduje się przegląd 9 typowych klas błędów wejścia wraz z krótkimi przykładami i typowym skutkiem.

1) Daty i czas

Problemy z datami zwykle wynikają z niejednoznacznych formatów (dzień/miesiąc), różnych separatorów, skrótowych zapisów oraz stref czasowych. To klasa błędów, która bywa zdradliwa, bo „wygląda poprawnie”, ale zmienia znaczenie.

• Niejednoznaczność: "03/04/2026" może oznaczać 3 kwietnia lub 4 marca.
• Strefy: "2026-03-28 00:30" bez strefy vs zapis ze strefą.
• Daty „prawie poprawne”: "2026-13-01" (zły miesiąc), "31.02.2026".

2) Waluty i kwoty

Kwoty psują się przez różne konwencje zapisu (kropka/przecinek), symbole i znaki wartości (minus, nawiasy), a także przez mieszanie waluty i liczby w jednym polu. Tu często dochodzi do błędów rzędu 100× (np. centy vs jednostki).

• Separatory: "1 234,56" vs "1,234.56".
• Ujemne: "-100,00" vs "(100.00)".
• Oznaczenia: "PLN", "zł", "€" oraz brak waluty przy wartości.

3) Separatory i formaty pól

Dotyczy danych tabelarycznych i pół-strukturalnych (CSV, eksporty z systemów, copy-paste). Błędy wynikają z innego delimitera, niewłaściwego cudzysłowu, obecności separatora w treści pola lub „niewidocznych” znaków (np. twardych spacji).

• Delimiter: średnik zamiast przecinka (częste w PL eksportach).
• Quoting: pole zawiera przecinek, ale nie jest ujęte w cudzysłów.
• Białe znaki: końcowe spacje, znak tabulacji, non-breaking space.

4) Kodowania i znaki

Ta klasa obejmuje zarówno „krzaki” po złym dekodowaniu, jak i subtelniejsze problemy: normalizacja Unicode, warianty tego samego znaku oraz różnice w zapisie (np. „é” jako pojedynczy znak vs „e” + akcent). Skutek to często problemy z dopasowaniem rekordów i walidacją.

• Złe kodowanie: tekst z Windows-1250 odczytany jako UTF-8.
• Normalizacja: różne reprezentacje „tej samej” litery.
• Znaki mylące: „–” (półpauza) vs „-” (minus), cudzysłowy typograficzne.

5) OCR / rozpoznawanie tekstu

Dane z OCR (skany, zdjęcia, PDF) mają specyficzne defekty: mylenie podobnych znaków, „sklejanie” lub rozbijanie tokenów, przypadkowe znaki, błędne łamanie linii. Są trudne, bo często tworzą pozornie poprawne ciągi, które przechodzą proste walidacje.

• Konfuzje znaków: O/0, l/1, S/5, B/8.
• Kwoty: "1O0,OO" zamiast "100,00".
• Identyfikatory: numer konta z brakującą cyfrą lub dodatkową spacją.

6) Brakujące pola

Braki mogą oznaczać brak klucza, wartość pustą, wartość „placeholder” ("—", "N/A"), albo częściowo wypełniony rekord. To inna sytuacja niż „błędny format” — tu agent musi zdecydować, czy da się kontynuować bezpiecznie.

• Null vs empty: różnica między brakiem a pustym stringiem.
• Placeholdery: "brak", "0" użyte jako „nie dotyczy”.
• Pola krytyczne: brak kwoty, brak daty, brak identyfikatora.

7) Duplikaty

Duplikaty to nie tylko identyczne rekordy. Często spotyka się near-duplicate: różne formatowanie, inne białe znaki, inne wielkości liter, zera wiodące, skróty. Duplikaty są szczególnie groźne w procesach finansowych i operacyjnych.

• Duplikat dosłowny: ten sam wiersz pojawia się 2×.
• Duplikat semantyczny: "FV/01/2026" vs "FV-01-2026".
• Powtórzenia zdarzeń: ponowne wysłanie tego samego pliku lub webhooka.

8) Outliery i wartości skrajne

Outliery to wartości, które są rzadkie, ale możliwe — albo wynikają z błędu. Mogą ujawniać brak ograniczeń, słabe założenia lub podatność na przepełnienia i błędy zaokrągleń.

• Zakres: bardzo duże kwoty, ekstremalna liczba pozycji w zamówieniu.
• Długość: pole tekstowe o długości wielokrotnie większej niż zwykle.
• Wartości graniczne: 0, 1, liczby ujemne, maksymalne daty.

9) Niespójne jednostki

Ta klasa błędów dotyczy sytuacji, gdy liczba jest poprawna syntaktycznie, ale nie wiadomo w jakiej skali lub jednostce została podana (albo jednostka jest inna niż oczekiwana). Problem występuje w danych technicznych, logistycznych i analitycznych.

• Miary: "500" jako gramy vs kilogramy.
• Czas: "90" jako minuty vs sekundy.
• Odległość/temperatura: mile vs kilometry, °C vs °F (często bez oznaczenia).

Wskazówka praktyczna: te klasy często się łączą — np. OCR generuje mylne znaki, które zmieniają separator kwoty, a następnie błędne kodowanie psuje symbole walut. Dlatego warto traktować je jako „klocki” do budowania wariantów wejść, a nie jako rozłączne kategorie.

4. Symulowanie i wstrzykiwanie błędów w testach: jak budować przypadki dla każdej klasy (property-based, fuzzing, scenariusze E2E)

Symulowanie „brudnych danych” polega na kontrolowanym psuciu wejść w sposób, który odzwierciedla realne źródła błędów (formularze, integracje, OCR, eksporty CSV/Excel), a następnie sprawdzaniu, czy agent zachowuje się zgodnie z oczekiwaniami: waliduje, naprawia, prosi o doprecyzowanie albo bezpiecznie odmawia. W praktyce najczęściej łączy się trzy podejścia: property-based testing (testowanie własności na wielu wariantach), fuzzing (wyszukiwanie awarii przez losowe/heurystyczne mutacje) oraz scenariusze E2E (przepływy od wejścia do efektu biznesowego). Na szkoleniach Cognity pokazujemy, jak poradzić sobie z tym zagadnieniem krok po kroku – poniżej przedstawiamy skrót tych metod.

Trzy podejścia: kiedy które stosować

Wstrzykiwanie błędów: gdzie „psuć” dane

Błędy można wstrzykiwać na różnych etapach, zależnie od architektury agenta. Kluczowe jest, by umieć powiązać mutację wejścia z obserwowalnym zachowaniem (logi, decyzje, wywołania narzędzi, rezultat).

• Na granicy systemu: payload API, plik CSV/PDF, treść wiadomości – najbliżej realnego świata.
• Przed walidacją/parsowaniem: testy modułów odpowiedzialnych za ekstrakcję i normalizację.
• W warstwie narzędzi: podstawianie odpowiedzi z narzędzi (np. „OCR zwróciło tekst z błędami”, „ERP zwrócił nietypowy format”).
• W kontekście rozmowy: sprzeczne lub niepełne informacje rozłożone na kilka wiadomości.

Jak budować przypadki dla każdej klasy błędów (mapa: klasa → technika → iniekcja → asercja)

Property-based: definiuj „własności”, nie pojedyncze przypadki

W testach property-based nie chodzi o ręczne wypisanie dziesiątek przykładów, tylko o opis reguły, która zawsze ma być prawdziwa. Następnie generator produkuje wiele wariantów, w tym brzegowe i rzadkie.

• Własności parserów: „jeśli wejście jest jednoznaczne, wynik musi być znormalizowany do jednego formatu”.
• Własności stabilności: „zmiana białych znaków i wielkości liter nie zmienia znaczenia”.
• Własności bezpieczeństwa: „dla niejednoznacznej daty agent nie podejmuje nieodwracalnej akcji bez doprecyzowania”.

// Pseudokod: własność dla kwot
property("kwota po normalizacji zachowuje wartość") {
  input = genAmountString(locale=any, currency=any, spaces=any, separators=any)
  parsed = parseAmount(input)
  assert(parsed.value is finite)
  assert(render(parsed, canonical=true) roundtrips)
}

Fuzzing: mutacje ukierunkowane na awarie i ślepe zaułki

Fuzzing jest szczególnie użyteczny tam, gdzie agent ma wiele ścieżek wykonania (łańcuch narzędzi, różne formaty plików) i ryzyko awarii nie wynika tylko z logiki biznesowej, ale z nieprzewidzianych kombinacji. Skuteczny fuzzing dla „brudnych danych” zwykle łączy losowość z heurystykami:

• Mutacje znakowe: wstawienia/usunięcia, zamiany podobnych znaków (OCR), losowe Unicode.
• Mutacje strukturalne: usuwanie kluczy, zmiana typów (string → number), przestawianie pól.
• Mutacje rozmiarowe: bardzo długie wartości, powtarzające się segmenty, nadmiar rekordów.
• Mutacje „formatowe”: BOM, nietypowe końce linii, mieszane delimitery.

W fuzzingu asercje bywają prostsze: brak crasha, brak niekontrolowanych wyjątków, limity czasu/kosztu, czytelny błąd zamiast milczącej akceptacji.

Scenariusze E2E: brudne dane w realistycznym procesie

Scenariusze end-to-end sprawdzają odporność w kontekście: agent dostaje dane w formie, w jakiej faktycznie je otrzymuje (załącznik, mail, skan), a test obserwuje cały łańcuch: ekstrakcję, walidację, decyzję, wywołania narzędzi i wynik końcowy. To dobre miejsce na symulacje mieszane, np. „OCR + brak pola + niespójna jednostka”, bo takie kombinacje często pojawiają się w praktyce.

• Iniekcja na wejściu: przygotuj warianty plików/wiadomości z wbudowanymi błędami (lub ich zestawy mutacji).
• Iniekcja w zależnościach: stuby/moki narzędzi zwracające nietypowe formaty albo częściowe dane.
• Asercje przepływu: czy agent zatrzymuje się w odpowiednim miejscu, zadaje pytania, nie dubluje akcji.

Łączenie technik: minimalny „pakiet” odporności

W praktyce warto złożyć pakiet testów tak, aby każdy typ błędu miał co najmniej jeden test „regułowy” (property-based), jedną próbę „awaryjną” (fuzzing) oraz jeden scenariusz „biznesowy” (E2E) dla krytycznych ścieżek. Dzięki temu pokrywasz zarówno poprawność, jak i stabilność oraz rzeczywiste konsekwencje brudnych danych.

5. Kryteria oceny jakości: metryki, progi akceptacji, oczekiwane zachowania

Odporność agenta na „brudne dane” warto oceniać nie tylko przez to, czy „działa/nie działa”, ale czy zachowuje się przewidywalnie w obliczu błędów wejścia: poprawnie je wykrywa, potrafi naprawić część z nich, a gdy nie może — bezpiecznie degraduje działanie (np. prosi o doprecyzowanie, wstrzymuje operację, oznacza rekord do ręcznej weryfikacji). Poniżej zestaw kryteriów, które pozwalają porównywać podejścia i ustalać progi akceptacji.

5.1. Trzy oczekiwane tryby zachowania

• Walidacja (fail-fast) — agent rozpoznaje, że dane są niepoprawne/niejednoznaczne i nie wykonuje ryzykownej akcji. Zamiast tego zwraca błąd, prosi o uzupełnienie lub wskazuje pole problematyczne.
• Naprawa (auto-correction) — agent normalizuje dane do formatu kanonicznego (np. ujednolica walutę, separator, kodowanie), zachowując spójność i ślad audytowy tego, co zmienił.
• Degradacja kontrolowana (graceful degradation) — gdy nie da się wiarygodnie naprawić, agent ogranicza zakres działania (np. przetwarza tylko bezpieczne pola, odkłada rekord do kolejki, przełącza się na tryb „read-only”), minimalizując skutki uboczne.

5.2. Kategorie metryk: skuteczność, bezpieczeństwo, stabilność

W praktyce metryki dzielą się na trzy grupy. Kluczowe jest, by progi akceptacji dotyczyły nie tylko „ile agent poprawił”, ale też „ile razy popełnił ryzykowny błąd”.

5.3. Metryki funkcjonalne: „czy wynik jest poprawny?”

• Accuracy/Success rate per klasa błędu — osobno dla dat, walut, OCR itd. (nie jeden uśredniony wynik). Pozwala znaleźć „wąskie gardła” odporności.
• Coverage poprawnej interpretacji — ile wariantów formatu agent rozumie (np. różne zapisy dat) przy zachowaniu tej samej semantyki.
• Semantic equivalence rate — odsetek przypadków, gdzie po normalizacji znaczenie pozostało tożsame (np. „1 234,50 PLN” → 1234.50 i waluta PLN).
• Field-level precision/recall — gdy agent ekstraktuje pola (np. z OCR), liczy się trafność dla każdego pola, nie tylko „rekord przeszedł/nie przeszedł”.

5.4. Metryki walidacji i diagnostyki: „czy agent rozumie, że nie rozumie?”

Tu liczy się jakość odmowy lub prośby o doprecyzowanie. Dobra walidacja nie jest „częstym odrzucaniem” — jest precyzyjna.

• True Reject Rate — jaki procent faktycznie błędnych/niejednoznacznych wejść agent poprawnie odrzucił lub oznaczył do weryfikacji.
• False Reject Rate — ile poprawnych danych agent niepotrzebnie odrzucił (koszt operacyjny, gorszy UX).
• Quality of error messages — czy komunikat wskazuje: pole, typ problemu, sugerowaną poprawkę. To można mierzyć check-listą (np. 0/1 za obecność elementów) zamiast subiektywnej oceny.
• Clarification efficiency — jeśli agent zadaje pytania, to ile ich potrzeba do uzyskania jednoznaczności (średnia liczba doprecyzowań na przypadek).

5.5. Metryki naprawy: „czy korekta jest bezpieczna i audytowalna?”

• Auto-fix rate — jaki odsetek błędów agent naprawia bez interwencji.
• Fix correctness — w ilu przypadkach naprawa była poprawna (ważniejsze niż sam auto-fix rate).
• Overcorrection rate — ile razy agent „naprawił” coś, co nie było błędem, lub zmienił semantykę (kluczowe ryzyko przy agresywnej normalizacji).
• Audit completeness — czy agent zwraca ślad: co zmienił, dlaczego, na jakiej podstawie (np. reguła/heurystyka), oraz czy zachował oryginał wejścia.

5.6. Metryki degradacji kontrolowanej: „czy porażka jest bezpieczna?”

• Safe fallback rate — odsetek przypadków, w których agent przeszedł na tryb bezpieczny zamiast podejmować ryzykowną decyzję.
• Partial completion correctness — jeśli agent wykonuje tylko część zadania, czy ta część jest poprawna i spójna (bez „półprawd” w systemie docelowym).
• Retry/loop rate — czy agent nie wpada w pętle ponowień przy trudnym wejściu (istotne dla kosztów i dostępności).

5.7. Metryki niefunkcjonalne: koszt, opóźnienie, deterministyczność

• Latency penalty — ile dodatkowego czasu zajmuje walidacja/naprawa na danych brudnych (osobno dla percentyli, np. p95).
• Cost per processed record — wzrost kosztu (np. liczba wywołań narzędzi, tokeny) na danych zakłóconych vs czystych.
• Stability score — powtarzalność: ten sam input powinien dawać ten sam wynik w zadanym reżimie (lub różnice tylko w dozwolonych polach, np. kolejności komunikatów).
• Observability coverage — czy logi/metryki zawierają informację o klasie błędu, decyzji (walidacja/naprawa/fallback) i wyniku.

5.8. Progi akceptacji: jak je ustalać bez „magicznych liczb”

Progi akceptacji powinny wynikać z ryzyka procesu. Inne będą dla automatyzacji „read-only”, inne dla działań finansowych czy modyfikujących dane. Dobrą praktyką jest definiowanie progów osobno dla każdej klasy błędu oraz rozdzielenie progów na krytyczne (blokujące wdrożenie) i miękkie (do stopniowej poprawy).

5.9. Minimalny kontrakt zachowania (przykład do specyfikacji testów)

Żeby wyniki testów były porównywalne, warto spisać „kontrakt” tego, co agent ma zrobić w danych warunkach. Poniżej zwięzły szablon (do dopasowania do domeny):

• Gdy wejście jest poprawne — agent przetwarza i zwraca wynik w formacie kanonicznym.
• Gdy wejście jest niepoprawne, ale naprawialne — agent naprawia, oznacza naprawę w metadanych i zachowuje oryginał.
• Gdy wejście jest niejednoznaczne — agent nie podejmuje nieodwracalnych działań; prosi o doprecyzowanie lub eskaluje.
• Gdy brakuje danych krytycznych — agent przerywa lub przechodzi w tryb ograniczony, jasno komunikując brak.
• Gdy wykryje podejrzenie błędu systemowego — agent loguje kontekst i kończy w stanie bezpiecznym (bez „cichych” wyjątków).

// Szkic kontraktu asercji (pseudokod)
assert(no_side_effects_when_ambiguous == true)
assert(preserves_original_input == true)
assert(normalization_does_not_change_semantics == true)
assert(errors_are_actionable == true)

6. Checklist przygotowania testów odporności na brudne dane

Poniższa lista kontrolna pomaga zaplanować testy tak, aby agent (lub automatyzacja oparta o LLM) był odporny na typowe „brudy” wejścia: potrafił je wykryć, naprawić albo bezpiecznie odrzucić bez cichych błędów. Checklist jest celowo praktyczny: skupia się na tym, co przygotować i jak to zorganizować, a nie na szczegółach implementacji.

A. Zakres i cele testów

• Zdefiniuj kontrakt wejścia/wyjścia: jakie pola są wymagane, jakie formaty dopuszczalne, jakie jednostki, jaka precyzja (np. zaokrąglenia walut).
• Określ krytyczność błędów: które dane „psują” proces biznesowy, a które tylko obniżają jakość (np. literówka w nazwie vs. błędna waluta).
• Ustal oczekiwane zachowania dla błędów: walidacja i odrzucenie, automatyczna korekta, prośba o doprecyzowanie, degradacja kontrolowana (np. przejście na tryb ręczny).
• Wybierz poziomy testów: jednostkowe (parser/normalizator), integracyjne (agent + narzędzia), E2E (cały proces), regresyjne (stałe zestawy przypadków).
• Spisz kryteria „stop”: kiedy uznajesz, że odporność jest wystarczająca (minimalny zestaw przypadków i progi akceptacji).

B. Inwentaryzacja wejść i „punktów brudu”

• Mapa źródeł danych: API, pliki CSV/XLSX/PDF, formularze, e-mail, OCR, kopiuj-wklej.
• Mapa transformacji: gdzie dane są parsowane, normalizowane, mapowane do schematu; gdzie następuje walidacja.
• Lista pól wysokiego ryzyka: daty, waluty/kwoty, identyfikatory, adresy, kody pocztowe, numery kont, jednostki, pola tekstowe z OCR.
• Macierz zależności: które pola wpływają na decyzje agenta (routing, kalkulacje, wybór narzędzia, reguły).

C. Projekt zestawów testowych (minimum)

• Zestaw „golden path”: poprawne dane referencyjne (baseline) do porównań.
• Zestaw negatywny: przypadki, które powinny zostać odrzucone (np. nienaprawialne formaty, niespójności).
• Zestaw „naprawialny”: przypadki, które system ma skorygować lub ujednolicić (np. różne separatory, warianty zapisu).
• Zestaw „niejednoznaczny”: dane wymagające doprecyzowania (np. dwuznaczna data), z oczekiwaną reakcją (pytanie/eskalacja).
• Zestaw „brzegowy”: wartości skrajne (0, bardzo duże kwoty, daty graniczne), ale nadal poprawne.

D. Pokrycie klas błędów (checklist per pole)

Dla każdego kluczowego pola przejdź krótką kontrolę pokrycia. Nie chodzi o pełną eksplozję kombinacji, tylko o świadome „odhaczenie” typowych odchyleń.

• Format: warianty zapisu, separatory, skróty, spacje, znaki specjalne.
• Lokalizacja: formaty regionalne (np. przecinek/kropka), strefy czasowe, symbole walut.
• Kodowanie i znaki: diakrytyka, znaki niewidoczne, BOM, łamania linii.
• Braki i nadmiary: pola puste, „N/A”, brak klucza, dodatkowe nieznane pola.
• Duplikaty: powtórzenia rekordów, wielokrotne wiersze dla tego samego ID.
• Niespójność: sprzeczne wartości między polami (np. waluta vs. symbol, jednostka vs. liczba).
• OCR/teksty zaszumione: typowe przekłamania znaków (0/O, 1/l), błędne odstępy, sklejone tokeny.

E. Orakle i asercje: co dokładnie sprawdzać

• Asercje na wynik: poprawność wartości po normalizacji (np. kanoniczny format daty), poprawne typy, brak utraty istotnych informacji.
• Asercje na zachowanie: czy agent wybiera właściwą ścieżkę (naprawa/odrzucenie/dopytanie), czy nie „zgaduje” krytycznych danych.
• Asercje na narzędzia: czy wywołania narzędzi są blokowane przy niepoprawnym wejściu, czy parametry są znormalizowane.
• Asercje na ślady/logi: czy w logach jest informacja o wykrytym brudzie, podjętej decyzji i ewentualnej korekcie (bez ujawniania danych wrażliwych).
• Asercje na stabilność: brak crashy, timeoutów, niekontrolowanych retrajów, pętli w agentach.

F. Reguły doboru przypadków: szerokość vs. głębokość

G. Dane testowe i prywatność

• Unikaj danych produkcyjnych wprost; jeśli musisz, stosuj anonimizację/pseudonimizację oraz minimalizację zakresu.
• Oznacz wrażliwe pola i upewnij się, że nie trafiają do logów/raportów testowych w jawnej postaci.
• Przygotuj „syntetyczne odpowiedniki” dla typowych rekordów (wystarczy reprezentatywność, nie realizm 1:1).

H. Powtarzalność i kontrola zmian

• Deterministyczność: seed dla generatorów, stałe wersje zależności, kontrola temperatury/parametrów modelu (jeśli dotyczy).
• Wersjonowanie zestawów: przypadki testowe jako kod/dane w repozytorium, z opisem intencji („dlaczego ten przypadek istnieje”).
• Kontrakty schematu: zmiany w schemacie wejścia wymagają aktualizacji testów (i odwrotnie).
• Reprodukcja incydentów: każdy błąd z produkcji powinien dać się odtworzyć jako nowy przypadek regresyjny.

I. Minimalny szkielet automatyzacji (opcjonalnie)

Jeśli potrzebujesz prostego punktu startowego, trzymaj przypadki jako dane, a wykonanie testu jako wspólny harness.

// Struktura przypadku (przykład)
{
  "name": "data_z_dwuznacznym_formatem",
  "input": { "date": "03/04/2025", "amount": "1 234,56" },
  "expect": {
    "behavior": "ASK_CLARIFY", 
    "normalized": null
  }
}

J. Ostateczna lista kontrolna (do odhaczenia)

• Kontrakt danych wejścia/wyjścia spisany i zatwierdzony.
• Wskazane pola krytyczne i ich typowe „brudy”.
• Baseline (golden path) + negatywne + naprawialne + niejednoznaczne + brzegowe przypadki.
• Jasne orakle: co ma zostać znormalizowane, co odrzucone, kiedy agent ma dopytać.
• Testy na zachowanie agenta (nie tylko na parsowanie).
• Powtarzalność: seed, wersje, stabilne warunki uruchomienia.
• Dane testowe bez ryzyka prywatności; logi nie zawierają wrażliwych wartości.
• Wersjonowanie zestawów i proces dopisywania regresji po incydentach.

7. Monitoring na produkcji: detekcja driftu i anomalii, alerty, logowanie, pętle feedbacku i utrzymanie zestawów regresyjnych

Nawet najlepiej przetestowany agent w praktyce zetknie się z danymi, które różnią się od treningowych i testowych: zmieniają się formaty eksportów, nowe wersje systemów źródłowych wprowadzają inne separatory, OCR zaczyna zwracać więcej artefaktów po zmianie skanera, a użytkownicy kopiują dane z kolejnych narzędzi. Monitoring na produkcji ma inny cel niż testy przed wdrożeniem: nie szuka „wszystkich możliwych” błędów, tylko wczesnych sygnałów, że jakość wejścia lub zachowanie agenta odchyla się od oczekiwań i wymaga reakcji.

Detekcja driftu i anomalii: co obserwować

Monitoring odporności na brudne dane zaczyna się od obserwacji dwóch warstw: charakterystyk wejścia (czy dane zaczęły wyglądać inaczej) oraz zachowania systemu (czy agent częściej się myli, wolniej działa albo częściej „naprawia” dane). Drift bywa stopniowy (np. rosnący odsetek wartości w nowym formacie), a anomalie często są punktowe (np. pojedynczy plik z błędnym kodowaniem, który wywraca proces).

• Wejście (data quality telemetry): rozkłady długości pól, udział wartości pustych, częstość znaków nietypowych, proporcje formatów dat i walut, odsetek pól z nieparsowalnymi wartościami, pojawianie się nowych symboli jednostek lub separatorów.
• Proces i wynik: odsetek rekordów odrzuconych przez walidację, liczba korekt/autonapraw, udział ścieżek fallback (np. „poproś użytkownika o doprecyzowanie”), czas przetwarzania, retry rate, błędy integracji, a także wskaźniki jakości domenowej (np. zgodność sum kontrolnych, bilansów, totalów).
• Sygnatury specyficzne dla OCR: spadek pewności rozpoznania, wzrost liczby znaków spoza alfabetu, częstotliwość typowych pomyłek (0/O, 1/I), a także pogorszenie jakości na określonych typach dokumentów.

Kluczowe jest rozróżnienie: drift danych informuje, że wejście się zmienia, ale nie przesądza o błędzie; drift jakości (np. wzrost odrzuceń, spadek trafności) sugeruje realny wpływ na automatyzację i wymaga priorytetyzacji.

Alerty: od sygnału do akcji

Alerty powinny być powiązane z decyzją operacyjną. Zbyt czułe progi generują szum, zbyt łagodne — wykrywają problem za późno. Dobrą praktyką jest ustawianie alarmów na zdarzenia, które mają jasne konsekwencje dla biznesu lub stabilności procesu.

• Alerty jakości wejścia: nagły wzrost nieparsowalnych dat/kwot, skok udziału brakujących pól, pojawienie się nowego kodowania lub nietypowych separatorów.
• Alerty zachowania agenta: wzrost błędów walidacji, częstsze przejścia na tryb „ręcznej interwencji”, spadek skuteczności ekstrakcji, zwiększenie liczby niejednoznacznych odpowiedzi.
• Alerty bezpieczeństwa i zgodności: wykrycie danych wrażliwych w polach nieprzewidzianych, nietypowe wolumeny żądań, próby wstrzyknięć w pola tekstowe.

Warto rozdzielić alerty na krytyczne (wymagające natychmiastowej reakcji: blokada przetwarzania, przełączenie na bezpieczny tryb) oraz diagnostyczne (sygnały do analizy trendów i planowania poprawy parserów, walidacji czy promptów).

Logowanie i obserwowalność: minimalne, ale wystarczające

Bez logów nie da się odtworzyć, dlaczego agent zareagował w określony sposób ani jak wyglądało „brudne” wejście. Jednocześnie logowanie surowych danych bywa ryzykowne (dane wrażliwe) i kosztowne. Celem jest odtwarzalność incydentu przy zachowaniu zasad prywatności i kosztów.

• Kontekst przetwarzania: identyfikator wersji agenta/konfiguracji, źródło danych, typ dokumentu/rekordu, ścieżka decyzyjna (np. walidacja → naprawa → akceptacja/odrzucenie).
• Ślady jakości: jakie reguły walidacji zadziałały, jakie korekty zostały wykonane, jakie pola były podejrzane i dlaczego (krótka przyczyna).
• Reprezentacje bezpieczne: hashe, statystyki, maskowanie i tokenizacja pól wrażliwych, próbki tylko tam, gdzie jest to uzasadnione i dozwolone.

Praktycznie przydatne są też „zdarzenia jakości” (np. parse_failed_date, currency_ambiguous, ocr_low_confidence) pozwalające agregować problemy bez konieczności czytania pełnych logów.

Pętle feedbacku: jak produkcja zasila rozwój odporności

Monitoring ma sens wtedy, gdy prowadzi do zamkniętej pętli: wykrycie problemu → klasyfikacja → decyzja → poprawka → weryfikacja. W kontekście brudnych danych najważniejsze jest, aby incydenty zamieniać na konkretne przypadki testowe oraz aktualizacje reguł walidacji i normalizacji.

• Triaging: szybkie przypisanie incydentu do klasy problemu (format daty, separator tysięcy, OCR, brak pola, duplikat, outlier, niespójna jednostka) oraz określenie wpływu.
• Analiza przyczyny: czy to zmiana źródła danych, nowy wariant dokumentu, degradacja OCR, czy błąd logiki agenta.
• Decyzje naprawcze: aktualizacja parserów/normalizatorów, doprecyzowanie walidacji, poprawa heurystyk, zmiana polityki fallback, dopuszczenie nowego wariantu formatu jako poprawnego.

Istotne jest też zbieranie informacji zwrotnej od użytkowników i operatorów: kiedy poprawiają dane ręcznie, jakie poprawki są najczęstsze i czy agent podaje zrozumiałe powody odrzucenia. Te sygnały często najszybciej ujawniają „ciche” awarie, w których proces formalnie działa, ale generuje więcej pracy ręcznej.

Utrzymanie zestawów regresyjnych: produkcja jako źródło „złotych” przypadków

Z czasem zestawy testowe starzeją się dokładnie tak jak dane. Dlatego przypadki z produkcji powinny regularnie zasilać regresję: nie jako losowe zrzuty, lecz jako wyselekcjonowane reprezentanty nowych wariantów brudu i ich poprawnych oczekiwań.

• Kuracja przypadków: wybieranie przykładów, które były nowe, kosztowne lub częste; usuwanie duplikatów; anonimizacja; opis oczekiwanego zachowania.
• Wersjonowanie: powiązanie testu z wersją agenta i reguł danych; utrzymywanie historii, kiedy dany przypadek przestał być problemem lub zmieniła się interpretacja biznesowa.
• Pokrycie zmian: gdy monitoring wykryje nowy wzorzec (np. nowy format waluty), powinien powstać test, który odtwarza go w sposób stabilny i mierzalny.

W praktyce to właśnie dobrze utrzymana regresja, zasilana zdarzeniami z produkcji, pozwala zwiększać odporność bez ryzyka „naprawy jednego przypadku kosztem innych” oraz skraca czas od wykrycia driftu do wdrożenia skutecznej poprawki.

8. Wdrożenie i skalowanie: środowiska, modele wdrożeniowe (cloud/on-prem), testy i utrzymanie

Odporność agenta na brudne dane nie kończy się na etapie laboratoriów. W praktyce „brud” zmienia się wraz z kanałami pozyskania danych, wersjami systemów źródłowych, lokalizacjami i zachowaniami użytkowników. Dlatego wdrożenie i skalowanie powinno traktować odporność jako cechę operacyjną: konfigurowalną, mierzalną i utrzymywaną w czasie, a nie jednorazowy test.

Kluczowe jest rozdzielenie środowisk w sposób, który minimalizuje ryzyko przeniesienia niekontrolowanych anomalii do produkcji. Typowy układ obejmuje środowisko rozwojowe (szybkie iteracje), testowe/staging (weryfikacja w warunkach zbliżonych do produkcji) oraz produkcyjne (stabilność i obserwowalność). Różnice między nimi nie powinny dotyczyć logiki walidacji i odporności, lecz przede wszystkim: poziomu restrykcji, sposobu logowania, dostępu do danych oraz polityk bezpieczeństwa.

Wybór modelu wdrożeniowego (cloud, on-prem, hybrydowy) wpływa na to, jak łatwo skalować testy odporności i jak bezpiecznie operować danymi wejściowymi. W chmurze zwykle łatwiej o elastyczną skalę (np. równoległe uruchamianie testów), standaryzację środowisk i integrację z usługami obserwowalności. On-prem częściej wygrywa tam, gdzie kluczowe są wymagania regulacyjne, ograniczenia w wynoszeniu danych lub integracje z systemami wewnętrznymi o zamkniętej sieci. Model hybrydowy bywa kompromisem: część przetwarzania i testów odbywa się lokalnie, a część automatyzacji (np. orkiestracja i raportowanie) może działać w chmurze.

Skalowanie agentów w kontekście brudnych danych dotyczy nie tylko mocy obliczeniowej, ale też zmienności wejść. Im więcej źródeł i formatów, tym większa potrzeba kontroli wersji kontraktów danych, konfiguracji parserów oraz reguł walidacji. Warto projektować system tak, aby nowe źródło danych można było dołączyć w sposób przewidywalny: z jasnym miejscem na mapowanie pól, polityką normalizacji i punktami, w których agent może bezpiecznie odmówić działania lub poprosić o doprecyzowanie.

Utrzymanie w dłuższej perspektywie wymaga podejścia „testy jako proces”. W praktyce oznacza to, że odporność na brudne dane powinna być włączona do cyklu CI/CD oraz do kryteriów akceptacji zmian w agentach, promptach, konfiguracji narzędzi i integracjach. Zmiana modelu, biblioteki OCR, parsera dat czy formatu eksportu w systemie źródłowym to nie tylko „aktualizacja techniczna” — to potencjalna zmiana rozkładu błędów wejścia, którą trzeba kontrolować.

Istotna jest również obserwowalność w produkcji, ale już na poziomie wdrożeniowym: jakie sygnały zbieramy, gdzie je przechowujemy i kto ma do nich dostęp. Dane wejściowe mogą zawierać informacje wrażliwe, więc logowanie musi równoważyć diagnostykę z prywatnością. Praktyczną zasadą jest rejestrowanie metadanych jakości (np. klasy błędu, ścieżki walidacji, liczby naprawionych pól), a nie pełnych treści dokumentów, chyba że polityki i zgody pozwalają inaczej.

Wdrożenie i skalowanie obejmuje też zarządzanie zmianą: priorytetyzację incydentów związanych z jakością danych, proces triage oraz decyzje o tym, kiedy agent ma naprawiać dane, kiedy prosić o interwencję, a kiedy bezpiecznie przerwać automatyzację. W środowiskach o wysokiej krytyczności biznesowej częściej opłaca się „degradacja kontrolowana” (np. przejście na tryb bardziej zachowawczy) niż agresywne zgadywanie brakujących elementów.

Na zakończenie – w Cognity wierzymy, że wiedza najlepiej działa wtedy, gdy jest osadzona w codziennej pracy, dlatego szkolimy praktycznie.

• Środowiska: spójna konfiguracja odporności między dev/staging/prod, różnicowanie głównie przez uprawnienia, dane i poziom logowania.
• Cloud: łatwiejsza elastyczność skali i automatyzacja pipeline’ów testowych; większy nacisk na kontrolę kosztów i polityki danych.
• On-prem: preferowane przy restrykcjach prawnych i integracjach w sieci zamkniętej; większy nacisk na utrzymanie infrastruktury i standaryzację środowisk.
• Hybryda: kompromis w organizacjach, które muszą łączyć lokalne dane z nowoczesną orkiestracją i raportowaniem.
• Utrzymanie: odporność jako element CI/CD, wersjonowanie kontraktów danych i kontrola wpływu zmian w narzędziach przetwarzania wejść.

Ostatecznie celem wdrożenia jest nie tylko uruchomienie agenta, ale utrzymanie stabilnej automatyzacji mimo nieuniknionej degradacji jakości wejść. Dobrze zaprojektowane środowiska, właściwy model wdrożeniowy oraz dyscyplina w testach i utrzymaniu sprawiają, że „brudne dane” stają się zarządzalnym ryzykiem, a nie źródłem ciągłych awarii.

Hardening endpointów agentów: rate limits, budżety tokenów i „circuit breaker” na dziwne sesje 29 kwietnia 2026

Agent AI do obsługi faktur: architektura „extract-validate-post” z progami pewności i ścieżką eskalacji 27 kwietnia 2026