Dostaliśmy telefon od klienta z branży logistycznej: agent odpowiedzialny za automatyzację rezerwacji transportu zaczął systematycznie wybierać droższego przewoźnika zamiast tańszego. Różnica w cenie była widoczna — przyczyna nie. Logi pokazywały wejścia i wyjścia. Nie pokazywały, dlaczego agent w konkretnym kroku wywołał narzędzie z takimi właśnie parametrami. Odtworzenie sekwencji decyzji z surowych logów zajęło nam cztery godziny. Sam problem dało się naprawić w kwadrans — ale dopiero wtedy, gdy wiedzieliśmy, gdzie szukać.
To problem, który powtarza się w większości pierwszych produkcyjnych wdrożeń agentów. Zespoły potrafią agenta zbudować i uruchomić, ale nie potrafią go debugować. Observability — zdolność do rozumienia wewnętrznego stanu systemu na podstawie jego zewnętrznych sygnałów — to dla agentów nie luksus. To warunek utrzymania i doskonalenia systemu.
Eval a observability: dwie różne rzeczy
Zanim przejdziemy do narzędzi i podejść, warto rozróżnić dwie rzeczy, które często są mylone.
Eval (ewaluacja) odpowiada na pytanie: *czy jakość wyjść agenta jest wystarczająca?* Mierzy się ją offline lub na danych historycznych — na przykład: czy agent miał rację w 87 % przypadków? Czy generował poprawny format? Czy odpowiadał na właściwe pytania?
Observability odpowiada na pytanie: *co dokładnie wydarzyło się podczas jednego przebiegu?* Mierzy się ją w runtime — gdy agent działa lub gdy przebieg właśnie się zakończył — i uchwytuje sekwencję decyzji, wywołań narzędzi, stany pośrednie oraz błędy.
Eval to retrospektywna statystyka. Observability to chirurgiczne narzędzie do analizy konkretnego incydentu. Obydwie są potrzebne — wzajemnie się nie zastępują.
Większość zespołów zaczyna od eval i ignoruje observability. W praktyce działa to do pierwszego incydentu produkcyjnego. Po nim priorytety się odwracają.
Co trzeba rejestrować
Agent to nie jedna funkcja. To sieć kroków — każdy krok ma wejście, wyjście, prompt LLM, decyzję i ewentualny błąd. Dla każdego przebiegu agenta musisz widzieć:
- Trace: kompletne drzewo wywołań od wejściowego promptu do finalnej odpowiedzi, włącznie ze wszystkimi poddrzewami
- Spans: poszczególne kroki w ramach trace — każde wywołanie LLM, każde wywołanie narzędzia, każdy retrieval
- State diff: co zmieniło się w wewnętrznym stanie agenta między krokami (kluczowe przy
LangGraph) - Tool calls: dokładne parametry każdego wywołania narzędzia i dokładna odpowiedź, którą narzędzie zwróciło
- LLM prompts: jaki był rzeczywisty prompt wysłany do modelu (nie szablon — finalny tekst po interpolacji)
- Tokeny i latencja: liczba tokenów na span, czas na span — identyfikacja bottlenecków
- Błędy i retry: gdzie agent zawiódł, ile razy ponawiał próbę i z jakim skutkiem
Każdy z tych elementów jest niezbędny. Jeśli rejestrujesz tylko wyjście ostatniego kroku, masz log aplikacji — nie observability agenta.
Dlaczego klasyczne logowanie nie wystarcza
Gdy programiści po raz pierwszy słyszą słowo „observability", zazwyczaj odpowiadają: „przecież logujemy". Logują — ale nie tak, jak wymaga tego agent.
Klasyczny log jest sekwencyjny. Wpis po wpisie, timestamp, komunikat. Dla prostego API to wystarcza. Dla agenta, gdzie jedno wejście użytkownika uruchamia dziesiątki wywołań LLM, narzędzi i kroków retrieval — w drzewie, nie w sekwencji — płaski log jest bezużyteczny. Brak kontekstu, brak hierarchii, brak stanu w czasie.
Kolejny problem: frameworki agentowe takie jak LangGraph internalizują wiele decyzji. Który węzeł został wybrany, dlaczego aktywowała się konkretna krawędź grafu, jaki był stan w checkpoincie — tego nie widać ze standardowego logu na stdout. Potrzebna jest integracja bezpośrednio z frameworkiem, nie wrapper wokół niego.
Trzeci problem to sampling i koszt. Produkcyjny agent może wykonywać tysiące przebiegów dziennie. Logowanie *wszystkiego* w postaci ustrukturyzowanych traces jest kosztowne pod względem storage. Potrzebujesz strategii samplingu — na przykład 100 % dla błędów i długich przebiegów, 10–20 % dla losowo wybranych poprawnych przebiegów.
Trace: fundament observability agenta
Trace to główny kontener jednego przebiegu agenta. Odpowiada jednemu zadaniu — na przykład jednemu żądaniu użytkownika lub jednej zaplanowanej operacji. Wewnątrz trace są spans — każdy span to jeden krok z metadanymi.
Hierarchia wygląda następująco:
- Trace: „Zarezerwuj transport dla zamówienia #4821"
- - Span: LLM call — rozumienie żądania
- - Span: Tool call —
search_carriers(origin, destination, date) - - Span: Tool call —
get_price(carrier_id=12) - - Span: Tool call —
get_price(carrier_id=17) - - Span: LLM call — decyzja i uzasadnienie
- - Span: Tool call —
book_shipment(carrier_id, price, ...)
Każdy span ma: czas rozpoczęcia i zakończenia, wejście, wyjście, ewentualny błąd, ID rodzica. Na tej podstawie można odtworzyć cały przebieg decyzji bez domysłów.
W LangGraph drzewo to naturalnie odwzorowuje grafy — każdy węzeł grafu to span. Narzędzia takie jak LangSmith rejestrują state diff przy każdym przejściu krawędzi grafu, dając szczegółowy wgląd w ewolucję stanu.
Tracing ReAct: reason-act-observe w logach
Gdy agent korzysta z architektury ReAct — pętli Reason, Act, Observe — observability powinna rejestrować każdy z tych kroków wprost.
Krok Reason: co agent „myślał" — wyjście chain-of-thought modelu przed wywołaniem narzędzia. To najcenniejszy krok przy debugowaniu. Gdy agent wywoła złe narzędzie, odpowiedź jest prawie zawsze widoczna w kroku Reason — model „zdecydował" błędnie z powodu, który jest zapisany w tekście.
Krok Act: dokładne wywołanie narzędzia z parametrami. Nie szablon — rzeczywiste wartości po interpolacji. Błędy w tool callingu — źle uformowane parametry, nieprawidłowy typ — widać tutaj.
Krok Observe: co narzędzie zwróciło. Ważne: surowy wynik narzędzia zanim model go przetworzy. Gdy narzędzie zwróci nieoczekiwany format lub komunikat błędu, tu to zobaczysz.
Bez jawnego logowania tych trzech kroków per iteracja masz tylko finalne wyjście. A finalne wyjście nie powie ci, dlaczego agent po trzeciej iteracji zmienił decyzję.
Metryki, które warto śledzić
Oprócz trace na przebieg potrzebujesz zagregowanych metryk do monitoringu:
- Latencja p50/p95/p99 — nie tylko całkowita latencja przebiegu, ale latencja per węzeł. Gdzie agent spędza czas?
- Zużycie tokenów na przebieg — trend, wartości odstające (przebiegi z 10× większą liczbą tokenów = wzorzec błędu)
- Tool error rate — odsetek przebiegów, w których co najmniej jedno wywołanie narzędzia zakończyło się błędem
- Retry rate — jaki procent przebiegów wymagał ponowienia. Retry rate na poziomie 12 % i więcej zazwyczaj sygnalizuje problem z walidacją schematu lub z promptem
- Abandonment rate — przebiegi, w których agent nie osiągnął celu i zwrócił odpowiedź fallback
- Human escalation rate — w systemach z HITL (human-in-the-loop): odsetek przebiegów eskalowanych do człowieka
Każda z tych metryk ma charakter objawowy. Wysoki retry rate wskazuje na niestabilne wywołania narzędzi. Wysoka latencja p99 przy niskiej p50 wskazuje na scenariusze odstające — prawdopodobnie długie konteksty lub pętle retry. Wysoki abandonment rate wskazuje na przypadki brzegowe, których agent nie potrafi obsłużyć.
Narzędzia: LangSmith, Langfuse, Arize Phoenix
Na dziś w produkcji istnieją trzy główne platformy:
`LangSmith` — najgłębsza integracja z LangGraph i LangChain. Automatycznie rejestruje trace, state diff, tokeny, latencję. Oferuje playground do replay przebiegów — możesz wziąć konkretny trace i uruchomić go ponownie ze zmodyfikowanym promptem. Hostowanie w chmurze, pricing według wolumenu traces. Jeśli Twój stack to LangGraph, LangSmith to naturalna decyzja.
`Langfuse` — niezależny od frameworku, możliwość self-hostingu (Postgres + ClickHouse). SDK dla Pythona, TypeScript, REST. Działa nawet jeśli nie piszesz przez LangGraph — wywołujesz SDK bezpośrednio przy każdym LLM call i tool call. Odpowiednie dla zespołów, które chcą pełnej kontroli nad danymi (branże regulowane, wymagania on-prem). Self-hosting zwiększa nakład ops — klaster ClickHouse trzeba utrzymywać.
`Arize Phoenix` — oparty na OpenTelemetry. Rejestruje traces przez standardowy protokół OTel, co oznacza integrację z istniejącym stackiem monitoringowym (Prometheus, Grafana, Jaeger). Dodatkowo: ponad 50 metryk eval bezpośrednio w platformie — faithfulness, wykrywanie halucynacji, relevance. Dla zespołów, gdzie observability agentów ma być częścią szerszego rozwiązania APM.
Wybór: jeśli jesteś na LangGraph w chmurze — LangSmith. Jeśli potrzebujesz self-hostingu lub masz heterogeniczny stack — Langfuse. Jeśli chcesz observability i eval w jednym i masz infrastrukturę OTel — Arize Phoenix.
Dla mniejszych projektów na wczesnym etapie: Langfuse self-hosted na prostym Docker Compose wystarczy i oszczędza koszty.
Replay i debugowanie konkretnego incydentu
Observability ma największą wartość przy konkretnym incydencie. Procedura, która sprawdza się w praktyce:
- 1.Zidentyfikuj trace po trace ID lub po filtrze (na przykład: wszystkie przebiegi z tool error rate > 0 w ostatnich 24 godzinach)
- 2.Otwórz state diff — sprawdź, jak zmieniał się stan agenta krok po kroku. Gdzie nastąpiła zmiana, której się nie spodziewałeś?
- 3.Przeczytaj reason text w każdym LLM call — szukaj logiki odpowiadającej na pytanie „dlaczego agent podjął tę decyzję"
- 4.Sprawdź wyjścia narzędzi — czy problem mógł leżeć w tym, co narzędzie zwróciło, a nie w tym, co agent zrobił z wynikiem?
- 5.Uruchom replay ze zmodyfikowanym promptem lub parametrami — weryfikacja hipotezy bez potrzeby prawdziwego środowiska
Ta procedura skraca MTTR (mean time to resolution) z godzin do minut. Z doświadczenia: większość błędów agentów nie leży w rozumowaniu LLM — leży w tool callingu, nieoczekiwanym formacie wyjścia narzędzia lub w zarządzaniu stanem. Observability pozwala dokonać tego rozróżnienia w ciągu sekund.
Alerty i aktywne monitorowanie
Reaktywne debugowanie to tylko jedna warstwa. System produkcyjny potrzebuje też aktywnych alertów.
Podstawowe reguły alertowania:
- Tool error rate > 5 % w oknie godzinnym → alert, prawdopodobna zmiana w systemie downstream lub w schemacie narzędzia
- Średnia latencja przebiegu > 2× baseline → alert, scenariusz odstający lub spowolnienie upstream
- Abandonment rate > 10 % w ciągu dnia → alert, nowe przypadki brzegowe w produkcji
- Koszt tokenów dziennie > X EUR — alert kosztowy, niezbędny przy agentach, gdzie pętle mogą bez ograniczeń generować wywołania. Agent bez alertu kosztowego może przez noc wygenerować tysiące wywołań i rachunek rzędu tysięcy euro — ryzyko, które w praktyce obserwujemy
Alerty powinny prowadzić do trace, a nie tylko do liczby. Gdy dostaję alert „tool error rate 8 %", chcę bezpośredni link do trace, w którym to wystąpiło — nie liczbę bez kontekstu.
Observability a koszty agenta
Sama observability generuje koszty — storage dla traces, compute dla analytics. W systemach produkcyjnych o dużym wolumenie ważne jest ustawienie strategii samplingu.
Rekomendowane podejście:
- 100 % samplingu dla przebiegów z błędami (tool error, abandonment, timeout)
- 100 % samplingu dla przebiegów z nieoczekiwaną latencją (wartości odstające p99)
- 10–20 % samplingu dla poprawnych przebiegów w normie
- 100 % samplingu podczas wdrożenia nowej wersji agenta (pierwsze 24–48 godzin)
To obniża koszty storage 5–10× przy zachowaniu pełnej widoczności dla diagnostyki. Platformy takie jak Langfuse obsługują konfigurację sampling rate natywnie.
Związek z kosztami agenta w produkcji: observability pozwala zidentyfikować nieefektywne przebiegi — na przykład takie, w których agent wielokrotnie wywołuje to samo narzędzie z powodu niejasnej odpowiedzi. To typowy problem niezawodności tool callingu, który observability ujawnia, zanim zdąży istotnie zwiększyć koszty.
Bezpieczeństwo i wymiar prawny tracingu
Traces zawierają wrażliwe dane — prompty, wyjścia narzędzi, wewnętrzny stan agenta. W branżach regulowanych (finanse, ochrona zdrowia, prawo) wymaga to:
- Szyfrowania traces at rest i in transit
- Kontroli dostępu — kto może odczytywać rekordy trace?
- Polityki retencji — jak długo przechowujesz traces?
- PII scrubbing — dane osobowe w promptach lub wyjściach narzędzi nie mogą być przechowywane w plain text
Self-hosted Langfuse daje pełną kontrolę nad tymi aspektami. Platformy chmurowe należy oceniać pod kątem wymagań GDPR i rezydencji danych — szczególnie gdy traces zawierają dane firmowe lub klientów.
W przypadku wdrożeń LLM on-prem self-hosted observability to prawie zawsze wymaganie, a nie kwestia wyboru.
Najczęstsze pytania
Czy muszę mieć observability przed pierwszym wdrożeniem agenta?
Niekoniecznie przed pierwszym wdrożeniem testowym — ale tak, przed wdrożeniem produkcyjnym z prawdziwymi użytkownikami lub prawdziwymi danymi. Bez observability nie masz sposobu, żeby ustalić, gdzie i dlaczego agent zawodzi. Pierwszy incydent produkcyjny wymagający debugowania bez tracingu zazwyczaj przekonuje zespół szybciej niż jakikolwiek argument.
Jaka jest różnica między tracingiem a standardowym logowaniem?
Klasyczny log to płaska sekwencja wpisów. Tracing rejestruje hierarchiczne drzewo — trace zawiera spans, spans zawierają child spans. Dla agenta, gdzie jedno wejście uruchamia dziesiątki wywołań w drzewie, hierarchiczna struktura jest niezbędna. Tracing rejestruje też state diff między krokami, czego płaski log nie umożliwia.
Czy observability działa też dla agentów spoza LangGraph?
Tak. Langfuse i Arize Phoenix są niezależne od frameworku — wystarczy wywołać SDK przy każdym LLM call i tool call. Jeśli piszesz własnego agenta bez frameworku, możesz ręcznie dodać OpenTelemetry spans. LangSmith ma najgłębszą integrację z LangGraph, ale integracje istnieją też dla innych frameworków.
Ile to kosztuje?
Langfuse self-hosted jest bezpłatny (tylko koszty operacyjne infrastruktury — prosty Docker Compose z Postgres + ClickHouse). LangSmith i Arize Phoenix mają poziom free dla niskich wolumenów; płatne plany zaczynają się od kilkudziesięciu euro miesięcznie. Głównym kosztem nie jest platforma — to storage dla traces, zwłaszcza przy dużym wolumenie przebiegów.
Czy powinienem logować pełne prompty LLM?
Tak — z jednym zastrzeżeniem: jeśli prompty zawierają dane osobowe lub firmowe, przed zapisem należy zadbać o PII scrubbing. Logowanie samych metadanych (liczba tokenów, latencja, nazwa narzędzia) bez treści promptu jest tańsze, ale znacząco ogranicza debugowalność. Rekomendujemy logowanie pełnych promptów z polityką retencji i kontrolą dostępu.
Podsumowanie
*Observability AI agentów to nie kwestia narzędzi — to kwestia kultury odpowiedzialności za to, co system robi na produkcji. Gdy agent zawodzi, na pytanie „dlaczego" trzeba mieć odpowiedź w minutach, nie godzinach. W MP Industrial Solutions pomagamy zespołom wbudować observability w architekturę agentów — nie jako warstwę doklejoną na końcu. Jeśli planujesz wdrożenie agenta lub rozwiązujesz incydent w istniejącym systemie, chętnie przyjrzymy się Twojemu konkretnemu przypadkowi.*