Przejdź do treści

Praktyczne zastosowania

Debugowanie agentów AI: Jak złapać błędy

Zaktualizowano: Autor: Andrzej Niemiec7 min czytania

Agenci AI zawodzą po cichu. Poznaj 4 źródła dryfu, metryki monitorowania i narzędzia do debugowania w produkcji.

Debugowanie agentów AI: Jak złapać błędy
Spis treści
  1. Czemu agent AI nagle zaczyna odpowiadać nonsensem?
  2. Cztery źródła dryfu agentów — i jak je odróżnić
  3. Pięć metryk, które musisz monitorować
  4. Jak zbudować dashboard do monitorowania dryfu
  5. Trzy strategie naprawcze
  6. Najczęstsze pytania
  7. Źródła

Czemu agent AI nagle zaczyna odpowiadać nonsensem?

Agenci AI zawodzą inaczej niż tradycyjne oprogramowanie. Zamiast crash-u dostajesz "cichą degradację" — system pracuje, ale coraz gorzej. W publicznych dyskusjach programistów (Reddit, GitHub) najczęściej pojawiają się opisy tego zjawiska: agent wykonuje kroki, ale zwraca błędne dane, pomija walidacje lub zaczyna preferować niewłaściwe narzędzia [1].

Problem polega na tym, że finalna odpowiedź ("Final answer: 245 000 zł") nie mówi, skąd wzięła się ta liczba. Logi pokazują tylko wynik, nie ścieżkę decyzyjną. Dlatego zespoły widzą symptomy (błędne odpowiedzi), ale nie wiedzą, gdzie szukać przyczyny.

Cztery źródła dryfu agentów — i jak je odróżnić

Dryf agenta to zmiana w zachowaniu systemu, która kumuluje się w czasie. Może wynikać z czterech głównych przyczyn:

1. Retriever zwraca złe dokumenty

Retriever to komponent, który wyszukuje dokumenty z bazy wiedzy. Zamiast zwracać aktualne umowy, może zacząć zwracać archiwa. Problem nie polega na tym, że zwraca "złe" dokumenty, ale że zwraca dokumenty z niewłaściwego kontekstu (np. stare wersje zamiast aktualnych).

Jak to wykryć: Monitoruj metrykę retrieval precision@3 — odsetek przypadków, w których co najmniej jeden z trzech najlepszych wyników jest relewantny dla zapytania. Wartość poniżej 0,8 to alarm [2].

LangSmith (platforma obserwowalności dla agentów LLM) pozwala ustawić alerty na spadek tej metryki. Gdy wartość spadnie poniżej progu, zespół dostaje powiadomienie [2].

2. Tool zwraca dane w niewłaściwym formacie

Tool to funkcja, którą agent może wywołać (np. API do bazy danych, Notion, Slack). Problem nie polega na tym, że tool nie działa, ale że zwraca dane, które agent nie potrafi przetworzyć — puste pola, niepoprawny JSON, brakujące klucze.

Jak to wykryć: Automatyczna walidacja outputów toolów. Przykład z Pydantic (biblioteka Pythona do walidacji danych):

from pydantic import BaseModel, ValidationError

class NotionPage(BaseModel):
    id: str
    title: str  # Pole wymagane
    last_edited_time: str

def validate_tool_output(output: dict):
    try:
        NotionPage(**output)
        return True
    except ValidationError as e:
        log_error(e)
        return False

Platformy do debugowania agentów generują wizualizację drzewa wywołań toolów, pokazując, które narzędzia zostały wywołane, jakie dane zwróciły i gdzie nastąpił "silent failure".

3. Memory zanieczyści kontekst

Memory to historia konwersacji, którą agent przechowuje między interakcjami. Problem: błędy w serializacji (niepoprawne formatowanie JSON) lub duplikaty w chat_history powodują, że agent pracuje z zaśmieconą historią.

Jak to wykryć: Monitoruj rozmiar chat_history między interakcjami. Wzrost o >5% na interakcję to sygnał zanieoczyszczenia. Resetuj memory co 10 interakcji lub gdy użytkownik zmienia temat.

4. Sam model zmienił zachowanie

Model odpowiada za ~15% przypadków dryfu. Przyczyny: aktualizacje API (OpenAI zmienia domyślne parametry) lub dryf danych treningowych (model zaczyna preferować inne wzorce).

Jak to wykryć: Monitoruj perplexity (miarę niepewności modelu). Wzrost o >10% może wskazywać na dryf. Dedykowane narzędzia do monitorowania oferują dashboard do śledzenia takich anomalii.

Pięć metryk, które musisz monitorować

MetrykaNarzędzieTargetCo oznacza
Retrieval precision@3LangSmith>0,8Czy retriever zwraca relewantne dokumenty?
Tool output validityWłasne skrypty (Pydantic)>95%Ile wywołań toolów zwraca poprawne dane?
Memory driftWłasne logi<5% wzrostu/interakcjęCzy chat_history rośnie w przewidywalnym tempie?
Perplexity driftDedykowane narzędzia<10% wzrostuCzy model jest stabilny?
Response timeLangSmith<2sCzy agent nie zwalnia?

Jak zbudować dashboard do monitorowania dryfu

Narzędzia

LangSmith — platforma obserwowalności dla agentów LLM. Oferuje:

  • Śledzenie każdego kroku wykonania agenta (prompt, odpowiedź modelu, wywołania toolów, wyniki).
  • Ewaluacje offline (testy regresyjne przed wdrożeniem) i online (monitorowanie w produkcji).
  • Alerty na degradację jakości [2].

Dedykowane platformy debugowania — generują drzewo wywołań toolów i wizualizują "silent failures".

Narzędzia do monitorowania modeli — dashboard do śledzenia perplexity, długości odpowiedzi i anomalii w outputach.

Własne skrypty — walidacja outputów toolów za pomocą Pydantic lub JSON Schema.

Przykładowy SLA

  • Max 2% dryfu na tydzień — jeśli którykolwiek z metryk spadnie o >2%, uruchamiasz procedurę naprawczą.
  • Alerty w czasie rzeczywistym — zespół dostaje powiadomienie w ciągu 5 minut od wykrycia dryfu.
  • Rollback w ciągu 30 minut — przywrócenie ostatniej stabilnej wersji agenta.

Trzy strategie naprawcze

Rollback

Przywróć ostatnią stabilną wersję agenta. LangSmith pozwala oznaczyć wersję jako "stable" i wrócić do niej jednym kliknięciem [2].

Kiedy stosować: Gdy dryf jest nagły i nie masz czasu na diagnozę.

Fallback

Zbuduj siatkę bezpieczeństwa dla krytycznych ścieżek. Przykład:

if retrieval_precision@3 < 0.8:
    fallback_to_keyword_search()  # Użyj prostszego retrievera

Kiedy stosować: Gdy dryf dotyczy tylko części funkcjonalności.

Retraining

Aktualizuj retriever (dodaj nowe dokumenty) lub model (dostosuj prompty, zmień parametry).

Kiedy stosować: Gdy dryf jest systematyczny i wynika ze zmian w danych.

Najczęstsze pytania

Czy LangChain to to samo co LangSmith?

Nie. LangChain to otwartoźródłowy framework do budowy aplikacji i agentów. LangSmith to oddzielna, komercyjna platforma obserwowalności, która działa z LangChain i innymi frameworkami [3]. LangChain dostarcza komponenty (modele, retrievery, tooly), a LangSmith dostarcza narzędzia do debugowania i monitorowania.

Ile kosztuje monitorowanie dryfu?

LangSmith Cloud Starter to 20 USD/miesiąc (przy rozliczeniu rocznym) i obejmuje 2 500 wykonań/miesiąc [4]. Dla większych wolumenów plany Pro i Business mają wyższe limity. Większość narzędzi oferuje free tier do testów.

Czy mogę debugować agenta bez narzędzi komercyjnych?

Tak. Możesz logować każdy krok agenta (prompt, odpowiedź, wyniki toolów) do pliku lub bazy danych i analizować logi ręcznie. Jednak narzędzia komercyjne automatyzują to i oferują wizualizacje, które ułatwiają diagnozę.

Kiedy agent jest "gotowy" do produkcji?

Gdy przejdzie testy regresyjne (zestaw przypadków testowych obejmujący typowe scenariusze, edge cases i znane błędy) i gdy masz ustawione alerty na metryki dryfu. Przed wdrożeniem powinieneś mieć baseline dla każdej metryki (wartość z ostatnich 7 dni).

Czy dryf agenta zawsze oznacza błąd?

Nie zawsze. Czasami zmiana w zachowaniu agenta wynika ze zmian w danych (np. nowe produkty w ofercie) lub celowych aktualizacji modelu. Dlatego ważne jest rozróżnienie między "dryf" (niezamierzona zmiana) a "evolucją" (zamierzona aktualizacja).

Źródła

  1. Why AI Agents Fail in Production (And How to Debug Them) — YouTube
  2. LangSmith: AI Agent & LLM Model Evaluation Platform — LangChain
  3. About LangChain: an open platform to own your intelligence — LangChain
  4. n8n Plans and Pricing — n8n.io
AN
O autorze
Andrzej Niemiec

Fanatyk nowych technologii i specjalista w zakresie sztucznej inteligencji.

Jak powstają teksty: Polityka AI · O redakcji