Observability dla agentów: logi zdarzeń, ścieżki rozumowania, trace narzędzi i SLO odpowiedzi
Praktyczny przewodnik observability dla agentów LLM: jakie logi i trace’y zbierać, jak korelować zdarzenia, chronić dane, mierzyć metryki oraz ustalać SLO i dashboardy.
1. Wprowadzenie: czym jest observability w agentach LLM i dlaczego różni się od klasycznych systemów
Observability (obserwowalność) to zdolność systemu do tego, by na podstawie danych generowanych podczas działania dało się zrozumieć, co się wydarzyło, dlaczego się wydarzyło i jaki będzie wpływ na użytkownika oraz koszty. W kontekście agentów opartych o LLM oznacza to nie tylko podgląd technicznych symptomów (czas odpowiedzi, błędy), ale także wgląd w przebieg realizacji zadania: jak agent interpretuje intencję, jakie kroki podejmuje, kiedy sięga po narzędzia i w którym momencie rozmowy pojawia się ryzyko błędnej odpowiedzi.
W klasycznych systemach obserwowalność koncentruje się zwykle na deterministycznych komponentach: żądanie trafia do usługi, wykonywana jest znana ścieżka kodu, a wynik zależy od danych wejściowych i stanu. W agentach LLM pojawiają się cechy, które sprawiają, że „standardowe” podejście do logów, metryk i trace’ów przestaje wystarczać.
- Niedeterministyczność i zmienność: to samo pytanie może prowadzić do różnych odpowiedzi, a drobne zmiany w promptach, temperaturze czy kontekście rozmowy potrafią zmienić przebieg działania. Observability musi uwzględniać, że „powtarzalność” incydentów jest trudniejsza.
- Wieloetapowość działania: agent nie jest pojedynczym wywołaniem modelu, tylko sekwencją kroków: interpretacja, plan, decyzje, użycie narzędzi, weryfikacja i finalna odpowiedź. Z perspektywy obserwowalności ważne jest uchwycenie przebiegu tej sekwencji oraz punktów, w których agent zmienia kierunek.
- Interakcje z narzędziami i światem zewnętrznym: agenci często wykonują wyszukiwania, zapytania do baz, operacje w systemach firm trzecich, a nawet działania modyfikujące stan. W efekcie źródłem problemów bywa nie tylko model, ale też narzędzie, dane, uprawnienia lub ograniczenia zewnętrznych API.
- Nowe klasy ryzyk: poza błędami infrastruktury pojawiają się zjawiska takie jak halucynacje, nadinterpretacja polecenia, podatność na prompt injection czy niezamierzone ujawnienie wrażliwych danych. Observability ma pomóc wykrywać symptomy tych ryzyk i rozumieć ich kontekst, zanim przełożą się na incydent.
- Koszt jako sygnał operacyjny: w systemach LLM koszt (np. wynikający z długości kontekstu, liczby wywołań i strategii działania) jest równie istotny jak wydajność. Obserwowalność powinna umożliwiać ocenę, czy agent rozwiązuje zadanie „skutecznie” w granicach akceptowalnych wydatków.
Praktycznie obserwowalność agentów odpowiada na pytania, które w tradycyjnych usługach pojawiają się rzadziej lub są prostsze: dlaczego agent wybrał dane narzędzie, czemu utknął w pętli, w którym momencie rozmowy zniknęły kluczowe informacje z kontekstu, albo dlaczego odpowiedź jest poprawna formalnie, ale nie spełnia intencji użytkownika. Jednocześnie zebrane sygnały muszą być na tyle precyzyjne, by umożliwiać diagnostykę, a na tyle bezpieczne, by nie utrwalać danych wrażliwych użytkowników.
W efekcie observability dla agentów LLM to połączenie podejścia znanego z systemów rozproszonych (widoczność przepływu żądań i zależności) z potrzebą śledzenia przebiegu „pracy poznawczej” agenta oraz skutków jego działań. To fundament do stabilnego działania w produkcji: szybszego debugowania, ograniczania ryzyka jakościowego, kontroli kosztów i utrzymywania przewidywalnego doświadczenia użytkownika.
2. Jakie logi zbierać: zdarzenia rozmowy, decyzje agenta, wywołania narzędzi, błędy i retry
W agentach LLM logowanie nie służy wyłącznie do diagnostyki awarii. Jest też źródłem wiedzy o tym, dlaczego agent zrobił to, co zrobił, z jakim skutkiem i jakim kosztem (czas, tokeny, użyte narzędzia). Kluczowe jest uchwycenie przebiegu pracy agenta jako sekwencji zdarzeń: od wejścia użytkownika, przez planowanie i działania, po finalną odpowiedź. Z doświadczenia szkoleniowego Cognity wiemy, że ten temat budzi duże zainteresowanie – również wśród osób zaawansowanych. Poniżej zestaw minimalnych kategorii logów, które zwykle dają największą wartość operacyjną.
- Zdarzenia rozmowy (conversation events)
Rejestrują przepływ komunikatów w sesji: wiadomości użytkownika, odpowiedzi modelu i ewentualne komunikaty systemowe. Celem jest odtworzenie kontekstu, który doprowadził do decyzji agenta, oraz szybka analiza jakości odpowiedzi. W praktyce warto utrzymywać rozróżnienie na: treść wejściową, treść wyjściową, a także metadane (np. język, kanał, typ klienta, wersja promptu/konfiguracji). Zwykle loguje się też informację o tym, czy odpowiedź była kompletna, przerwana, skrócona lub zmodyfikowana przez warstwę polityk (np. filtrowanie).
- Decyzje agenta (agent decisions)
To logi mówiące o tym, jakie kroki agent zamierza wykonać i z jakich powodów, ale bez wchodzenia w wrażliwe szczegóły. Obejmują m.in. wybór strategii (odpowiedź bez narzędzi vs. użycie narzędzi), wybór narzędzia, określenie celu kroku, decyzję o kontynuacji lub zakończeniu oraz oceny pewności/ryzyka. W tej kategorii szczególnie ważne jest, aby logować wynik decyzji i jej kontekst (np. klasyfikacja intencji, wymagane dane, ograniczenia), zamiast pełnej „ścieżki rozumowania” w postaci surowych, niekontrolowanych notatek modelu.
- Wywołania narzędzi (tool calls)
Agenci często korzystają z wyszukiwania, baz danych, systemów transakcyjnych, kalkulatorów, funkcji biznesowych czy innych modeli. Logi narzędzi powinny rejestrować: jakie narzędzie wywołano, z jakimi parametrami (w zakresie bezpiecznym do zapisu), kiedy wywołanie się rozpoczęło i zakończyło, jaki był rezultat (sukces/niepowodzenie) oraz podstawowe atrybuty odpowiedzi (np. rozmiar, status, liczba rekordów). Dzięki temu można zrozumieć, czy problem wynika z modelu, czy z integracji oraz gdzie „ucieka” czas i koszt w całym przebiegu działania agenta.
- Błędy i wyjątki (errors)
W agentach błędy pojawiają się na wielu poziomach: od warstwy modelu (limity, błędy walidacji, odmowy), przez orkiestrację (błędna konfiguracja, przekroczenie budżetu kroków), po narzędzia (timeouty, błędy autoryzacji, niezgodny schemat odpowiedzi). W logach błędów kluczowe są: typ błędu, komponent, który go zgłosił, wpływ na użytkownika (czy agent zdołał dostarczyć odpowiedź), oraz minimalne dane diagnostyczne potrzebne do naprawy. Dobrą praktyką jest rozróżnienie błędów oczekiwanych (np. brak danych) od awaryjnych (np. wyjątek runtime), bo mają inne ścieżki obsługi i inne priorytety.
- Retry, fallback i degradacja działania
Retry w agentach to nie tylko powtórzenie tego samego żądania. Często oznacza zmianę parametrów (np. krótszy kontekst), wybór alternatywnego narzędzia, przejście na tryb „bez narzędzi” lub użycie odpowiedzi przybliżonej. Warto logować: powód retry (timeout, limit, błąd walidacji), numer próby, zastosowaną strategię naprawczą oraz rezultat. To pozwala odróżnić chwilowe problemy infrastrukturalne od systematycznych błędów w promptach, schematach danych czy integracjach.
Dobry zestaw logów dla agentów łączy więc przebieg konwersacji, decyzje orkiestracji, interakcje z narzędziami oraz awarie i mechanizmy naprawcze. Taki podział pomaga szybko ustalić, czy problem dotyczy jakości odpowiedzi, logiki sterowania, integracji narzędzi czy stabilności wykonania.
3. Projektowanie trace’ów i korelacji: identyfikatory (trace/span), kontekst, session/user, replay i debug
W agentach LLM pojedyncza „odpowiedź” jest zwykle wynikiem łańcucha kroków: interpretacji intencji, planowania, kilku wywołań narzędzi, ewentualnych retry oraz finalnej syntezy. Dlatego klasyczne podejście „loguj request i response” nie wystarcza. Potrzebujesz trace’u, który spina wszystkie zdarzenia w jedną historię wykonania i pozwala ją potem odtworzyć w debugowaniu.
Trace i span: minimalny model do składania historii działania agenta
Trace opisuje jedno przejście przez system (np. obsługę jednej wiadomości użytkownika albo jednego zadania agenta). Span to fragment trace’u odpowiadający konkretnemu etapowi, np. „wybór narzędzia”, „call tool: search”, „LLM final answer”. Kluczowa jest tu hierarchia: span może zawierać inne spany, co odzwierciedla zagnieżdżone decyzje i wywołania.
- trace_id – wspólny identyfikator dla całego przebiegu (korelacja end-to-end).
- span_id – identyfikator pojedynczego kroku.
- parent_span_id – relacja rodzic-dziecko dla rekonstrukcji drzewa działań.
- timestamp + duration – pozwalają zbudować oś czasu i zidentyfikować wąskie gardła.
Co warto traktować jako osobne spany w agentach
W agentach najczęściej opłaca się tworzyć spany dla etapów, które mają inne źródła opóźnień i inne tryby awarii. Dzięki temu łatwiej odróżnić problemy modelu od problemów integracji.
- Wejście użytkownika (przetworzenie wiadomości, walidacje, normalizacja).
- Wywołanie LLM (osobne spany dla: klasyfikacji intencji, planowania, refleksji, generacji odpowiedzi – jeśli występują).
- Wybór/dispatch narzędzia (decyzja o użyciu narzędzia, wybór konkretnego toola).
- Wywołanie narzędzia (HTTP/DB/queue, wraz z kodem odpowiedzi i retry jako osobnymi spanami).
- Agregacja wyników (łączenie danych, ranking, filtracja, kompresja kontekstu).
- Odpowiedź końcowa (renderowanie, formatowanie, post-processing).
Korelacja przez kontekst: co przenosić między krokami
Same identyfikatory trace/span to za mało, jeśli chcesz robić analizę przekrojową. W praktyce potrzebujesz zestawu stabilnych atrybutów kontekstu (tagów), które umożliwiają filtrowanie i grupowanie.
- session_id – łączy wiele trace’ów w ramach jednej sesji rozmowy (kontekst dialogu).
- user_id / tenant_id – korelacja z użytkownikiem lub organizacją (z zachowaniem zasad prywatności).
- conversation_turn – numer tury w rozmowie; pomaga wykrywać degradację jakości w dłuższych sesjach.
- agent_run_id – identyfikator konkretnego uruchomienia agenta, jeśli jedna tura inicjuje kilka równoległych ścieżek.
- model, tool_name, route (ścieżka biznesowa), feature_flag – szybkie segmentowanie po konfiguracji.
Dobrym kompromisem jest zasada: kontekst ma być wystarczający do diagnozy i analizy, ale możliwie stały i niezbyt „gadatliwy”. Zbyt duża liczba tagów utrudnia utrzymanie i zwiększa koszty.
Session vs trace: typowy błąd w agentach
Sesja rozmowy jest długotrwała, natomiast trace powinien być krótką jednostką wykonania. W agentach łatwo wpaść w pułapkę „jeden trace na całą rozmowę”, co prowadzi do gigantycznych trace’ów i utrudnia analizę. Częściej sprawdza się podejście:
- session_id – stałe w obrębie rozmowy,
- trace_id – nowe dla każdej tury użytkownika lub każdego zadania,
- linki/korelacje – gdy jedna tura rozgałęzia się na kilka równoległych działań.
Replay i debug: co musi znaleźć się w śladach, by dało się odtworzyć przebieg
„Replay” oznacza możliwość odtworzenia (w całości lub częściowo) przebiegu działania agenta w środowisku testowym. W agentach to szczególnie ważne, bo zachowanie zależy od: promptu, kontekstu, wyników narzędzi i konfiguracji modelu. Żeby replay był realny, trace powinien wskazywać:
- wejścia i wyjścia kroków (na poziomie metadanych): np. rozmiary, skróty treści, identyfikatory artefaktów,
- wersje: prompt template, konfiguracji agenta, narzędzi oraz modelu,
- źródła danych: identyfikatory zapytań, endpointy, kody odpowiedzi,
- decyzje sterujące: np. „wybrano narzędzie X z powodu Y” jako krótki atrybut decyzyjny (bez wchodzenia w pełne szczegóły rozumowania).
W praktyce dane do replay często przechowuje się jako artefakty powiązane z trace’em (np. snapshot kontekstu), a w samych spanach trzyma się jedynie odnośniki i kontrolne sumy. Ułatwia to zarządzanie rozmiarem i dostępem.
Krótka mapa: identyfikatory i ich rola
| Element | Zakres | Po co | Typowe pytanie diagnostyczne |
|---|---|---|---|
| session_id | Wiele tur rozmowy | Spójność dialogu, analiza zachowania w czasie | Czy problemy pojawiają się po kilku turach? |
| trace_id | Jedna tura / jedno zadanie | Historia wykonania end-to-end | Co dokładnie stało się w tej jednej odpowiedzi? |
| span_id | Pojedynczy krok | Lokalizacja opóźnień i błędów | Który etap spowolnił lub zawiódł? |
| parent_span_id | Relacja w drzewie | Rekonstrukcja przyczynowości | Jaki krok wywołał ten tool call? |
| user_id/tenant_id | Przekrój systemu | Segmentacja i wsparcie operacyjne | Czy dotyczy to konkretnej grupy użytkowników? |
Minimalny szkic instrumentacji (przykład)
Poniższy przykład pokazuje jedynie ideę: jeden trace dla tury i spany dla LLM oraz narzędzia, z podstawowymi polami korelacji.
// pseudokod
trace_id = newTraceId()
span_root = startSpan("agent.turn", { trace_id, session_id, user_id, turn: 12 })
span_plan = startChildSpan(span_root, "llm.plan", { model: "...", prompt_version: "v3" })
plan = callLLM(...)
endSpan(span_plan, { outcome: "ok" })
span_tool = startChildSpan(span_root, "tool.call", { tool_name: "search" })
res = callTool(...)
endSpan(span_tool, { http_status: 200 })
span_answer = startChildSpan(span_root, "llm.answer", { model: "..." })
answer = callLLM(...)
endSpan(span_answer, { outcome: "ok" })
endSpan(span_root, { final: "ok" })
Najważniejsze jest konsekwentne używanie tych samych identyfikatorów i atrybutów w całym łańcuchu, tak aby dało się płynnie przechodzić od widoku „co widział użytkownik” do „który span i dlaczego zawiódł”.
4. Bezpieczeństwo i prywatność logów
Logi w systemach agentowych są szczególnie wrażliwe, bo często zawierają pełny kontekst rozmowy, parametry wywołań narzędzi (np. zapytania do baz, fragmenty dokumentów) oraz artefakty sterujące (prompt, instrukcje systemowe, konfiguracje). To zwiększa ryzyko ujawnienia danych osobowych, tajemnic biznesowych i sekretów technicznych. Dlatego obserwowalność musi być projektowana tak, aby dostarczać informacji diagnostycznej bez utrwalania danych, których nie wolno lub nie trzeba przechowywać.
PII i sekrety: co najczęściej „przecieka” do logów
W praktyce problemem nie są wyłącznie jawne dane w wiadomościach użytkownika, ale też dane pochodzące z narzędzi i integracji, które agent wywołuje w tle.
- PII: imię i nazwisko, e-mail, telefon, adres, identyfikatory klientów, dane lokalizacyjne, dane zdrowotne/finansowe (w zależności od domeny), a także identyfikatory sesji powiązane z konkretną osobą.
- Sekrety: tokeny API, klucze, hasła, nagłówki autoryzacyjne, ciasteczka sesyjne, podpisy webhooków, poświadczenia do baz, a czasem całe treści promptów zawierające instrukcje lub dane konfiguracyjne.
- Dane wrażliwe biznesowo: fragmenty umów, cenniki, nieopublikowane roadmapy, dane klientów z CRM, wyniki analiz, dokumenty wewnętrzne pobrane przez narzędzia.
Redakcja i minimalizacja: loguj „to, co potrzebne”, nie „to, co się da”
Najskuteczniejszym podejściem jest minimalizacja: zapisywanie możliwie małej ilości treści, a zamiast tego metadanych (np. długości, typów, statusów). Tam, gdzie potrzebujesz wglądu w zawartość, stosuj redakcję (maskowanie) i selektywne próbkowanie (np. tylko dla wybranych środowisk lub incydentów). Zespół trenerski Cognity zauważa, że właśnie ten aspekt sprawia uczestnikom najwięcej trudności — zwłaszcza gdy trzeba pogodzić potrzeby debugowania z zasadą minimalizacji danych.
| Ryzyko | Co logować zamiast pełnej treści | Typowa redakcja |
|---|---|---|
| Tekst rozmowy zawiera PII | Identyfikator wiadomości, długość, język, klasyfikacja tematu | Maskowanie e-mail/telefonu, usuwanie adresów, pseudonimizacja identyfikatorów |
| Wywołania narzędzi zawierają dane klientów | Nazwa narzędzia, status, czasy, kody błędów, rozmiary payloadów | Redakcja parametrów i odpowiedzi, logowanie tylko schematu/kluczy |
| Sekrety w nagłówkach i konfiguracji | Informacja o typie uwierzytelnienia, identyfikator klucza (nie wartość) | Stałe maskowanie Authorization, tokenów, kluczy, cookie |
| Prompt/system instrukcje ujawniają IP | Wersja promptu, checksum/skrót, identyfikator konfiguracji | Przechowywanie szablonów w repozytorium, a w logach tylko referencje |
Praktyczna zasada: logi „debug” z pełną treścią traktuj jak dane produkcyjne o najwyższej wrażliwości. Jeśli musisz je zbierać, rób to krótkotrwale, z ograniczonym dostępem, z kontrolą eksportu i z jasnym celem (np. analiza incydentu).
Mechanizmy ochrony: gdzie wdrożyć redakcję
- Po stronie klienta (przed wysłaniem): najlepsze dla oczywistych sekretów (np. token w UI), ale rzadko wystarczające.
- W warstwie ingestu/logowania: centralne miejsce na reguły maskowania i walidację pól; ułatwia spójność między usługami.
- Na poziomie schematu zdarzeń: jawne rozdzielenie pól „bezpiecznych” (metryki, statusy) od pól „treściowych” (które mogą być wyłączone lub szyfrowane).
- W magazynie: szyfrowanie w spoczynku, ograniczenia zapytań, mechanizmy DLP, ale nie zastępują minimalizacji.
// Przykład: bardzo uproszczona redakcja pól w payloadzie logu
function redact(logEvent) {
const cloned = structuredClone(logEvent);
const secretKeys = ["authorization", "api_key", "token", "password", "cookie"];
function maskValue(v) {
if (typeof v !== "string") return v;
// maskuj typowe wzorce
return v
.replace(/\b[\w.%+-]+@[\w.-]+\.[A-Za-z]{2,}\b/g, "[REDACTED_EMAIL]")
.replace(/\b\+?\d[\d\s()-]{7,}\b/g, "[REDACTED_PHONE]");
}
function walk(obj) {
if (!obj || typeof obj !== "object") return;
for (const k of Object.keys(obj)) {
if (secretKeys.includes(k.toLowerCase())) {
obj[k] = "[REDACTED_SECRET]";
} else if (typeof obj[k] === "string") {
obj[k] = maskValue(obj[k]);
} else {
walk(obj[k]);
}
}
}
walk(cloned);
return cloned;
}
Polityki retencji: jak długo przechowywać logi i dlaczego
Retencja powinna wynikać z celu (debug, audyt, analityka kosztów) oraz z wymogów prawnych. W agentach szczególnie ważne jest rozdzielenie retencji dla danych treściowych i metadanych.
- Krótka retencja dla treści: pełne wypowiedzi, payloady narzędzi, odpowiedzi z baz dokumentów – najczęściej tylko tyle, ile realnie potrzeba do diagnostyki.
- Dłuższa retencja dla metryk i metadanych: statusy, czasy, liczniki, kody błędów – zwykle wystarczają do trendów i SLO bez ryzyka ekspozycji treści.
- Kasowanie selektywne: możliwość usunięcia danych na żądanie (np. użytkownika) w sposób obejmujący logi, kopie i indeksy.
- Środowiska: inne zasady dla produkcji, stagingu i środowisk testowych (testy często są mniej pilnowane, a potrafią zawierać realne dane).
Kontrola dostępu: najmniejsze uprawnienia i separacja ról
Dostęp do logów agentowych powinien być traktowany jak dostęp do danych produkcyjnych. Najczęstszy błąd to szeroki dostęp „dla wygody debugowania”.
- RBAC/ABAC: role (np. on-call, bezpieczeństwo, analityka) i atrybuty (np. środowisko, typ danych) ograniczające widok.
- Segmentacja: oddzielne indeksy/projekty dla logów treściowych vs metadanych; ograniczanie zapytań przekrojowych.
- Audit trail: rejestrowanie kto i kiedy przeglądał/eksportował logi, zwłaszcza te zawierające treść.
- Bezpieczne udostępnianie: przy eskalacji incydentów preferuj wycinki zredagowane, a nie pełne eksporty.
Zgodność i wymagania prawne: projektuj z myślą o rozliczalności
Zgodność to nie tylko „czy wolno nam to logować”, ale też „czy potrafimy udowodnić, że robimy to właściwie”. W kontekście agentów kluczowe są procesy: klasyfikacja danych, podstawy przetwarzania, kontrola dostępu i możliwość usuwania.
- Klasyfikacja danych: oznaczanie zdarzeń/pól według poziomu wrażliwości (np. publiczne/wewnętrzne/poufne/ściśle poufne) i automatyczne egzekwowanie zasad.
- Rejestrowanie podstawy i celu: dlaczego dany typ logu jest zbierany (diagnostyka, bezpieczeństwo, rozliczenia) i kto jest właścicielem danych.
- Transfery i podmioty przetwarzające: jeśli logi trafiają do zewnętrznych usług, wymagaj umów i kontroli lokalizacji danych oraz szyfrowania.
- Procedury DSAR/RTBF: zdolność do wyszukania i usunięcia danych powiązanych z osobą (w tym w logach) oraz do ograniczenia przetwarzania.
Wniosek praktyczny: dobra observability dla agentów zaczyna się od decyzji, które dane są w ogóle dopuszczalne w logach. Dopiero potem dobiera się narzędzia, schematy i reguły redakcji — tak, aby zespół mógł diagnozować problemy bez budowania „drugiej bazy danych osobowych” w systemie logowania.
5. Metryki i monitoring: latency, tokeny/koszty, narzędzia, cache hit rate, błędy, jakość odpowiedzi
W agentach LLM monitoring nie kończy się na „czy API działa”. Trzeba mierzyć czas, koszt i skuteczność całego przebiegu: od zrozumienia polecenia, przez planowanie i wywołania narzędzi, po finalną odpowiedź. Kluczowa różnica względem klasycznych usług webowych polega na tym, że wynik jest probabilistyczny, często wieloetapowy, a koszt zależy od długości kontekstu i liczby kroków (narzędzi/iteracji).
5.1. Latency: czas odpowiedzi jako suma etapów
Użytkownik odczuwa opóźnienie jako „czas do użytecznej odpowiedzi”, ale w agentach warto rozbić je na komponenty. Dzięki temu wiadomo, czy winne jest LLM, narzędzie, czy np. rozrost kontekstu.
- TTFT (time to first token) – czas do rozpoczęcia strumieniowania odpowiedzi; dobry wskaźnik percepcji szybkości.
- TTR (time to response/end) – czas do pełnej odpowiedzi (lub do spełnienia warunku „done”).
- Tool latency – czas wywołań narzędzi (DB/HTTP/search), najlepiej per narzędzie i per operacja.
- Orchestration overhead – czas spędzony w logice agenta (routing, wybór narzędzia, walidacje, post-processing).
- Queueing / rate limit – opóźnienia wynikające z kolejek i limitów dostawcy.
Praktycznie: raportuj percentyle (p50/p95/p99), bo rozkłady opóźnień są zwykle ciężkoogonowe. W agentach istotna jest też metryka „latency per step” (na iterację), bo wzrost liczby kroków często tłumaczy regresje.
5.2. Tokeny i koszty: obserwowalność ekonomii rozmowy
W LLM koszt jest funkcją tokenów i modelu, a tokeny rosną wraz z historią, dokumentami i wynikami narzędzi. Metryki kosztowe powinny być widoczne tak samo jak metryki wydajności.
- Input tokens / output tokens – per żądanie i agregowane per sesja.
- Tokens per step – pozwala wykryć „puchnięcie” promptu w kolejnych iteracjach.
- Cost per request / per conversation – przeliczone wg cennika; przydatne do budżetów.
- Context utilization – udział tokenów „kontekstu” vs „treści użytkowej” (np. historia, instrukcje, narzędzia).
- Truncation rate – odsetek przypadków, gdy kontekst trzeba było obciąć (ryzyko spadku jakości).
Różnica względem klasycznych systemów: koszt zmienia się w czasie w zależności od jakości danych wejściowych, polityk pamięci i częstotliwości użycia narzędzi. Dlatego koszty warto trendować per use case i per wersja konfiguracji agenta.
5.3. Narzędzia (tooling): skuteczność i „tarcie” integracji
Agent jest często tak dobry, jak jego narzędzia. Monitoring powinien pokazać zarówno niezawodność narzędzi, jak i to, czy agent używa ich sensownie.
- Tool call count – liczba wywołań na żądanie/sesję; nagły wzrost może oznaczać pętle lub złą strategię.
- Tool success rate – odsetek zakończonych powodzeniem (np. HTTP 2xx, poprawna walidacja wyniku).
- Tool error taxonomy – kategorie błędów: timeout, 4xx/5xx, walidacja schematu, brak uprawnień.
- Retries – liczba i powód ponowień; odróżniaj retry „techniczne” od „semantycznych” (agent próbuje inaczej).
- Tool result size – rozmiar odpowiedzi narzędzia (często przekłada się na tokeny i latency).
Ważne: w agentach poprawność narzędzia nie gwarantuje poprawności wyniku końcowego. Dlatego metryki narzędzi łącz z metrykami jakości odpowiedzi (poniżej), aby wykrywać przypadki, gdzie narzędzie działa, ale agent źle interpretuje dane.
5.4. Cache hit rate: szybkość i koszt vs ryzyko nieaktualności
Cache w agentach może dotyczyć różnych warstw: wyników narzędzi, wyszukiwania, embeddingów, a czasem nawet odpowiedzi LLM (z ostrożnością). Monitoruj zarówno korzyści, jak i skutki uboczne.
- Cache hit rate – per warstwa i per endpoint/narzędzie.
- Latency saved – oszczędność czasu dzięki cache (różnica vs miss).
- Cost saved – oszczędność tokenów i kosztów narzędzi.
- Staleness indicators – sygnały nieaktualności (np. age, TTL breaches, odsetek „regret” gdy po odświeżeniu wynik się zmienia).
- Cache key cardinality – czy klucze nie są zbyt unikalne (cache nie działa) lub zbyt ogólne (ryzyko błędnej odpowiedzi).
W agentach cache często wpływa bezpośrednio na jakość (np. nieświeże dane) – dlatego cache nie powinien być oceniany wyłącznie przez pryzmat hit rate.
5.5. Błędy: od awarii infrastruktury do błędów „poznawczych”
Klasyczny monitoring skupia się na wyjątkach i kodach HTTP. W agentach trzeba dodać warstwę błędów wynikających z natury generacji i orkiestracji.
- LLM provider errors – timeouts, rate limits, błędy serwera, problemy z połączeniem.
- Parsing/validation failures – niezgodność z oczekiwanym formatem (np. JSON), problemy z walidacją schematu.
- Safety/guardrail triggers – blokady treści, odmowy, przekroczenia polityk.
- Tool execution failures – błędy narzędzi (techniczne) oraz błędne parametry wejściowe generowane przez agenta.
- Loop/degeneration signals – nadmierna liczba iteracji, powtarzające się kroki, „stuck” w planowaniu.
Metryki błędów raportuj jako: rate, unique affected sessions oraz wpływ na użytkownika (np. czy doszło do odpowiedzi zastępczej). Dzięki temu widać, czy system „degraduje łagodnie”, czy przerywa pracę.
5.6. Jakość odpowiedzi: mierzalna, ale wielowymiarowa
Jakość w agentach LLM nie sprowadza się do „brak błędów”. Dobre metryki jakości powinny łączyć sygnały behavioral (co użytkownik zrobił) oraz automatyczne (ocena treści), najlepiej segmentowane per scenariusz.
- Task success / resolution rate – czy użytkownik osiągnął cel (np. zamknięcie sprawy, poprawne wykonanie akcji).
- User feedback – oceny, zgłoszenia „nie to”, rezygnacje; ważne jest trendowanie i segmentacja.
- Rewrite/reprompt rate – odsetek przypadków, gdy użytkownik musi doprecyzować (sygnał niezrozumienia).
- Groundedness / citation presence – czy odpowiedź opiera się na źródłach (gdy wymagane) i czy cytowania są obecne.
- Policy compliance rate – zgodność z zasadami bezpieczeństwa i stylu odpowiedzi.
- LLM-as-judge (metrika pomocnicza) – automatyczna ocena jakości, użyteczna do trendów, ale wymagająca kalibracji.
Różnica względem klasycznych systemów: metryki jakości mogą się wahać mimo braku zmian w kodzie (np. inne zapytania, inny kontekst, inne dane z narzędzi). Dlatego jakość monitoruje się przez koszyki użycia (typy zadań) i porównuje w czasie z uwzględnieniem sezonowości.
5.7. Zestaw minimalny: co mierzyć od pierwszego dnia
| Obszar | Minimalne metryki | Po co |
|---|---|---|
| Latency | TTFT, TTR, p95 per endpoint, tool latency p95 | Wykrywanie regresji i wąskich gardeł etapów |
| Tokeny/koszt | input/output tokens, cost/request, cost/conversation | Kontrola budżetu i wykrywanie puchnięcia kontekstu |
| Narzędzia | success rate, error rate, retries, call count | Stabilność integracji i diagnoza pętli agentowych |
| Cache | hit rate, latency saved, staleness age | Balans koszt/szybkość vs aktualność danych |
| Błędy | provider errors, validation failures, guardrail triggers | Rozróżnienie awarii technicznych od błędów formatu i polityk |
| Jakość | task success proxy, reprompt rate, feedback trend | Szybkie wykrywanie spadku użyteczności |
5.8. Krótki przykład: instrumentacja metryk w stylu „request + steps”
// Pseudokod: metryki na poziomie żądania i kroków agenta
metrics.timing("agent.ttft_ms", ttftMs, tags)
metrics.timing("agent.ttr_ms", ttrMs, tags)
metrics.count("agent.steps", stepsCount, tags)
metrics.count("llm.input_tokens", inputTokens, tags)
metrics.count("llm.output_tokens", outputTokens, tags)
metrics.gauge("llm.cost_usd", estimatedCostUsd, tags)
for (toolCall in toolCalls) {
metrics.timing("tool.latency_ms", toolCall.latencyMs, { ...tags, tool: toolCall.name })
metrics.count("tool.calls", 1, { ...tags, tool: toolCall.name })
metrics.count("tool.errors", toolCall.ok ? 0 : 1, { ...tags, tool: toolCall.name, reason: toolCall.errorType })
}
metrics.count("agent.reprompts", reprompted ? 1 : 0, tags)
metrics.count("agent.task_success", taskSuccess ? 1 : 0, tags)
W praktyce tagi/etykiety warto ograniczać, aby uniknąć eksplozji krotności (np. nie tagować metryk pełnym promptem ani ID użytkownika). Segmentację lepiej robić przez stabilne atrybuty: typ zadania, wersja agenta, model, środowisko.
6. SLO dla agentów LLM: definicje dla jakości, czasu odpowiedzi i kosztów oraz budżety błędów
SLO (Service Level Objective) dla agentów LLM to mierzalne cele opisujące, jak dobrze agent ma działać w praktyce. W odróżnieniu od klasycznych usług, gdzie „poprawność” bywa binarna (działa/nie działa), w agentach część wymagań jest probabilistyczna (jakość odpowiedzi, adekwatność decyzji, trafność użycia narzędzi) oraz silnie zależna od kontekstu rozmowy. Dlatego SLO zwykle definiuje się w kilku wymiarach jednocześnie: jakość, czas i koszt, a następnie zarządza kompromisami poprzez budżety błędów.
6.1. Co jest „usługą” w agencie i co mierzyć
Zanim zapiszesz SLO, określ jednostkę, której dotyczy:
- Odpowiedź (pojedynczy turn): najprostsze do mierzenia, dobre dla aplikacji Q&A i asystentów.
- Zadanie (task): zakończenie celu użytkownika, często obejmuje wiele turnów i wywołań narzędzi.
- Sesja: ciąg interakcji; przydatne, gdy liczy się utrzymanie kontekstu lub konsekwencja zachowania.
W praktyce warto zdefiniować SLO na poziomie odpowiedzi (operacyjnie stabilne) oraz co najmniej jedno SLO na poziomie zadania (bliżej wartości biznesowej).
6.2. SLO jakości: „dobrze” znaczy co?
Jakość w agentach LLM obejmuje zarówno treść odpowiedzi, jak i zachowanie agenta (dobór narzędzi, zgodność z politykami). SLO jakości powinny być oparte o jawne kryteria, a nie wyłącznie o subiektywne oceny.
- Użyteczność/zgodność z intencją: czy odpowiedź rozwiązuje problem użytkownika w ramach ustalonego kontekstu.
- Faktyczność: odsetek odpowiedzi bez istotnych błędów rzeczowych w obszarach, gdzie weryfikacja jest możliwa.
- Kompletność: czy agent dostarcza wymagane elementy (np. kroki, linki, wynik działania narzędzia).
- Zgodność z politykami: brak naruszeń (np. treści zabronione, ujawnienie sekretów, nieuprawnione działania).
- Poprawność działania narzędziowego: czy agent wybiera właściwe narzędzie i poprawnie interpretuje wynik (bez „wymyślania” rezultatów).
Ze względu na nieostrość pojęcia jakości, częstą praktyką jest rozdzielenie SLO na: jakość merytoryczną (przydatność/fakty) oraz jakość behawioralną (zgodność, bezpieczeństwo, poprawne użycie narzędzi). To umożliwia różne priorytety i osobne budżety błędów.
6.3. SLO czasu odpowiedzi: szybkość postrzegana vs. całkowita
Dla agentów liczy się zarówno czas do pierwszego użytecznego sygnału (percepcja), jak i czas do ukończenia (wynik). Dlatego warto rozróżnić:
- TTFB / time-to-first-token (lub czas do pierwszej części odpowiedzi): wpływa na wrażenie „responsywności”.
- Time-to-final: czas do zakończenia odpowiedzi w danym turnie.
- Time-to-task-complete: czas do osiągnięcia celu (gdy agent wykonuje kroki i narzędzia).
W SLO czasu unikaj średniej; stosuj percentyle (np. p95/p99) oraz segmentuj po typach zadań (proste Q&A vs. złożone działania narzędziowe), bo mieszanie klas zadań zaciemnia obraz i utrudnia decyzje produktowe.
6.4. SLO kosztów: budżet tokenów, narzędzi i „przepaleń”
Koszt w agentach jest częścią niezawodności: gdy koszt wymyka się spod kontroli, system przestaje być utrzymywalny. SLO kosztowe można formułować jako:
- Budżet kosztu na odpowiedź (np. p95 kosztu poniżej progu).
- Budżet kosztu na zadanie (zwłaszcza dla agentów wieloetapowych).
- Limit liczby wywołań narzędzi na turn/zadanie (ochrona przed pętlami i „nadgorliwością”).
- Limit retry oraz koszt retry (bo generują ukryty narzut).
W kosztach ważne jest rozdzielenie: kosztu przewidywalnego (tokeny) od kosztu zależnego od narzędzi (API zewnętrzne, wyszukiwarki, bazy, płatne integracje). SLO powinno pilnować obu wymiarów, bo optymalizacja jednego może zwiększać drugi.
6.5. Budżety błędów: jak zarządzać kompromisami
Budżet błędów to „przestrzeń na ryzyko” wynikająca z SLO: jeśli celem jest 99,5% spełnionych odpowiedzi, to 0,5% stanowi budżet błędów w danym oknie czasu. W agentach budżet błędów jest szczególnie użyteczny, bo pozwala sterować napięciem między:
- jakością (np. dodatkowe kroki weryfikacji),
- latencją (więcej narzędzi = wolniej),
- kosztem (więcej tokenów i wywołań = drożej).
Praktyczne zastosowania budżetu błędów w agentach:
- Gating wdrożeń: jeśli budżet błędów jakości/zgodności jest „spalony”, wstrzymujesz rollout zmian promptów, modeli lub narzędzi.
- Tryby degradacji: gdy kończy się budżet latencji lub kosztu, przełączasz się na tańszy/szybszy tryb (np. mniej narzędzi, krótsze odpowiedzi), o ile nie narusza to SLO bezpieczeństwa.
- Priorytetyzacja napraw: przekroczenie budżetu w obszarze „zgodność” traktujesz ostrzej niż w obszarze „styl odpowiedzi”.
Warto przyjąć zasadę: SLO bezpieczeństwa i zgodności ma najwyższy priorytet i najmniejszy (lub zerowy) tolerowany budżet błędów, natomiast SLO kosztu i latencji mogą mieć większą elastyczność w zależności od produktu.
6.6. Przykładowy zestaw SLO (szablon do adaptacji)
| Wymiar | Obiekt | Przykładowa definicja SLO | Uwagi |
|---|---|---|---|
| Jakość | Zadanie | >= 98% zadań zakończonych wynikiem spełniającym kryteria „użyteczne” w oknie 7 dni | Warto rozbić na klasy zadań |
| Faktyczność | Odpowiedź | >= 99% odpowiedzi bez wykrytej istotnej niezgodności z bazą referencyjną (gdzie możliwe do sprawdzenia) | Nie wszystko da się zweryfikować automatycznie |
| Zgodność | Odpowiedź | >= 99,9% odpowiedzi bez naruszeń polityk treści i bez ujawnień wrażliwych danych | Najwyższy priorytet |
| Czas | Odpowiedź | p95 time-to-first-token <= X ms oraz p95 time-to-final <= Y s | Oddziel percepcję od całości |
| Czas | Zadanie | p95 time-to-task-complete <= Z s | Istotne przy agentach narzędziowych |
| Koszt | Zadanie | p95 kosztu na zadanie <= A oraz p99 liczby wywołań narzędzi <= B | Chroni przed pętlami i eskalacją kosztów |
6.7. Minimalny zapis SLO jako kontrakt (przykład)
Dobry zapis SLO jest jednoznaczny: definiuje okno czasu, populację (jakie żądania liczymy), metodę pomiaru i próg. Poniżej minimalny szablon, który można traktować jako „kontrakt” między produktem a zespołem:
{
"slo": {
"name": "agent.response.latency.p95",
"window": "7d",
"population": "successful_responses",
"indicator": "time_to_final_ms",
"threshold": { "percentile": 95, "lte_ms": 2500 }
},
"error_budget": {
"window": "7d",
"allowed_violations_ratio": 0.01,
"actions_on_burn": ["freeze_rollout", "enable_degradation_mode"]
}
}
Kluczowe jest, by SLO nie było wyłącznie raportem. Ma ono uruchamiać decyzje operacyjne: kiedy zwalniasz rollout, kiedy optymalizujesz koszty, a kiedy wprowadzasz mechanizmy poprawy jakości.
7. Przykładowy schemat eventów (JSON) i praktyczne zasady nazewnictwa/wersjonowania
Spójny schemat zdarzeń jest „kręgosłupem” observability agentów: pozwala łączyć logi rozmowy, decyzje, wywołania narzędzi i wynik w jedną opowieść o tym, co się wydarzyło. W agentach LLM szczególnie ważne jest, by eventy były jednocześnie czytelne dla ludzi (debug) i stabilne dla systemów (analizy, alerty), a przy tym odporne na szybkie zmiany promptów, narzędzi i wersji modeli.
Poniżej znajduje się przykład, jak myśleć o „minimalnym, ale użytecznym” schemacie: event jako pojedynczy rekord, z obowiązkowymi identyfikatorami korelacji, metadanymi runtime oraz ujednoliconą sekcją payload zależną od typu zdarzenia. W tej sekcji chodzi o kształt i zasady, a nie o implementacyjne detale.
Założenia przykładowego eventu
- Stały „nagłówek”: czas, typ, źródło, środowisko, wersje, identyfikatory korelacji.
- Oddzielny payload: część zmienna zależna od typu eventu, najlepiej z własnym mini-schematem.
- Stabilne identyfikatory: możliwość scalenia zdarzeń w ramach jednej sesji, jednego trace’u i jednego „kroku” agenta.
- Jawna wersja schematu: możliwość ewolucji bez łamania konsumentów logów.
Przykładowy schemat pojedynczego eventu (JSON)
{
"schema": "ai.agent.observability.event",
"schema_version": "1.0.0",
"event_id": "<uuid>",
"event_name": "tool.call",
"timestamp": "<RFC3339>",
"severity": "INFO",
"service": {
"name": "agent-api",
"env": "prod",
"region": "eu"
},
"correlation": {
"trace_id": "<trace-id>",
"span_id": "<span-id>",
"parent_span_id": "<span-id|null>",
"session_id": "<session-id>",
"request_id": "<request-id>",
"agent_step": 3
},
"actor": {
"user_id": "<stable-id-or-null>",
"tenant_id": "<tenant-id-or-null>"
},
"runtime": {
"model": {
"provider": "<provider>",
"name": "<model-name>",
"version": "<model-version-or-snapshot>"
},
"build": {
"app_version": "<git-sha-or-semver>",
"prompt_version": "<prompt-semver-or-hash>"
}
},
"metrics": {
"duration_ms": 1280,
"tokens_in": 420,
"tokens_out": 210,
"cost_usd": 0.0042
},
"payload": {
"tool": {
"name": "<tool-name>",
"operation": "<operation>",
"attempt": 1
},
"input": {
"arguments": { "<key>": "<value>" }
},
"output": {
"status": "ok",
"result_ref": "<blob-uri-or-inline-small>"
},
"error": null
}
}Ten szablon celowo rozdziela elementy, które powinny być porównywalne w czasie (np. event_name, identyfikatory, wersje), od treści, która może szybko ewoluować (np. argumenty narzędzia). Dzięki temu łatwiej utrzymać kompatybilność i jednocześnie zachować przydatność diagnostyczną.
Typy zdarzeń i konwencja nazw
Najpraktyczniej traktować event_name jako kontrakt. Dobre nazwy są przewidywalne, nie zawierają danych dynamicznych i dają się grupować. Sprawdza się format kropkowany: domena.kategoria.akcja.
- conversation.message – zdarzenie pojawienia się wiadomości (wejście/wyjście), bez mieszania z logiką narzędzi.
- agent.plan – zapis faktu podjęcia planowania lub wyboru strategii (bez wklejania całej treści rozumowania jako wymogu schematu).
- agent.decision – decyzja sterująca przepływem (np. „call_tool”, „ask_user”, „finish”).
- tool.call / tool.result – rozpoczęcie i zakończenie wywołania narzędzia (umożliwia osobne mierzenie czasu i retry).
- model.request / model.response – wejście/wyjście z warstwy modelu (przydatne do kosztów i latencji).
- guardrail.trigger – zadziałanie polityk (np. moderacja, ograniczenia danych), jako osobna kategoria.
- error – błąd, który nie mieści się w prostym „result status”, z jasno określonym kodem i klasą.
Unikaj nazw typu tool.call.weather_for_warsaw (dynamiczne końcówki rozbijają agregacje). Dane szczegółowe powinny trafić do pól w payloadzie.
Zasady stabilności pól (co musi być stałe, co może się zmieniać)
- Stałe: schema, schema_version, event_name, timestamp, podstawowe identyfikatory korelacji oraz kluczowe pola metryk (np. duration_ms).
- Elastyczne: zawartość payload (argumenty, wynik narzędzia, skróty/odnośniki do większych artefaktów), o ile nie łamie to istniejących konsumentów.
- Nieprzenośne: pola „debug-only” (np. pełne prompty) powinny być opcjonalne i wyraźnie oznaczone, aby nie stały się zależnością analityk/alertów.
Wersjonowanie schematu: semver i kompatybilność
Wersjonowanie schematu logów ma sens tylko wtedy, gdy jest konsekwentne. Najczęściej sprawdza się semver:
- PATCH: doprecyzowanie opisów, poszerzenie zakresu wartości, poprawki niezmieniające kształtu danych.
- MINOR: dodanie nowych, opcjonalnych pól; dodanie nowych wartości enum w sposób, który nie psuje parserów (np. parser tolerancyjny).
- MAJOR: usunięcie/zmiana znaczenia pól, zmiana typu, restrukturyzacja payloadu, zmiana wymagań co do obecności pól.
Praktyczna zasada: nigdy nie zmieniaj znaczenia istniejącego pola „w miejscu”. Jeśli coś ma znaczyć co innego, dodaj nowe pole i oznacz stare jako przestarzałe.
Konwencje dla pól, enumów i kodów błędów
- Nazwy pól: spójny styl (np. snake_case) i unikanie skrótów, które różne zespoły rozumieją inaczej.
- Enumy: preferuj małe, stabilne zestawy wartości (np. severity: DEBUG/INFO/WARN/ERROR), a niestabilne szczegóły przenieś do osobnych pól (np. error.class, error.code).
- Kody błędów: rozdziel klasę (np. timeout, validation, rate_limit) od źródła (model/tool/network) i od powtarzalności (retryable true/false).
- Wartości liczbowe: trzymaj jednostki w nazwie (duration_ms, cost_usd), żeby uniknąć domysłów w analizach.
Artefakty duże lub wrażliwe: referencje zamiast inline
W logach agentów łatwo o pola, które rosną (np. pełne treści, dokumenty, wyniki narzędzi). Żeby schemat pozostał wydajny i bezpieczny, traktuj payload jako miejsce na skrót lub odnośnik (np. result_ref), a nie magazyn wszystkiego. Dzięki temu event pozostaje lekki, a jednocześnie możliwy do „doreferowania” w debug/replay, jeśli masz odpowiednie uprawnienia.
Minimalny zestaw „must have” do korelacji i diagnozy
- trace_id i span_id – do złożenia ścieżki wykonania.
- session_id i (jeśli dotyczy) user_id/tenant_id – do analizy per użytkownik/klient.
- event_name + schema_version – do stabilnego parsowania i agregacji.
- model + prompt_version + app_version – do porównań jakości i regresji po zmianach.
- duration_ms/tokens/cost – do powiązania jakości z czasem i kosztem.
Jeśli utrzymasz te elementy spójnie, reszta schematu może ewoluować szybciej bez utraty użyteczności observability.
8. Przykładowy dashboard: kluczowe wykresy, alerty i workflow reagowania na incydenty
Dashboard dla agentów LLM powinien odpowiadać na trzy pytania operacyjne: czy agent działa, czy działa dobrze oraz czy działa opłacalnie. W odróżnieniu od klasycznych usług backendowych, tu „zdrowie” systemu wynika nie tylko z dostępności API, ale też z jakości odpowiedzi, poprawności użycia narzędzi oraz stabilności zachowania w dłuższych sesjach. Dobrze zaprojektowany widok łączy sygnały z rozmów, narzędzi i infrastruktury w jednym miejscu, tak aby skracać czas diagnozy i ograniczać koszt błędnych odpowiedzi.
Kluczowe wykresy, które warto mieć „na pierwszym ekranie”
- Ruch i obciążenie: liczba sesji i wiadomości w czasie, rozkład długości rozmów, udział użytkowników powracających. To pomaga odróżnić awarię od naturalnego spadku ruchu oraz wykryć nagłe zmiany profilu zapytań.
- Latencja end-to-end: czas do pierwszej sensownej odpowiedzi oraz czas całkowity, najlepiej w percentylach. Dla agentów ważne jest rozdzielenie, czy opóźnienie wynika z modelu, narzędzi, czy orkiestracji.
- Skuteczność i niezawodność narzędzi: odsetek sukcesów wywołań, najczęstsze typy błędów, retry rate oraz czas wykonania narzędzi. W agentach to często główne źródło degradacji doświadczenia.
- Jakość w ujęciu operacyjnym: proste, obserwowalne proxy jakości, np. odsetek rozmów zakończonych eskalacją, rezygnacją, prośbą o doprecyzowanie lub zbyt częstymi korektami. Chodzi o sygnały, które dają się monitorować bez pełnej oceny semantycznej.
- Koszt i zużycie: tokeny lub równoważne miary zużycia w czasie, koszt na sesję, koszt na udaną realizację zadania. W agentach koszt zwykle rośnie skokowo przez iteracje rozumowania i łańcuch narzędzi.
- Stabilność zachowania: udział odpowiedzi odrzuconych przez filtry bezpieczeństwa, odsetek przerwanych generacji, przypadki przekroczeń limitów kontekstu. To sygnalizuje zarówno problemy w danych wejściowych, jak i w konfiguracji.
Alerty: co alarmować, aby nie utonąć w powiadomieniach
Alerty powinny być zorientowane na wpływ na użytkownika i budżety niezawodności, a nie na każdy pojedynczy błąd. Dla agentów LLM szczególnie istotne są alerty zbudowane na zmianach trendu oraz na korelacji pomiędzy warstwami (model ↔ narzędzia ↔ orkiestracja).
- Degradacja czasu odpowiedzi: gwałtowny wzrost percentyli latencji end-to-end lub czasu do pierwszej odpowiedzi, z rozróżnieniem na źródło opóźnienia (np. narzędzia vs generacja).
- Skok błędów narzędzi: wzrost odsetka nieudanych wywołań, wzrost retry rate, wzrost timeoutów. To często koreluje z „pętlami” agenta i kosztami.
- Wzrost kosztu na sesję: nagłe odchylenie kosztu/zużycia przy stałym ruchu może oznaczać niekontrolowane iteracje, złą politykę planowania lub regresję promptów.
- Spadek proxy jakości: wzrost eskalacji, spadek domknięcia zadań, wzrost liczby korekt w obrębie jednej sesji. Takie alerty są bardziej użyteczne niż subiektywne skargi, bo są mierzalne i szybkie.
- Problemy z bezpieczeństwem: wzrost odrzuceń przez polityki, wykrycia wrażliwych danych w logach, nietypowe wzorce zapytań. Alert powinien uruchamiać także ścieżkę zgodności, nie tylko techniczną.
Workflow reagowania na incydenty: od symptomu do przyczyny
W agentach warto stosować podejście „najpierw wpływ, potem przyczyna”, bo ten sam symptom (np. dłuższy czas odpowiedzi) może wynikać z wielu warstw. Dashboard powinien prowadzić operatora ścieżką diagnozy bez konieczności ręcznego skakania między narzędziami.
- Triaging: potwierdzenie, czy problem dotyczy wszystkich, czy segmentu (konkretny kanał, region, typ użytkownika, konkretne narzędzie). Szybko określ priorytet na podstawie wpływu na użytkowników i kosztów.
- Izolacja warstwy: sprawdzenie, czy dominuje problem modelu (np. opóźnienie generacji), narzędzi (timeouty), czy orkiestracji (pętle decyzji). Celem jest zawężenie obszaru, zanim zacznie się głębokie debugowanie.
- Korelacja zdarzeń w sesji: przejście od metryk agregowanych do widoku pojedynczych sesji, aby zobaczyć typowy przebieg „złych” interakcji i powtarzalne wzorce.
- Mitigacje: działania o szybkim efekcie i niskim ryzyku, np. ograniczenie liczby iteracji, czasowe wyłączenie problematycznego narzędzia, przełączenie na tryb degradacji (prostsza odpowiedź bez narzędzi), dostrojenie limitów timeoutów.
- Weryfikacja i zamknięcie: potwierdzenie powrotu do normy na wykresach wpływu (latencja, sukces narzędzi, proxy jakości) oraz obserwacja, czy nie pojawiły się efekty uboczne (np. spadek jakości po redukcji narzędzi).
- Post-incident learning: krótkie podsumowanie: co wykrył dashboard, czego nie wykrył, które alerty były zbyt czułe lub spóźnione, oraz jakie dodatkowe widoki są potrzebne, aby następnym razem skrócić czas diagnozy.
Dobrze zaprojektowany dashboard dla agentów LLM nie jest „ładnym raportem”, tylko narzędziem operacyjnym: łączy zdrowie techniczne z doświadczeniem użytkownika i kosztami, a jednocześnie wspiera szybkie decyzje o degradacji funkcji, izolacji narzędzi i przywracaniu stabilności. Jeśli chcesz poznać więcej takich przykładów, zapraszamy na szkolenia Cognity, gdzie rozwijamy ten temat w praktyce.
Majczęściej zadawane pytania i odpowiedzi odnośnie Observability dla agentów: logi zdarzeń, ścieżki rozumowania, trace narzędzi i SLO odpowiedzi
Observability agentów LLM obejmuje nie tylko błędy i czas odpowiedzi, ale też przebieg decyzji, użycie narzędzi i wpływ na koszt oraz jakość odpowiedzi. W klasycznych aplikacjach ścieżka wykonania jest zwykle bardziej przewidywalna. W agentach trzeba dodatkowo śledzić zmienność odpowiedzi, wieloetapowość działania, ryzyko halucynacji, pętle oraz zależność od kontekstu rozmowy.
Najlepiej zacząć od logów, które pokazują pełny przebieg jednej odpowiedzi agenta. Minimalny zestaw zwykle obejmuje:
- zdarzenia rozmowy i metadane wiadomości,
- decyzje agenta i wybór strategii,
- wywołania narzędzi wraz ze statusem i czasem,
- błędy, retry, fallbacki i tryby degradacji.
Taki podział pozwala szybko ustalić, czy problem leży po stronie modelu, orkiestracji czy integracji.
Nie, bezpieczniej i praktyczniej jest logować wynik decyzji oraz jej kontekst, a nie pełną surową ścieżkę rozumowania. Artykuł podkreśla, że większą wartość operacyjną daje zapis: jaki krok agent wybrał, dlaczego użył narzędzia, czy kontynuował zadanie i jakie ryzyko oceniono. Ogranicza to także ryzyko utrwalania wrażliwych treści w logach.
session_id powinno spinać rozmowę, trace_id jedną turę lub zadanie, a span_id pojedynczy krok wykonania. To rozdzielenie ułatwia analizę i debugowanie. Typowy błąd polega na tworzeniu jednego trace'u dla całej sesji, co utrudnia diagnozę. Lepsze jest krótkie śledzenie na poziomie tury oraz łączenie go z dłuższym kontekstem sesji.
Do replay i debug najlepiej przechowywać metadane kroków, wersje konfiguracji oraz referencje do artefaktów, a nie pełne duże payloady w każdym śladzie. Przydatne są szczególnie identyfikatory wejść i wyjść, wersja promptu, modelu i narzędzia, źródła danych oraz krótki opis decyzji sterującej. Dzięki temu można odtworzyć przebieg bez nadmiernego rozrostu trace'ów.
Najskuteczniejsze jest ograniczanie treści w logach i zastępowanie ich metadanymi oraz redakcją pól wrażliwych. W praktyce warto wdrożyć:
- maskowanie PII i sekretów,
- logowanie wersji promptów zamiast pełnych instrukcji,
- krótszą retencję dla treści niż dla metryk,
- ścisłą kontrolę dostępu do logów treściowych.
Taki model zmniejsza ryzyko zbudowania niekontrolowanego repozytorium danych produkcyjnych.
Na start warto mierzyć czas, koszt, użycie narzędzi, błędy i podstawowe proxy jakości odpowiedzi. W praktyce oznacza to TTFT i czas pełnej odpowiedzi, tokeny wejścia i wyjścia, koszt na żądanie lub sesję, success rate narzędzi, retry oraz sygnały takie jak reprompt rate czy feedback trend. Taki zestaw szybko pokazuje regresje techniczne i spadek użyteczności.
Dobre SLO dla agenta AI powinny być rozdzielone na jakość, czas odpowiedzi i koszt, a następnie powiązane z budżetem błędów. Najlepiej definiować je osobno dla odpowiedzi i dla zadania. SLO powinno jasno określać populację, okno czasu, wskaźnik i próg. Dzięki temu można świadomie decydować o rolloutach, degradacji działania i priorytecie napraw.