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.
Spis treści
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ć
| Metryka | Narzędzie | Target | Co oznacza |
|---|---|---|---|
| Retrieval precision@3 | LangSmith | >0,8 | Czy retriever zwraca relewantne dokumenty? |
| Tool output validity | Własne skrypty (Pydantic) | >95% | Ile wywołań toolów zwraca poprawne dane? |
| Memory drift | Własne logi | <5% wzrostu/interakcję | Czy chat_history rośnie w przewidywalnym tempie? |
| Perplexity drift | Dedykowane narzędzia | <10% wzrostu | Czy model jest stabilny? |
| Response time | LangSmith | <2s | Czy 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
Fanatyk nowych technologii i specjalista w zakresie sztucznej inteligencji.
Jak powstają teksty: Polityka AI · O redakcji