Obserwowalność agentów AI korporacyjnych przy użyciu Langfuse i OCI
Dlaczego logi, metryki i ślady nie wystarczają dla agentów GenAI oraz jak śledzić prompty, wywołania narzędzi, tokeny i sesje za pomocą otwartego oprogramowania Langfuse w OCI Agents.
Źródła: Observability for Enterprise AI Agents: an open-source solution
Łogi, metryki i ślady nie pokażą ci, dlaczego agent AI korporacyjnego udzielił złej odpowiedzi. Aby zrozumieć te systemy, musisz również zobaczyć prompty, kontekst przekazany modelowi, wywołania narzędzi, użycie tokenów, czasy odpowiedzi oraz jakość wyniku. Ten tekst wyjaśnia, dlaczego sztuczna inteligencja generatywna potrzebuje innego podejścia do możliwości obserwacji, a następnie pokazuje konkretną konfigurację wykorzystującą Langfuse, która łączy się z agentami OCI Enterprise AI dzięki kompatybilności z API OpenAI Responses.
Dlaczego to ma znaczenie
Pojęcie „agent” jest używane w odniesieniu do każdego procesu pracy, który wykorzystuje jeden lub więcej dużych modeli językowych w celu uzyskania wyniku. To zaciera rzeczywistą różnicę. Prawdziwy agent zapewnia autonomię, umożliwia korzystanie z narzędzi i zarządzanie kontekstem, a wraz z tym znacznie większą złożoność operacyjną.
Drugi problem jest jeszcze bardziej palący w przedsiębiorstwach. Uwaga skupia się na „magii” sztucznej inteligencji, podczas gdy praca niezbędna do niezawodnego, kontrolowanego i wysokiej jakości działania tych systemów jest zaniedbywana. Obserwowalność znajduje się na szczycie tej listy. W przypadku złożonego agenta opartego na technologii GenAI nie jest to drobna kwestia techniczna – to właśnie ona umożliwia zrozumienie zachowania systemu, analizę błędów, ocenę jakości odpowiedzi oraz kontrolę kosztów i opóźnień.
Pierwsza część tekstu definiuje obserwowalność oraz jej znaczenie w kontekście sztucznej inteligencji generatywnej. Druga część przedstawia prosty w użyciu setup o otwartym kodzie źródłowym, który można łatwo uruchomić na platformie OCI, wraz z przykładami zebranych danych i wyjaśnieniem, dlaczego są one przydatne.
Co oznacza obserwowalność
Obserwowalność to właściwość złożonych systemów. Mówiąc prościej, system jest obserwowalny, jeśli można wywnioskować jego wewnętrzne zachowanie na podstawie sygnałów, które emituje i które można zebrać oraz przeanalizować. Bardziej formalnie, dwa różne stany wewnętrzne muszą być rozróżnialne na podstawie sygnałów zewnętrznych. To, co system emituje, musi wiarygodnie ujawniać to, co dzieje się w jego wnętrzu.
Powstają z tego dwie konsekwencje. Obserwowalność ma największe znaczenie tam, gdzie istnieje wiele komponentów, zależności i interakcji. Ponadto obserwowanie z zewnątrz nie wystarcza, ponieważ system musi być zaprojektowany i wyposażony w odpowiednie narzędzia, aby dostarczać przydatnych informacji. Prawidłowe uruchomienie czegoś takiego jak agent AI w przedsiębiorstwie oznacza zbieranie danych telemetrycznych, które ujawniają jego stan, zachowanie, anomalie oraz wydajność.
W tym właśnie aspekcie obserwowalność różni się od klasycznego monitorowania. Monitorowanie odpowiada na pytania, które przemyślałeś z góry, takie jak ile procesora wykorzystuje dana usługa lub jak wolna była prośba. Obserwowalność musi również umożliwiać badanie niespodzianek, problemów i pytań, których nikt nie przewidział na etapie projektowania, często określanych jako „nieznane nieznane”.
Obserwowalność przed sztuczną inteligencją generatywną
„Systemy tradycyjne” oznaczają tutaj aplikacje stworzone przed tym, zanim sztuczna inteligencja generatywna stała się powszechna, mniej więcej przed rokiem 2023. Ich obserwowalność opierała się na trzech rodzajach danych: logach, metrykach i śladach.
Łogi i metryki są dobrze znane. Ślad to pełna dokumentacja pojedynczej prośby lub interakcji, składająca się z elementów opisujących poszczególne kroki. W architekturze mikrosług jeden ślad może obejmować całą transakcję aplikacyjną, zawierając elementy odpowiadające wywołaniu API, zapytaniu do bazy danych lub wezwaniu zewnętrznej usługi. Aby była skuteczna, taka metoda musi śledzić prośbę we wszystkich komponentach, z którymi się kontaktuje.
Dla agentów opartych na GenAI ten klasyczny model sam w sobie nie wystarcza. Oprócz logów, metryk i śladów trzeba również obserwować, co model robi, jaki kontekst otrzymał, jakie narzędzia wykorzystał oraz jak dobre były jego odpowiedzi.
Co zmienia się dzięki GenAI
Oprogramowanie konwencjonalne jest dość przewidywalne. Systemy oparte na sztucznej inteligencji generatywnej są mniej przewidywalne, szczególnie gdy mają pewną swobodę podejmowania decyzji. Wynik działania LLM zależy od znacznie większej liczby czynników niż dane wprowadzone przez użytkownika, a wszystkie te elementy muszą być widoczne.
Ustawienie umożliwiające obserwację w systemie LLM powinno rejestrować co najmniej cztery rzeczy:
- model oraz parametry wywołania
- instrukcje oraz faktycznie wysłany prompt
- kontekst dostarczony, w tym wcześniejsza historia rozmowy
- sposób działania systemu, w tym wywołania narzędzi, pośrednie wyniki, opóźnienia oraz zużycie tokenów
Patrzenie tylko na ostateczną odpowiedź jest niewystarczające. Aby zrozumieć system GenAI, należy móc odtworzyć, dla każdego śladu, wszystko to, co przyczyniło się do odpowiedzi.
To jest tym bardziej prawdą, gdy model ma swobodę działania. Jeśli może sam wybrać, jakie narzędzia użyć, w jakiej kolejności wykonać działania, jakie źródła skonsultować lub kiedy przestać, to proste polecenia i wyniki nie wystarczą. Trzeba zobaczyć sam proces decyzyjny, w tym sekwencję wywołań narzędzi, czas ich wykonywania oraz wyniki pośrednie.
Nawet pełny zapis działań często nie pozwala określić, czy wynik jest dobry. W tym celu do każdego zapisu zazwyczaj dodaje się oceny. Mogą one pochodzić z tradycyjnej logiki lub z innego modelu językowego, czyli z powszechnie stosowanej obecnie techniki „LLM-as-a-judge”.
Warto rozważyć ocenę odpowiedzi typu RAG. Może ona być częściowo prawidłowa lub wydawać się wiarygodna, mimo że nie ma podstaw w pobranych źródłach. W takim przypadku trzeba odróżnić co najmniej dwa aspekty: przyczynę podstawową, taką jak pobieranie danych, ponowna klasyfikacja lub generowanie, oraz uzasadnienie, czyli to, czy odpowiedź rzeczywiście opiera się na pobranych dokumentach. Sprawdzenia uzasadnienia ujawniają niepotwierdzone twierdzenia, a więc możliwe halucynacje.
Wszystko to oznacza, że zwykła platforma do obserwacji nie będzie wystarczająca dla GenAI. Potrzebny jest narzędzie, które w sposób natywny rejestruje te informacje i jednocześnie minimalizuje wysiłek związany z ich gromadzeniem. Prawdziwa różnica leży w zakresie funkcjonalności – w przypadku GenAI obserwuje się infrastrukturę i szybkość działania jak dotychczas, a dodatkowo kontekst, który widział model, podjęte przez niego decyzje, jakość wygenerowanego wyniku oraz spójność jego zachowania.
Od teorii do gotowej konfiguracji
Zatem możliwość obserwacji agentów korporacyjnych musi obejmować sugestie, kontekst, wywołania narzędzi, czasy odpowiedzi, zużycie tokenów, jakość wyników oraz prawdopodobne przyczyny błędów lub słabych odpowiedzi, oprócz klasycznych sygnałów. Pytanie praktyczne brzmi, jak uzyskać to wszystko w prosty i skuteczny sposób, który pasuje do środowiska korporacyjnego. Poniższa odpowiedź to rozwiązanie open-source, które łatwo zastosować w OCI.
Langfuse
Wśród narzędzi open-source do monitorowania modeli językowych i agentów wyróżnia się Langfuse. Jest to platforma do śledzenia, monitorowania oraz oceny (wyliczania wyników) aplikacji opartych na modelach językowych, obejmująca większość powyżej wymienionych danych: prompty, wyniki, ślady działania, metadane, czasy odpowiedzi, użycie tokenów, wywołania narzędzi oraz wyniki oceny. To coś więcej niż zwykła usługa logowania – zapewnia ustrukturyzowany przegląd tego, jak faktycznie zachowuje się aplikacja oparta na technologii GenAI, zorganizowany wokół śladów działania i sesji, a nie w postaci prostego strumienia linii tekstowych, który trzeba przeszukiwać.
Dlaczego OCI ułatwia integrację
OCI Enterprise AI Agents udostępnia API w pełni kompatybilne z API OpenAI Responses. Ma to znaczenie nie tylko ze względu na wygodę, ponieważ umożliwia ponowne wykorzystanie narzędzi, bibliotek oraz wzorców rozwojowych szerokiego ekosystemu kompatybilnego z OpenAI. W przypadku Langfuse znacznie skraca pracę związana z zbieraniem danych telemetrycznych z wywołań modeli oraz tworzeniem warstwy obserwowalności, dzięki czemu więcej czasu poświęca się analizie, a mniej na konfigurację. To jeden z głównych powodów, dla których OCI i Langfuse dobrze współpracują w środowiskach korporacyjnych.
Szybka implementacja jako dowód koncepcji
Dla celów demonstracyjnych Langfuse można łatwo zainstalować na OCI, na przykład na maszynie wirtualnej Linux, korzystając z oficjalnego rozwiązania Docker Compose dostępnego w repozytorium Langfuse. Nie jest to koniecznie ostateczna architektura dla środowiska przedsiębiorstwa klasy produkcyjnej. Jest to jednak więcej niż wystarczające do weryfikacji pomysłu, zbierania rzeczywistych danych telemetrycznych oraz sprawdzenia, jakie analizy stają się możliwe po integracji. W praktyce szybko stworzyło to działającą platformę, dostępną przez przeglądarkę i gotową do odbierania danych z aplikacji opartych na modelach językowych Pythona.
Podłączanie kodu
Gdy instancja Langfuse jest uruchomiona, kolejnym krokiem jest wyposażenie aplikacji w narzędzia umożliwiające automatyczne przesyłanie danych telemetrii z wywołań modelu. Dzięki zgodności z API Responses jest to proste w przypadku aplikacji Python napisanych już w oparciu o wywołania w stylu OpenAI. Aplikacja nadal wywołuje model w taki sam sposób jak dotychczas, a Langfuse rejestruje istotne informacje.
Zmiany są niewielkie:
- Ustaw kilka zmiennych środowiskowych.
- Użyj klienta dostarczonego przez bibliotekę Langfuse, który jest już wyposażony w mechanizmy do zbierania i wysyłania danych telemetrii.
- Przekaż
conversation_idzamiastsession_id, aby żądania z tej samej rozmowy były łączone w jednej sesji. - Opcjonalnie zmusz do natychmiastowego wysłania danych telemetrii poprzez ich wypłukanie. W przeciwnym razie zostaną one wysłane automatycznie po kilku sekundach.
Co jest zbierane
Po integracji Langfuse automatycznie zbiera wiele przydatnych informacji. Dla agentów obejmuje to nie tylko dane wejściowe i wyjściowe modelu, ale także przepływ wykonywania z pośrednimi etapami, wywołaniami narzędzi oraz informacjami o czasie, które pomagają odtworzyć, w jaki sposób powstał wynik.
Najważniejsze elementy to:
- model i jego wersja
- wyśłany prompt
- wygenerowany wynik
- metadane dołączone do wywołania
- struktura śladu oraz wszystkie jego etapy
- pomiarzy opóźnień, w tym tych widocznych dla użytkownika, takich jak czas do pierwszego tokena
- liczbę tokenów wejściowych i wyjściowych, które służą do analizy kosztów
- wywołania narzędzi i ich szczegóły
- oceny i wyniki powiązane ze śladem
Nie wszystko, co przydatne, pojawia się automatycznie, i tak jest celowo, ponieważ platforma nie może wiedzieć, co twoja firma uważa za dobrą odpowiedź. Oceny specyficzne dla danej dziedziny, niestandardowe wskaźniki oraz metadane biznesowe mogą, a czasami muszą, być dodawane przez aplikację. To połączenie automatycznego zbierania danych z celowym wzbogacaniem sprawia, że narzędzie jest skuteczne.
Sezony
Langfuse może łączyć kilka śladów z jednej sesji użytkownika za pomocą session_id. W takim ustawieniu rozmowa jest identyfikowana standardowym conversation_id z API Responses, więc ustawienie session_id na wartość tego identyfikatora powiązuje wszystkie żądania z tej samej rozmowy. Sezony można następnie przeglądać w interfejsie użytkownika, gdzie każdy z nich zawiera kilka śladów.
Przeglądanie śladu
Rezultaty analizy są wyraźnie widoczne. Interfejs Langfuse umożliwia szczegółowe badanie każdej interakcji, ujawniając informacje, które w przeciwnym razie byłyby rozproszone w logach aplikacji, luźnych metadanych i kodzie. Dla pojedynczej śledzenia można zobaczyć faktycznie wysłany prompt, model, jego parametry, czasy wykonywania, zużyte tokeny, sekwencję wszystkich wywołań oraz wyniki na każdym etapie. Jest to szczególnie ważne podczas badania nietypowego zachowania, problemów z opóźnieniami, rosnących kosztów lub odpowiedzi o niesatysfakcjonującej jakości. Na przykład powolna odpowiedź może wynikać z długiej serii wywołań narzędzi, zbyt długiego promptu lub wolnego pierwszego tokena, a każdy z tych problemów wymaga innego rozwiązania. Bez porównywania czasu trwania operacji na poziomie poszczególnych etapów oraz liczby tokenów, trzeba by zgadywać, który to problem jest przyczyną.
Praktycznym nawykiem wynikającym z tego jest traktowanie każdej rozmowy jako czegoś, co można później odtworzyć. Gdy użytkownik zgłosi złą odpowiedź tydzień później, widok sesji umożliwia otwarcie dokładnych zapisów, przeczytanie oryginalnego zapytania i kontekstu oraz zobaczenie, który narzędzie dostarczyło jakie dane, zamiast próbować odtworzyć sytuację na podstawie pamięci.
Ograniczenia, które należy mieć na uwadze
Wprowadzenie Langfuse nie rozwiązuje wszystkich problemów związanych z obserwowalnością i oceną w systemach GenAI. Bogate zapisy zawierające kontekst są konieczne, ale nie zawsze wystarczające. Najbardziej przydatne wskaźniki zazwyczaj zależą od dziedziny zastosowania i muszą być celowo zaprojektowane. Ponadto rzeczywiste środowiska korporacyjne wymagają dokładnej analizy kwestii bezpieczeństwa, danych wrażliwych, przechowywania danych telemetrycznych, kontroli dostępu oraz architektury wdrażania.
Mimo to platforma otwartego oprogramowania w połączeniu z pełną kompatybilnością API OCI stanowi solidny punkt wyjścia dla konkretnego rozwiązania z zakresu obserwowalności przeznaczonego dla agentów korporacyjnych.
Podsumowanie
Dla agentów AI w środowiskach korporacyjnych obserwowalność nie jest detalami technicznymi ani dodatkową opcją – jest warunkiem koniecznym do zrozumienia zachowania agenta, analizy błędów, oceny jakości odpowiedzi oraz obniżenia czasu reakcji i kosztów działania. Obserwowanie infrastruktury, logów aplikacji oraz standardowych metryk to za mało. Potrzebne są również dane bliższe temu, co faktycznie robi agent: prompty, kontekst, wywołania narzędzi, zużycie tokenów, odczuwana przez użytkownika opóźniona reakcja oraz wyniki ocen.
Langfuse to szczególnie interesująca opcja o otwartym kodzie źródłowym, ponieważ przetwarza i organizuje dużą część tych danych telemetrycznych, a API kompatybilne z OpenAI w OCI Enterprise AI Agents ułatwia integrację. Żadna platforma sama w sobie nie rozwiązuje wszystkiego – bezpieczeństwo, zarządzanie, obsługa danych wrażliwych oraz projektowanie wskaźników specyficznych dla danej dziedziny pozostają niezbędne.
Jeśli te agenty mają przejść od demonstracji i stać się niezawodną częścią rzeczywistych systemów, widoczność nie może być kwestią drugorzędną. Ich złożoność nie da się usunąć, ale można i należy ją ujawnić.
Naturalnym krokiem jest wzbogacanie śladów o wskaźniki, które w bardziej systematyczny sposób mierzą jakość, szczególnie te generowane przez model językowy pełniący rolę sędziego, dzięki czemu każdy ślad zawiera oceny jakości odpowiedzi obok danych technicznych dotyczących jej realizacji.
Literatura pokrewna
- Jak przechowywanie w przeglądarce cichо niszczy dane użytkowników i jak temu zapobiec — Utracone aktualizacje, przestarzałe zrzuty stanu, zmiany schematu oraz wycieki danych z urządzeń współdzielonych mogą uszkodzić dane z localStorage bez żadnego błędu. Wzorce dotyczące zarządzania własnością, wersjonowania i walidacji.
- Praktyczne notatki: Systemy RAG: Kompletny przewodnik od podstaw do zaawansowania (wydanie 2026) — Szczegółowy przewodnik po Praktycznych notatkach: Systemy RAG: Kompletny przewodnik od podstaw do zaawansowania (wydanie 2026): kontrakty, sprawdzania oraz gotowe elementy kodu dla zespołów wdrażających ten wzorzec.