Agentic RAG bez halucynacji: 9 kontroli jakości odpowiedzi (guardrails, cytowania, testy)

1. Wprowadzenie: czym jest Agentic RAG i skąd biorą się halucynacje

Agentic RAG (Retrieval-Augmented Generation w wariancie „agentowym”) to podejście, w którym model językowy nie tylko generuje odpowiedź, ale też aktywnie wykonuje kroki prowadzące do lepszego ugruntowania odpowiedzi w danych: formułuje zapytania, dobiera źródła, ocenia ich przydatność, a czasem iteruje, gdy informacje są niekompletne. W praktyce chodzi o to, by system zachowywał się bardziej jak analityk: najpierw szuka materiałów, potem je interpretuje, a dopiero na końcu odpowiada.

Klasyczny RAG bywa „jednostrzałowy”: pobiera kilka fragmentów z bazy wiedzy i na ich podstawie generuje tekst. W Agentic RAG istotna jest intencjonalność i kontrola procesu: system może korygować kierunek wyszukiwania, zawężać temat, doprecyzowywać pytanie użytkownika lub sprawdzać, czy zebrane materiały rzeczywiście wspierają tezy w odpowiedzi. To szczególnie przydatne w zadaniach, gdzie stawka jest wysoka lub wymagane są uzasadnienia: wsparcie konsultantów, obsługa procedur, analiza dokumentów, Q&A z regulaminów i polityk, pomoc w pracy z dokumentacją techniczną, a także tworzenie streszczeń i rekomendacji opartych o wewnętrzne repozytoria.

Mimo tego halucynacje nadal się zdarzają. Halucynacja w kontekście LLM to sytuacja, w której model generuje treści brzmiące wiarygodnie, ale niepoparte danymi wejściowymi albo po prostu fałszywe. W systemach RAG problem jest podstępny: nawet jeśli istnieją źródła, model może je źle zinterpretować, pominąć lub „dopowiedzieć” brakujące elementy.

Najczęstsze przyczyny halucynacji w Agentic RAG można zgrupować w kilku kategoriach:

• Braki lub szum w danych: baza wiedzy nie zawiera odpowiedzi, jest nieaktualna, niespójna albo zawiera fragmenty wyrwane z kontekstu. Model, próbując być pomocny, uzupełnia luki.
• Nietrafione wyszukiwanie: zapytanie do wyszukiwarki jest zbyt ogólne, źle sformułowane lub opiera się na błędnym założeniu. Wtedy pobrane konteksty nie odpowiadają na pytanie, a generacja idzie „na pamięć”.
• Słaba selekcja kontekstu: nawet przy dobrym retrievalu można podać modelowi fragmenty mało relewantne albo sprzeczne. Model może wybrać niewłaściwe źródło lub uśrednić sprzeczności w sposób niezgodny z dokumentami.
• Nadmierna pewność generacji: modele językowe są trenowane do płynnej kontynuacji tekstu, więc potrafią brzmieć przekonująco także wtedy, gdy nie mają wystarczających podstaw. Problem nasila presja na pełną odpowiedź zamiast bezpiecznego „nie wiem”.
• Mieszanie wiedzy ogólnej z wiedzą firmową: model może wplatać „powszechną” wiedzę z treningu tam, gdzie wymagane są konkretne zapisy z dokumentów. W efekcie odpowiedź jest logiczna, lecz niezgodna z obowiązującą polityką lub aktualną wersją procedury.
• Ataki i wrogie instrukcje: złośliwe lub niejednoznaczne polecenia potrafią nakłonić system do ignorowania kontekstu, ujawniania niepożądanych treści lub tworzenia pozornych uzasadnień.

Właśnie dlatego w Agentic RAG kluczowe jest podejście „jakość jako funkcja procesu”: nie wystarczy podłączyć wyszukiwarki do modelu. Trzeba zaprojektować mechanizmy, które ograniczają swobodę konfabulacji, wymuszają oparcie odpowiedzi na źródłach oraz wykrywają sytuacje, w których lepsza jest odmowa, doprecyzowanie pytania albo ponowna próba z inną strategią.

2. Architektura Agentic RAG: przepływ (retrieval → reasoning → generation) i punkty kontrolne

Agentic RAG to podejście, w którym model nie tylko „dopytuje” bazę wiedzy, ale też działa jak agent: planuje kroki, iteruje wyszukiwanie, ocenia trafność materiałów i dopiero potem generuje odpowiedź. W praktyce oznacza to przepływ sterowany decyzjami (a nie jednorazowe pobranie kontekstu), dzięki czemu można ograniczać halucynacje oraz lepiej obsługiwać złożone pytania. Podczas szkoleń Cognity ten temat wraca regularnie – dlatego zdecydowaliśmy się go omówić również tutaj.

Typowy przepływ składa się z trzech faz:

• Retrieval: pozyskanie materiałów źródłowych (dokumenty, fragmenty, fakty) z indeksu lub zewnętrznych repozytoriów.
• Reasoning: zaplanowanie i wykonanie kroków rozumowania na bazie pozyskanego kontekstu (czasem wieloetapowo), w tym decyzja, czy trzeba dociągnąć kolejne źródła.
• Generation: sformułowanie odpowiedzi w żądanym formacie, z zachowaniem zgodności ze źródłami oraz ograniczeń polityk (np. bezpieczeństwa, prywatności, zakresu kompetencji).

Retrieval: jak agent „szuka” i co może pójść nie tak

W warstwie retrieval agent zamienia pytanie użytkownika na zapytania do wyszukiwarki (wektorowej, hybrydowej lub klasycznej) i wybiera fragmenty, które staną się „dowodami” dla odpowiedzi. Agentic RAG różni się od prostego RAG tym, że agent może wykonywać kilka rund wyszukiwania: doprecyzować zapytanie, zmienić strategię, poszerzyć lub zawęzić zakres, a nawet przerwać, gdy dane są niewystarczające.

Kluczowe punkty kontrolne w tej fazie to:

• Intencja i zakres: czy zapytanie do retrieval odzwierciedla intencję użytkownika, a nie przypadkowe skojarzenia?
• Trafność: czy zwrócone fragmenty naprawdę odpowiadają na pytanie (nie tylko „są podobne semantycznie”)?
• Pokrycie: czy zebrany kontekst ma wystarczającą kompletność, by odpowiedzieć bez domysłów?
• Świeżość i wersjonowanie: czy źródła są aktualne i czy nie mieszamy sprzecznych wersji tej samej informacji?
• Ryzyko wstrzyknięć: czy w treści źródeł nie ma instrukcji wpływających na zachowanie modelu (np. prompt injection w dokumentach)?

Reasoning: plan, iteracje i decyzja o „jeszcze jednym wyszukaniu”

Warstwa reasoning pełni rolę kontrolera: rozbija zadanie na kroki, ocenia niepewność i decyduje, czy dostępny kontekst wystarcza. W praktyce agent może np. wykonać: (1) analizę pytania, (2) wstępne retrieval, (3) ocenę braków, (4) dodatkowe retrieval ukierunkowane na luki, (5) konsolidację faktów.

To właśnie tutaj najłatwiej ograniczać halucynacje: zamiast „dopowiedzieć” brakujące elementy, agent powinien rozpoznać braki i wrócić do retrieval albo zaplanować odmowę/odpowiedź warunkową (np. z zaznaczeniem niepewności) zgodnie z wymaganiami produktu.

Punkty kontrolne w reasoning obejmują:

• Wykrycie niepewności: czy agent umie stwierdzić, że dowodów jest za mało lub są sprzeczne?
• Spójność: czy wnioski wynikają z dostarczonych fragmentów, a nie z „wiedzy ogólnej” modelu, gdy wymagane jest oparcie o źródła?
• Rozwiązywanie konfliktów: co zrobić, gdy źródła się różnią (priorytety, hierarchia wiarygodności, potrzeba doprecyzowania)?
• Granice zadania: czy agent nie rozszerza problemu poza pytanie użytkownika, generując zbędne twierdzenia?

Generation: odpowiedź jako „produkt końcowy” z kontrolą formy i zgodności

W fazie generation model zamienia ustrukturyzowane wnioski w czytelną odpowiedź. Agentic RAG zakłada, że generacja nie jest „wolną twórczością”, tylko prezentacją wniosków opartych na dowodach. Dlatego w tej fazie szczególnie ważne są kontrolki dotyczące zgodności treści z materiałem wejściowym, formatowania oraz wymogów bezpieczeństwa.

Najczęstsze punkty kontrolne na etapie generation to:

• Zgodność ze źródłami: czy każda istotna teza ma pokrycie w kontekście, a model nie dodaje nowych faktów?
• Precyzja językowa: czy odpowiedź rozróżnia fakty od zaleceń, hipotez i interpretacji?
• Format i kompletność: czy odpowiedź spełnia wymagany układ (np. lista kroków, definicje, streszczenie), bez „uciekania” w dygresje?
• Polityki i ograniczenia: czy odpowiedź nie narusza zasad (np. prywatność, bezpieczeństwo, dozwolony zakres porad)?

Gdzie umieszcza się punkty kontrolne w całym przepływie

W dojrzałej architekturze punkty kontrolne nie są jedną „bramką na końcu”, tylko serią bramek rozsianych po całej ścieżce:

• Przed retrieval: kontrola intencji i jakości zapytań (żeby nie szukać „złego problemu”).
• Po retrieval: kontrola trafności/pokrycia oraz filtracja ryzykownych fragmentów.
• W trakcie reasoning: decyzje o iteracji, doprecyzowaniu lub przerwaniu z powodu braku danych.
• Przed generation: weryfikacja, czy materiał dowodowy jest wystarczający do odpowiedzi w wymaganym stylu i zakresie.
• Po generation: szybka walidacja końcowa: zgodność, spójność, polityki i gotowość do publikacji.

Tak ułożona architektura tworzy fundament pod dalsze mechanizmy jakości: reguły akceptacji, cytowania, walidatory orkiestrujące retry/fallback oraz testy automatyczne. Dzięki temu ograniczanie halucynacji nie jest „magiczne”, lecz wynika z jawnych decyzji i kontroli na każdym etapie.

3. 9 kontroli jakości odpowiedzi (guardrails): definicje, przykłady reguł i progi akceptacji

Guardrails to zestaw automatycznych kontroli, które oceniają (i w razie potrzeby korygują) odpowiedź modelu pod kątem: zgodności z pytaniem, oparcia o kontekst, kompletności, bezpieczeństwa oraz formatu. W Agentic RAG guardrails działają jak „bramki jakości” — mogą zatrzymać publikację odpowiedzi, wymusić doprecyzowanie, uruchomić ponowne wyszukiwanie albo wymusić odmowę, jeśli nie ma wystarczających podstaw.

Poniżej znajduje się 9 praktycznych kontroli. Każda ma: cel, przykładową regułę oraz próg akceptacji (który warto kalibrować na danych testowych).

Jak dobierać progi akceptacji (bez nadmiernego „duszenia” modelu)

• Rozdziel krytyczność: inne progi dla błędów „twardych” (format, safety, privacy) i „miękkich” (kompletność, styl).
• Kalibruj na przykładach: ustaw wstępne progi, a następnie dostrajaj je na zestawie pytań typowych dla Twojej domeny.
• Unikaj jednego super-sędziego: lepiej kilka prostszych bramek (np. groundedness + cytaty + spójność) niż jedna ocena „jakość 0–10”.
• Projektuj ścieżki wyjścia: gdy kontrola nie przechodzi, zdefiniuj co ma się stać (retry, doprecyzowanie, odmowa), zamiast tylko „FAIL”.

Minimalny przykład reguł (konfiguracyjnie)

{
  "guards": [
    {"name": "relevance", "type": "score", "threshold": 0.80, "on_fail": "retry_retrieve"},
    {"name": "groundedness", "type": "ratio", "threshold": 0.90, "on_fail": "retry_retrieve"},
    {"name": "citations", "type": "required_for_claims", "threshold": 1.00, "on_fail": "regenerate_with_citations"},
    {"name": "format", "type": "json_schema", "threshold": 1.00, "on_fail": "regenerate"},
    {"name": "safety", "type": "policy", "threshold": 1.00, "on_fail": "refuse"},
    {"name": "privacy", "type": "pii_secrets", "threshold": 1.00, "on_fail": "redact_or_refuse"}
  ]
}

Tak zdefiniowane guardrails nie eliminują kreatywności modelu, ale ograniczają swobodę tam, gdzie ryzyko halucynacji i błędów jest największe: przy faktach, cytatach, bezpieczeństwie, prywatności i maszynowym formacie wyjścia.

4. Cytowania i weryfikacja źródeł: mechanizm referencji, groundedness, detekcja fałszywych cytowań

W Agentic RAG cytowania nie są „ozdobą” odpowiedzi, tylko mechanizmem kontroli prawdziwości: użytkownik (i system) mają widzieć, na czym model oparł wnioski oraz czy przytoczone fragmenty rzeczywiście istnieją w źródłach. Dobrze zaprojektowane referencje pomagają ograniczyć halucynacje, bo wymuszają powiązanie twierdzeń z dowodami z retrievera. Zespół trenerski Cognity zauważa, że właśnie ten aspekt sprawia uczestnikom najwięcej trudności — zwłaszcza gdy trzeba przejść od „listy linków” do weryfikowalnego mapowania tezy na konkretny fragment źródła.

Mechanizm referencji: jak łączyć twierdzenia z dowodami

Najpraktyczniejszy wzorzec to cytowania na poziomie twierdzeń (claim-level), a nie tylko lista linków na końcu. Odpowiedź dzieli się na zdania/akapitowe tezy, do których przypina się identyfikatory źródeł (np. [S1], [S2]) oraz – gdy to możliwe – zakresy (strona, sekcja, timestamp, fragment).

• Źródło: dokument/strona/rekord z magazynu wiedzy, najlepiej z unikalnym ID i metadanymi (tytuł, autor, data, URL, wersja).
• Dowód (evidence): konkretny fragment tekstu zwrócony w retrievalu (cytowany dosłownie lub jako streszczenie), z informacją o miejscu w dokumencie.
• Mapowanie: relacja „twierdzenie → dowód” (jedno twierdzenie może mieć wiele dowodów; brak dowodu oznacza konieczność odmowy lub doprecyzowania).

W zastosowaniach produkcyjnych cytowania bywają też maszynowo czytelne (np. struktura JSON z listą claimów i evidence), a format widoczny dla użytkownika jest tylko prezentacją tej struktury.

Groundedness: co to znaczy, że odpowiedź jest „ugruntowana”

Groundedness (ugruntowanie) oznacza, że kluczowe treści odpowiedzi są wspierane przez treści z retrievalu, a nie „dopowiedziane” przez model. To pojęcie warto rozbić na dwa poziomy:

• Semantyczne wsparcie: dowód rzeczywiście potwierdza sens twierdzenia (nie tylko zawiera podobne słowa).
• Zakres i kompletność: odpowiedź nie wychodzi poza to, co da się uczciwie wywnioskować z dostarczonych źródeł (brak nieuzasadnionych szczegółów, dat, liczb, wyjątków).

W praktyce groundedness jest regułą: „twierdzisz → cytujesz”. Dla elementów opinii/porad dopuszcza się wyjątki, ale powinny być jasno oznaczone (np. „rekomendacja” vs „fakt z dokumentacji”).

Detekcja fałszywych cytowań: najczęstsze tryby awarii

Fałszywe cytowania to nie tylko nieistniejące linki. Typowe problemy to:

• Cytowanie „z grubsza”: źródło mówi o czymś podobnym, ale nie wspiera konkretnego wniosku.
• Przesunięcie kontekstu: model wycina zdanie z innego kontekstu, zmieniając znaczenie.
• Konfabulacja metadanych: zmyślone numery stron, sekcje, daty wersji, tytuły.
• Wskazanie źródła, którego nie było w retrievalu: model „dopisuje” autorytet z pamięci lub z wyuczonych wzorców.
• „Cytat” niebędący cytatem: fragment w cudzysłowie, który nie występuje dosłownie w dokumencie.

Podstawowe techniki weryfikacji źródeł (bez wchodzenia w implementację)

Najskuteczniejsze podejście to krótka ścieżka weryfikacji uruchamiana po wygenerowaniu odpowiedzi: system sprawdza, czy cytowania i treść są spójne z dowodami. Typowe kategorie kontroli:

• Walidacja istnienia: każde cytowanie musi wskazywać na dokument/fragment dostępny w indeksie lub repozytorium.
• Walidacja zakresu: sprawdzenie, czy przytoczone lokacje (strona/sekcja) pasują do metadanych dokumentu.
• Spójność treści: weryfikacja, czy dowód pokrywa się z tezą (np. przez dopasowanie semantyczne lub prostsze heurystyki dla liczb i nazw własnych).
• Sprawdzanie cytatów dosłownych: jeśli odpowiedź używa cudzysłowów, fragment powinien istnieć w źródle w tej samej postaci (z tolerancją na białe znaki).
• Ograniczanie „pustych” źródeł: zakaz cytowania dokumentów, które nie pojawiły się w kontekście przekazanym do generacji (zapobiega dopisywaniu autorytetów).

Różne typy cytowań i kiedy ich używać

Minimalny kontrakt danych dla cytowań (przykład struktury)

Poniższy przykład pokazuje, jak można ustandaryzować cytowania tak, by dało się je automatycznie sprawdzać (format jest poglądowy):

{
  "answer": "...",
  "claims": [
    {
      "text": "System wymaga uwierzytelnienia dwuskładnikowego.",
      "citations": [
        {
          "source_id": "doc_127",
          "locator": {"type": "section", "value": "Security/Authentication"},
          "evidence": "Two-factor authentication (2FA) is required for all accounts."
        }
      ]
    }
  ]
}

Praktyczne zasady prezentacji cytowań użytkownikowi

• Jednoznaczne identyfikatory źródeł i czytelne rozwinięcie (tytuł, data, link) po kliknięciu.
• Rozróżnienie faktów i rekomendacji: fakty z cytowaniami, sugestie jako sugestie.
• Umiar w liczbie źródeł: lepiej 1–3 trafne dowody na tezę niż 10 luźno powiązanych linków.
• Bez udawanej precyzji: jeśli nie ma stabilnych numerów stron/sekcji, lepiej podać fragment i nagłówek niż zmyślony „str. 42”.

Tak rozumiane cytowania są fundamentem „odpowiedzi bez halucynacji”: nie gwarantują nieomylności, ale wprowadzają wymuszalną odpowiedzialność za każde kluczowe twierdzenie i umożliwiają automatyczną weryfikację spójności.

5. Walidatory i orkiestracja: pseudokod kontrolerów, retry/fallback, refusal i policy checks

W Agentic RAG sama obecność „guardrails” nie wystarcza — kluczowe jest to, jak są one uruchamiane, w jakiej kolejności i co dzieje się, gdy kontrola jakości nie przejdzie. Za to odpowiada orkiestracja: warstwa sterująca przebiegiem (plan → retrieval → odpowiedź) oraz podejmująca decyzje o retry, fallback, skróceniu odpowiedzi, eskalacji do odmowy (refusal) albo zmianie strategii.

Walidator vs. kontroler: podstawowe role

Praktycznie warto rozdzielić dwie odpowiedzialności:

• Walidatory – funkcje/komponenty oceniające artefakt (np. zapytanie, wyniki wyszukiwania, draft odpowiedzi) i zwracające werdykt pass/fail oraz uzasadnienie.
• Kontrolery (orkiestrator) – logika decyzyjna, która na podstawie werdyktów walidatorów wybiera następny krok (retry, fallback, refusal, skrócenie, zmiana promptu, zmiana narzędzia).

Gdzie wpinamy walidatory (i po co)

Orkiestracja zwykle obejmuje kilka „bramek” w krytycznych punktach przepływu. Bez wchodzenia w szczegóły samych reguł, najczęściej spotkasz:

• Pre-check (wejście): czy pytanie jest dozwolone, czy wymaga doprecyzowania, czy zawiera prompt injection.
• Post-retrieval check: czy znaleziono cokolwiek relewantnego; czy źródła spełniają minimalne kryteria (np. typ, świeżość, zaufanie).
• Draft answer check: czy odpowiedź trzyma się kontekstu, ma wymagany format, nie zawiera treści zabronionych.
• Final gate: „ostatnia bramka” przed wysłaniem – m.in. spójność, brak przecieków danych, minimalny poziom ugruntowania.

Pseudokod orkiestratora (kontrolery + walidatory)

Poniżej uproszczony schemat: walidatory są małe i wymienne, a kontroler spina je w reguły przepływu z limitami prób.

def answer(user_query, session):
    # 1) Pre-check: policy + injection + wymagane doprecyzowanie
    verdict = run_validators("pre", user_query, session)
    if verdict.blocked:
        return refusal(verdict.reason)  # policy refusal
    if verdict.needs_clarification:
        return ask_clarifying_question(verdict.question)

    # 2) Retrieval (z retry na zmianę zapytania)
    ctx = None
    for attempt in range(2):
        retrieval_query = rewrite_query(user_query, attempt=attempt)
        ctx = retrieve(retrieval_query)

        r = run_validators("post_retrieval", ctx, session)
        if r.pass_:
            break
    if ctx is None or not r.pass_:
        return fallback_no_sources(user_query)  # np. bez odpowiedzi merytorycznej lub z prośbą o źródła

    # 3) Generation (z retry na zmianę stylu/ograniczenie twierdzeń)
    for attempt in range(2):
        draft = generate(user_query, ctx, mode=("strict" if attempt else "normal"))

        g = run_validators("draft", draft, ctx, session)
        if g.pass_:
            final = draft
            break
    else:
        return refusal("Nie mogę bezpiecznie udzielić odpowiedzi na podstawie dostępnych źródeł.")

    # 4) Final gate
    f = run_validators("final", final, ctx, session)
    if not f.pass_:
        return refusal(f.reason)

    return final

Retry: kiedy ma sens, a kiedy szkodzi

Retry jest użyteczny, gdy niepowodzenie wynika z problemu, który da się skorygować zmianą parametrów (np. inne sformułowanie zapytania, większy limit dokumentów, tryb „bardziej ostrożny”). Jest szkodliwy, gdy prowadzi do „mielenia” i rosnących kosztów bez poprawy jakości.

• Dobry retry: brak wyników retrieval → rewrite query; zbyt ogólna odpowiedź → tryb „strict” z ograniczeniem twierdzeń.
• Zły retry: policy violation → retry nie zmieni faktu, że treść jest zabroniona; lepszy jest natychmiastowy refusal.

W orkiestracji często ustala się twarde limity (np. 1–2 próby na etap) oraz budżet czasu, po którym system przechodzi do fallback/refusal.

Fallback: strategie awaryjne (bez „udawania” wiedzy)

Fallback to kontrolowany tryb degradacji, który ma utrzymać użyteczność bez generowania nieugruntowanych twierdzeń. Typowe warianty:

• Fallback na doprecyzowanie: gdy retrieval jest słabe, agent prosi o kontekst (np. zakres, jurysdykcja, dokument, data).
• Fallback na odpowiedź proceduralną: zamiast faktów — wskazówki, jak zdobyć dane (kroki, jakie źródła sprawdzić).
• Fallback na częściową odpowiedź: tylko te fragmenty, które przechodzą walidację; reszta jako „nie wiem na podstawie źródeł”.
• Fallback na inne narzędzie: np. inny indeks, inny tryb wyszukiwania (semantyczne vs. keyword), inny retriever.

Refusal: odmowa jako kontrola jakości (i element bezpieczeństwa)

Refusal nie powinien być „porażką systemu”, tylko jawnie zaprojektowaną akcją kontrolera, uruchamianą gdy:

• żądanie jest niezgodne z politykami (policy checks),
• brak wystarczających źródeł do odpowiedzi przy wymaganym poziomie pewności,
• nie można usunąć ryzyka po retry/fallback (np. odpowiedź wciąż jest nieugruntowana).

Dobra odmowa jest krótka, neutralna i — jeśli to możliwe — proponuje bezpieczną alternatywę (np. pytanie doprecyzowujące albo zakres, w którym można pomóc).

Policy checks: oddziel warstwę zgodności od jakości merytorycznej

Policy checks warto traktować jako osobną klasę walidatorów: ich celem nie jest „czy odpowiedź jest dobra”, tylko „czy wolno ją wygenerować i zwrócić”. W orkiestracji zwykle mają one pierwszeństwo (fail-fast) i nie powinny być „naprawiane” retry, chyba że retry oznacza zmianę formy na bezpieczną (np. przejście na uogólnione informacje zamiast instruktażu).

Minimalny interfejs walidatora (do wymienialności)

Aby walidatory dało się łatwo podmieniać i łączyć, utrzymuje się prosty kontrakt:

class Verdict:
    def __init__(self, pass_, blocked=False, needs_clarification=False, reason="", signals=None):
        self.pass_ = pass_
        self.blocked = blocked
        self.needs_clarification = needs_clarification
        self.reason = reason
        self.signals = signals or {}

class Validator:
    def run(self, payload, context, session) -> Verdict:
        raise NotImplementedError

Dzięki temu kontroler może agregować wyniki (np. „jeśli jakikolwiek walidator zablokuje → refusal”, „jeśli któryś wymaga doprecyzowania → pytanie uzupełniające”), bez mieszania logiki oceny z logiką decyzji.

Najczęstsze błędy orkiestracji (krótko)

• Brak deterministycznej ścieżki awaryjnej: system „kombinuje” zamiast przejść do fallback/refusal po limicie prób.
• Mieszanie polityk i jakości: próby „naprawy” policy violation przez kolejne prompty zamiast bezpiecznej odmowy.
• Zbyt późne bramki: walidacja dopiero na końcu zwiększa koszty (tokeny, latency) i ryzyko wycieku.
• Nadmierny retry: rosną koszty i czas, a halucynacje bywają tylko bardziej „wypolerowane”.

6. Testy automatyczne: unit/integration/e2e, zestawy danych, symulacje ataków i regresje

W Agentic RAG testy automatyczne nie służą wyłącznie sprawdzeniu „czy działa”, ale czy system pozostaje uziemiony w źródłach, nie przecieka polityk i nie degraduje jakości po zmianach promptów, modeli, indeksu lub konfiguracji narzędzi. Ponieważ agent podejmuje decyzje (np. kiedy wyszukiwać, kiedy odrzucić, jak dobrać narzędzia), testy powinny obejmować zarówno pojedyncze komponenty, jak i zachowanie całego przepływu w realistycznych scenariuszach.

6.1. Unit vs integration vs e2e — co testować i po co

Zastosowanie w praktyce: unit testy dają szybkie sprzężenie zwrotne dla zmian w regułach i parserach; integration testy chronią przed degradacją po zmianach w indeksie i konfiguracji; e2e testy zapewniają, że agent zachowuje się bezpiecznie w scenariuszach użytkownika.

6.2. Zestawy danych testowych: co powinny zawierać

Zamiast jednego „złotego” zbioru, warto utrzymywać kilka małych, celowanych zestawów pokrywających ryzyka typowe dla Agentic RAG. Kluczowa jest powtarzalność (wersjonowanie dokumentów i indeksu) oraz pokrycie przypadków brzegowych (wymuszających odmowę, doprecyzowanie lub dodatkowe wyszukiwanie).

• QA grounded: pytania, na które odpowiedź jest wprost w dokumentach; oczekiwane cytowania do konkretnych fragmentów.
• Unanswerable: pytania, na które korpus nie zawiera odpowiedzi; oczekiwana odmowa lub prośba o doprecyzowanie (bez „zgadywania”).
• Ambiguity: pytania wieloznaczne; oczekiwane pytanie doprecyzowujące albo odpowiedź warunkowa z jasnymi założeniami.
• Conflicting sources: sprzeczne dokumenty; oczekiwane wskazanie rozbieżności i oparcie się na konkretnych źródłach.
• Policy & compliance: treści, które powinny skutkować odmową lub sanitacją (np. próby wyłudzenia danych, prośby o instrukcje niedozwolone).
• Tooling: scenariusze wymagające użycia narzędzia (np. wyszukiwanie w bazie, kalkulacja); oczekiwane poprawne decyzje o wywołaniu narzędzia.
• Localization: pytania wielojęzyczne / mieszane; oczekiwany język odpowiedzi i spójność cytowań niezależnie od języka.

Dobrym nawykiem jest przechowywanie przypadków testowych jako rekordów: prompt użytkownika, kontekst/korpus (wersja), oczekiwany typ zachowania (odpowiedź/odmowa/dopytanie), oraz minimalne warunki akceptacji (np. wymagane cytowanie, zakaz pewnych stwierdzeń, maks. liczba kroków agenta).

6.3. Symulacje ataków: red teaming w CI

Agentic RAG jest podatny nie tylko na klasyczne prompt injection, ale też na ataki „pośrednie” (w dokumentach) oraz na manipulacje planowaniem (np. wymuszenie pominięcia retrieval). Automatyczne symulacje ataków powinny stać się częścią pipeline’u testowego — w formie krótkich, powtarzalnych scenariuszy.

• Prompt injection (user): próby obejścia zasad, wymuszenia ujawnienia system promptu, kluczy, konfiguracji narzędzi.
• Indirect prompt injection (docs): dokument zawiera instrukcje typu „zignoruj poprzednie polecenia”; test sprawdza, czy model traktuje to jako treść źródła, a nie dyrektywę.
• Citation spoofing: użytkownik żąda cytatu do nieistniejącego dokumentu lub wprowadza fałszywą referencję; test oczekuje braku „zmyślonych” źródeł.
• Data exfiltration: prośby o PII lub dane wrażliwe; oczekiwane blokady/odmowy zgodne z polityką.
• Tool misuse: wymuszenie wywołania narzędzia z niebezpiecznymi parametrami lub w nieautoryzowanym celu; oczekiwane zatrzymanie przez walidację.
• Jailbreak przez wieloetapowość: eskalacja w kilku turach (najpierw „niewinne” pytania, potem obejście); testy powinny odtwarzać dialog, nie tylko pojedynczy prompt.

6.4. Regresje jakości: jak nie „zepsuć” RAG przy zmianach

W Agentic RAG regresje często pochodzą z pozornie niewinnych zmian: nowy embedding, inne parametry chunkingu, aktualizacja promptu planera, zmiana rerankera lub modelu generującego. Dlatego testy regresyjne powinny mierzyć nie tylko „zgodność tekstu”, ale też własności odpowiedzi.

• Snapshoty zachowań: porównuj wyniki na stałym zestawie pytań przed/po zmianie (z kontrolą wersji indeksu i dokumentów).
• Asercje właściwości zamiast literalnych odpowiedzi: np. „musi zawierać ≥1 cytowanie”, „nie może zawierać stwierdzeń bez pokrycia w źródłach”, „musi odmówić w scenariuszu X”.
• Testy stabilności: uruchomienia wielokrotne (różne seedy/temperatury) i sprawdzenie, czy system mieści się w akceptowalnym zakresie odchyleń.
• Progi wydajności: limity czasu, liczby kroków agenta, liczby wywołań narzędzi — regresja bywa „ukryta” jako wzrost kosztu lub latencji.

6.5. Minimalny szkic implementacji testu (przykład)

Poniższy przykład pokazuje ideę testu e2e opartego o własności (nie o identyczny tekst). Jest to celowo skrótowe — chodzi o wzorzec asercji.

# pseudokod
case = {
  "query": "Podaj wymagania X i zacytuj źródło.",
  "expected": {
    "must_cite": True,
    "must_refuse": False,
    "max_steps": 6
  }
}

result = agent.run(case["query"])

assert result.steps <= case["expected"]["max_steps"]
assert (len(result.citations) > 0) == case["expected"]["must_cite"]
assert result.refusal == case["expected"]["must_refuse"]
assert result.policy_violations == []

6.6. Organizacja testów w pipeline (CI/CD)

• Szybki tor (na każdy commit): unit + mały pakiet integration (kilkanaście przypadków), deterministyczna konfiguracja.
• Tor rozszerzony (np. nightly): e2e na pełnych zestawach, wieloturnowe dialogi, symulacje ataków, testy stabilności.
• Bramki akceptacji: merge/blokada wdrożenia, gdy spadnie groundedness/cytowania, wzrośnie odsetek halucynacji lub przekroczone zostaną limity kosztu/latencji.

Taki podział pozwala utrzymać krótką pętlę informacji zwrotnej dla deweloperów, a jednocześnie regularnie „przepalać” pełen pakiet ryzyk typowych dla agentów korzystających z retrieval i narzędzi.

7. Metryki skuteczności: jak mierzyć jakość guardrails (precision/recall), koszty i latency

Guardrails w Agentic RAG mają sens tylko wtedy, gdy da się je mierzyć: czy faktycznie blokują ryzykowne odpowiedzi, czy nie psują użyteczności produktu i ile kosztują w utrzymaniu. Dobre metryki nie sprowadzają się do „spadku halucynacji” — muszą obejmować skuteczność detekcji, wpływ na zachowanie systemu oraz narzut na czas i budżet.

Skuteczność guardrails: precision/recall i koszt błędów

Większość kontroli jakości działa jak klasyfikator: przepuszcza odpowiedź albo uruchamia korektę, retry, fallback lub odmowę. Dlatego naturalnym językiem oceny są metryki typu precision i recall, liczone dla zdarzeń „powinno zostać zatrzymane” vs „powinno przejść”.

• Precision (precyzja): jaki odsetek zatrzymań był uzasadniony. Niska precyzja oznacza dużo fałszywych alarmów, które psują UX (zbyt częste odmowy, niepotrzebne retry, zaniżona „helpfulness”).
• Recall (czułość): jaki odsetek realnie niebezpiecznych lub nieuziemionych odpowiedzi guardrail wykrył. Niski recall oznacza, że halucynacje i naruszenia polityk przeciekają do użytkownika.
• F1 / Fβ: pojedynczy wskaźnik łączący precyzję i czułość. W praktyce często ważniejsze jest przesunięcie w stronę recall (większa kara za przepuszczenie błędu), ale zależy to od ryzyka domeny.
• Koszt FP vs FN: te same wartości precision/recall mogą oznaczać różne ryzyko biznesowe. Fałszywe pozytywy (FP) podnoszą frustrację i koszty, fałszywe negatywy (FN) generują ryzyko reputacyjne/prawne. Warto jawnie zdefiniować, który błąd jest droższy.

Żeby te metryki miały sens, trzeba zdefiniować etykietę prawdy („gold”) na poziomie: (a) całej odpowiedzi, (b) poszczególnych twierdzeń, lub (c) akcji agenta (np. czy w ogóle powinien użyć retrieval). Im bliżej poziomu twierdzeń, tym lepsza diagnostyka — ale rośnie koszt oceny.

Metryki uziemienia i halucynacji: „groundedness” jako cel

W RAG kluczowe jest nie tylko „czy odpowiedź jest poprawna”, ale czy jest oparta na dostarczonych źródłach. Dlatego warto oddzielać błędy faktograficzne od błędów uziemienia.

• Odsetek odpowiedzi uziemionych: udział odpowiedzi, które da się w pełni poprzeć materiałem wejściowym (kontekstem, dokumentami, bazą wiedzy).
• Coverage cytowań: jaka część kluczowych twierdzeń ma przypisane źródło; niska wartość sugeruje „opowiadanie” zamiast raportowania.
• Wskaźnik „unsupported claims”: ile odpowiedzi zawiera istotne twierdzenia bez pokrycia w kontekście (to praktyczny obraz halucynacji w RAG).

Te metryki pomagają rozdzielić problemy: czy zawodzi retrieval (brak dowodów), czy reasoning (złe wnioskowanie), czy generacja (dopisanie treści). Guardrail może poprawiać tylko wybrany etap — pomiar powinien to pokazać.

Metryki użyteczności: czy guardrails nie „psują” produktu

Nawet idealne bezpieczeństwo nie obroni się, jeśli system stale odmawia lub produkuje mało pomocne odpowiedzi. Dlatego mierzy się równolegle:

• Acceptance rate: odsetek interakcji zakończonych odpowiedzią zaakceptowaną przez walidatory (bez eskalacji do odmowy lub agresywnego fallbacku).
• Refusal rate: częstotliwość odmów — osobno dla odmów uzasadnionych i „nadmiarowych”.
• Regeneration / retry rate: jak często system musi poprawiać odpowiedź; to proxy zarówno jakości modelu, jak i „agresywności” guardrails.
• Task success: czy użytkownik finalnie osiąga cel (metryki produktowe, np. rozwiązanie problemu, zakończenie procesu).

W praktyce guardrails powinny podnosić bezpieczeństwo przy minimalnym spadku task success. Jeśli spadek jest duży, to sygnał, że reguły są zbyt restrykcyjne lub źle skalibrowane do domeny.

Koszty: tokeny, narzut walidacji i „koszt na poprawną odpowiedź”

Agentic RAG często zawiera dodatkowe kroki: ekstra retrieval, reranking, walidatory, ponowne generacje. To wszystko kosztuje. Same „koszt na zapytanie” bywa mylące, dlatego warto patrzeć na koszty w funkcji jakości.

• Cost per request: średni koszt obsługi zapytania (model + retrieval + walidacja). To podstawa budżetowania.
• Cost per accepted answer: koszt tylko tych odpowiedzi, które przeszły kontrolę jakości. Jeśli retry rate rośnie, ten wskaźnik rośnie szybciej niż cost per request.
• Marginal cost of safety: przyrost kosztu po włączeniu danego guardraila (lub podniesieniu progu). Ułatwia decyzje, które kontrole dają najlepszy zwrot.
• Budget compliance: odsetek zapytań mieszczących się w limicie kosztu (ważne przy dynamicznych pętlach retry).

Dobrą praktyką jest mierzenie kosztu osobno dla segmentów: proste pytania (bez retrieval), pytania wymagające źródeł oraz przypadki ryzykowne (z odmową). Guardrails zwykle najwięcej kosztują właśnie tam, gdzie ryzyko jest największe — i to jest oczekiwane, o ile metryki skuteczności to uzasadniają.

Latency: nie tylko średnia, ale ogon rozkładu

W systemach agentowych opóźnienie rośnie skokowo, gdy uruchamiają się dodatkowe kroki (kolejny retrieval, dodatkowa generacja, walidacja). Dlatego nie wystarczy średnia.

• p50 / p95 / p99 latency: typowy czas odpowiedzi oraz „ogon” — to ogon często decyduje o odczuciu jakości.
• Latency by path: osobno dla ścieżki bez retry i ścieżek z retry/fallback/odmową; pozwala zobaczyć, co realnie spowalnia system.
• Timeout rate: odsetek zapytań, które nie domykają się w czasie; rośnie, gdy guardrails powodują zbyt wiele iteracji.

Optymalny system to nie ten, który ma minimalne latency, tylko taki, który świadomie „płaci” opóźnieniem tam, gdzie ryzyko jest wysokie — i potrafi utrzymać p95/p99 w akceptowalnych granicach.

Kalibracja progów i monitoring regresji

Metryki są użyteczne dopiero, gdy prowadzą do decyzji o progach akceptacji. Dla każdej kontroli warto ustalić: docelowy poziom recall (by ograniczać ryzyko) oraz maksymalny dopuszczalny spadek precision (by nie zabić użyteczności), a następnie obserwować wpływ na cost i latency.

W produkcji kluczowe są dwa aspekty monitoringu:

• Drift danych: zmiana typu zapytań lub dokumentów może obniżyć groundedness i podnieść retry rate bez zmiany kodu.
• Regresje po zmianach: każda aktualizacja modelu, promptów, indeksu czy polityk powinna być oceniana na tych samych metrykach, aby nie „poprawić” bezpieczeństwa kosztem katastrofalnego UX lub budżetu.

W efekcie metryki guardrails to zestaw naczyń połączonych: precision/recall opisują skuteczność, groundedness mówi „czy jest oparte na źródłach”, a cost i latency pokazują cenę tej pewności. Dopiero równowaga tych czterech wymiarów pozwala utrzymać Agentic RAG bez halucynacji w realnym produkcie.

8. Checklist wdrożeniowa produkcyjna: observability, monitorowanie, incident response i ciągłe ulepszanie

Agentic RAG w produkcji to nie tylko „lepsze prompty” i „dobry wektorowy indeks”, ale system, który musi być mierzalny, audytowalny i odporny operacyjnie. Poniższa checklista skupia się na praktykach, które ograniczają ryzyko halucynacji i niekontrolowanych zachowań agenta poprzez widoczność (observability), wczesne wykrywanie problemów, sprawną obsługę incydentów oraz stałe doskonalenie.

Observability: co logować i jak zapewnić ścieżkę audytu

• Ślad wykonania (trace) całego przebiegu: identyfikator żądania, czas, wersja konfiguracji, użyty model, parametry generacji oraz decyzje podejmowane przez komponenty (np. wybór narzędzia, retry, fallback).
• Kontekst wejściowy i wyjściowy: pytanie użytkownika, wynikowe fragmenty odpowiedzi oraz skrócone metadane, które pozwalają odtworzyć przebieg bez gromadzenia nadmiarowych danych wrażliwych.
• Artefakty retrieval: zapytanie do wyszukiwarki, lista dokumentów/fragmentów wraz z metadanymi (źródło, timestamp, wersja), wyniki rankingu i progi odcięcia.
• Oceny i sygnały jakości: wyniki walidacji, flagi ryzyka (np. niska zgodność z kontekstem, wykryty konflikt źródeł, podejrzenie wstrzyknięcia instrukcji).
• Bezpieczeństwo i prywatność logów: redakcja danych wrażliwych, polityka retencji, kontrola dostępu, separacja środowisk oraz możliwość usunięcia danych na żądanie.

Monitorowanie: metryki, alerty i progi operacyjne

• Metryki jakości odpowiedzi: odsetek odpowiedzi odrzuconych przez kontrolki, liczba retry na żądanie, udział fallbacków, udział odpowiedzi z cytowaniami oraz odsetek odpowiedzi wymagających odmowy.
• Metryki „groundedness” operacyjnej: sygnały typu „brak wystarczających źródeł”, „zbyt niska pewność retrieval”, „niezgodność odpowiedzi z przytoczonymi fragmentami” – monitorowane jako trendy i skoki.
• Metryki wydajności i kosztów: latency end-to-end, czasy etapów (retrieval/reasoning/generation), obciążenie narzędzi, cache hit-rate, tokeny i koszt na żądanie.
• Metryki niezawodności: błędy integracji z narzędziami, time-outy, degradacja jakości indeksu, wzrost pustych wyników wyszukiwania.
• Alerty oparte o anomalie: wykrywanie nagłych zmian (np. wzrost odmów, skok retry, spadek cytowań, wzrost odpowiedzi „pewnych siebie” bez źródeł).
• Podział dashboardów: osobne widoki dla produktu (jakość i satysfakcja), dla inżynierii (latency i błędy) oraz dla ryzyka/compliance (audyt, naruszenia polityk).

Incident response: gotowość na halucynacje, błędne źródła i nadużycia

• Klasyfikacja incydentów: osobno traktuj błędy faktograficzne, błędne cytowania, ujawnienie danych, naruszenia polityk, podatność na prompt injection oraz awarie narzędzi.
• Runbooki i procedury eskalacji: jasne kryteria, kiedy włączyć tryb bezpieczny (np. wymuszona odmowa lub ograniczenie narzędzi), kiedy zatrzymać rollout i kto podejmuje decyzję.
• Szybkie ograniczanie szkód: przełączenie na konserwatywne ustawienia, ograniczenie zakresu odpowiedzi do cytowanych źródeł, czasowe wyłączenie niepewnych konektorów danych.
• Analiza przyczyny (RCA): rozróżnienie, czy problem wynika z retrieval (złe/nieaktualne dane), z orkiestracji (zła decyzja agenta), czy z generacji (nieuzasadnione twierdzenia).
• Komunikacja: przygotowane szablony dla zespołów produktowych i wsparcia, aby konsekwentnie informować o ograniczeniach, poprawkach i obejściach.

Ciągłe ulepszanie: pętla feedbacku, wersjonowanie i kontrolowane zmiany

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

• Zbieranie feedbacku: sygnały od użytkowników (negatywne oceny, zgłoszenia błędów) powiązane z trace, aby można było odtworzyć warunki i źródła odpowiedzi.
• Priorytetyzacja poprawek: osobna kolejka dla problemów „krytycznych” (bezpieczeństwo, compliance, dane wrażliwe) oraz dla jakości merytorycznej.
• Wersjonowanie wszystkiego: promptów, reguł, progów, konfiguracji retrieval, konektorów, indeksów i zestawów danych – tak, aby wynik dało się porównać między wydaniami.
• Kontrolowane rollouty: stopniowe wdrażanie zmian z możliwością szybkiego wycofania; porównywanie zachowania na tym samym typie zapytań.
• Higiena wiedzy: cykliczna weryfikacja jakości i aktualności dokumentów, usuwanie duplikatów, kontrola uprawnień do źródeł oraz monitorowanie „dryfu” treści.
• Zarządzanie ryzykiem: regularne przeglądy polityk, aktualizacja listy nadużyć i scenariuszy ataków, dopasowanie ograniczeń do realnego wykorzystania systemu.

Minimalny „definition of done” dla produkcji

• Ścieżka audytu pozwala odpowiedzieć: skąd wzięły się źródła, dlaczego agent podjął decyzję i które kontrolki zadziałały.
• Alerty wykrywają wzrost ryzyka halucynacji i regresje jakości szybciej, niż zauważy je użytkownik.
• Runbook umożliwia przełączenie w tryb bezpieczny w minutach, a nie dniach.
• Proces zmian chroni przed „cichymi” regresjami: każda modyfikacja jest wersjonowana, monitorowana i możliwa do wycofania.

KNIME w 2026: 12 gotowych wzorców workflow do czyszczenia danych bez kodu 26 marca 2026

ThinkCell vs PowerPoint Add-ins 2026: 9 różnic, które widać dopiero w dużych deckach 24 marca 2026