Debugowanie agentów AI: Twój dashboard zna koszt, a nie przyczynę

Debugowanie agenta AI zaczyna się tam, gdzie kończy się twój dashboard obserwowalności. Gdy agent AI do kodowania coś zepsuje, a uruchomienie już się zakończyło, dashboard może pokazać, ile kosztowało to uruchomienie (tokeny, dolary, opóźnienia), ale milczy w kwestii jedynego pytania, które naprawdę się liczy: dlaczego agent zmienił ten plik? Odpowiedzią na nie jest zarejestrowany ślad, który możesz otworzyć, przeczytać i odtworzyć, ponieważ oddaje ci przebieg uruchomienia z powrotem, zamiast opisywać go z zewnątrz.

To przestało być rzadkim zdarzeniem, gdy agenci zaczęli wykonywać prawdziwą pracę. Agent przejdzie przez repozytorium, zmieni kilka plików, uruchomi testy i zamelduje sukces — wszystko między dwoma promptami, które wpisałeś w odstępie kilku minut. Jeśli jedna z tych zmian jest błędna, dowiadujesz się o tym później: gdy terminal jest już zamknięty, gdy bufor przewijania zniknął, gdy proces, który mógł się wytłumaczyć, już się zakończył. To, co stanie się dalej, zależy wyłącznie od tego, co zachowałeś. Jeśli odpowiedzią jest panel kosztów — czeka cię archeologia. Jeśli odpowiedzią jest nagranie — czeka cię czytanie.

Błąd, którego nie możesz odtworzyć.

Tak to wygląda. Wracasz do repozytorium, a plik, którego nikt nie miał dotykać, został przepisany, usunięty albo opróżniony z funkcji, od której zależy wszystko inne. Pytasz agenta, co się stało; sesja jest zamknięta, a nawet tam, gdzie zachował się transkrypt, relacja agenta z własnego przebiegu jest rekonstrukcją, a nie nagraniem. Robisz więc to, co naturalne — uruchamiasz to ponownie — i otrzymujesz inny przebieg. Inne wywołania narzędzi, inne edycje, być może wcale nie ma błędu, bo pierwotna trajektoria zależała od próbkowania, stanu repozytorium i czasu. Przebieg, który musisz zbadać, już nie istnieje.

To jest gorsze niż niereprodukowalne. Jest niereprodukowalne i oznaczone jako sukces. Uruchomienie kończy się kodem 0, gdy agent kończy z kodem 0, nawet jeśli kontrola wewnątrz uruchomienia zakończyła się kodem 1: potok może być zielony, podczas gdy krok weryfikacji wewnątrz uruchomienia nie powiódł się, a kod wyjścia, któremu naturalnie ufasz, nic ci nie mówi.

Nie ma znaczenia, który model router wybrał do uruchomienia (GLM 5.3 Flash czy cokolwiek innego): gdy proces się kończy, rozumowanie znika wraz z nim. Dowody istniały tylko, dopóki proces działał: prompty, wywołania narzędzi, wyniki, diffy. Jeśli nic ich nie zarejestrowało, pytanie „dlaczego to zmieniło ten plik” nie ma odpowiedzi. Ma tylko teorie.

To jest tryb awarii, który oddziela agentów AI do kodowania od każdego narzędzia, które istniało wcześniej: uszkodzenie i wyjaśnienie pojawiają się w tym samym miejscu, a miejsce to się zamyka.

Co mierzy dashboard, a co pomija?

Instynkt po nieudanym przebiegu każe otworzyć pulpit obserwowalności, a ten pulpit będzie naprawdę dobry w swoim zadaniu. Jego zadaniem jest ruch: tokeny dziennie, koszt na model, opóźnienia, wskaźniki błędów. Do planowania pojemności i rozliczeń jest to dokładnie właściwe narzędzie, a jeśli uruchamiasz agentów w produkcji, powinieneś mieć go otwartego.

Ale twoje pytanie nie jest zagregowane. Jest jednostkowe i przyczynowe: dlaczego to uruchomienie zmieniło ten plik? Agregacja pomija właśnie tę szczegółowość, która na nie odpowiada. Uśrednione między uruchomieniami to uruchomienie, które cię interesuje, jest szumem; wewnątrz tego uruchomienia wywołanie narzędzia, które cię interesuje, znów jest szumem.

Dashboard opisuje przebieg z zewnątrz: to, że się odbył, ile ważył, ile kosztował. Nie może wręczyć ci samego przebiegu, a „dlaczego” nie jest cechą opisu. Jest cechą sekwencji.

Jaki był koszt uruchomienia? — Odpowiedź daje panel kosztów vs Odpowiedź daje zarejestrowany ślad.

• Dlaczego agent zmienił ten plik? — Panel kosztów Brak odpowiedzi vs Zarejestrowany ślad Edycja, w kolejności, z jej diff

• Która kontrola nie powiodła się w zielonym przebiegu? — Panel kosztów: brak odpowiedzi vs zarejestrowany ślad. Kontrola z kodem wyjścia.

• Czy mogę powtórzyć dokładnie to samo niepowodzenie? — Panel kosztów: Nie vs Zarejestrowany ślad: Tak, offline, bez kosztów

Warstwa, która na to odpowiada, znajduje się pod spodem: zarejestrowane logi żądań, przechwycone w trakcie trwania przebiegu, z każdą wysłaną prośbą, każdym wykonanym wywołaniem narzędzia i każdą odpowiedzią, która wróciła, w kolejności. Nie podsumowanie przebiegu. Sam przebieg.

Odczytywanie jednego przebiegu jako osi czasu.

Z nagraniem debugowanie przestaje być archeologią, a staje się czytaniem. Archeologia to to, co robisz bez nagrania: git reflog, wpisy stasha, historia powłoki, twoje własne wspomnienie tego, o co prosiłeś wcześniej tego dnia. Czytanie to to, co robisz z nagraniem: otwórz oś czasu i przewiń.

Oś czasu przedstawia przebieg w kolejności, w jakiej miał miejsce: prompt, który go zapoczątkował, każde wywołanie narzędzia, każda edycja pliku wraz z diffem, każde sprawdzenie, każdy kod wyjścia. Migawka systemu plików jest tworzona raz na turę, a nie raz na wywołanie narzędzia — to wystarczy, by zobaczyć stan repozytorium na każdym etapie rozmowy, bez tonięcia w szumie pojedynczych wywołań. To, co sprawia, że jest to debugowanie, a nie przeglądanie, to sąsiedztwo: edycja i sprawdzenie, które ją wychwyciło, znajdują się obok siebie, w kolejności, bez niczego pomiędzy, co wymagałoby spekulacji. „Dlaczego” to w większości właściwość sąsiedztwa.

Konkretny przykład odczytany z zarejestrowanej poprawki: 14 zdarzeń, w tym zmiana pliku wypisana jako +1 -3 oraz nieudane sprawdzenie z kodem wyjścia 1. Edycja i sprawdzenie, które z jej powodu nie przeszło, są w zapisie obok siebie. Na tym polega cała różnica między odtwarzaniem przebiegu z fragmentów a odczytaniem go. Ma to największe znaczenie dla agentów kodujących w terminalu, których przestrzenią roboczą jest terminal, który zamyka się z chwilą zakończenia zadania: oś czasu to scrollback, który przetrwa.

Zarejestrowane czy wywnioskowane: co ślad wie, a co ustalił

Oś czasu mówi ci, co wydarzyło się po kolei. Graf przyczynowy mówi ci, co doprowadziło do czego, a luka między tymi dwoma to miejsce, gdzie trzeba zapracować na zaufanie.

Wykres łączy zdarzenia: tę edycję, potem tę nieudaną kontrolę. Niektóre z tych krawędzi to odnotowane fakty: wywołanie narzędzia, które wygenerowało diff, jest widoczne w logu. Inne są wywnioskowane: konkluzja wykresu, że kontrola nie powiodła się z powodu tego diffa. orca graph oznacza każdą krawędź jako odnotowaną lub wywnioskowaną i w obu przypadkach podaje nazwę reguły, której użył, dzięki czemu zawsze wiesz, czy patrzysz na coś, co zrobiło wykonanie, czy na coś, co narzędzie wywnioskowało o tym wykonaniu.

To rozróżnienie jest egzekwowane, a nie tylko postulowane: wnioskowane krawędzie nigdy nie są zapisywane z powrotem do śladu. Ślad pozostaje wiernym zapisem tego, co się zdarzyło; wnioskowanie to widok nałożony na niego, który możesz badać i kwestionować, a z którym możesz się nie zgadzać. Ma to największe znaczenie, gdy w grę wchodzi więcej niż jeden agent. Gdy agent refaktoryzujący i agent piszący testy pracują na tych samych plikach, „który agent to spowodował” to właśnie pytanie, na które atrybucja wieloagentowa ma odpowiedzieć. Krawędź, która po cichu awansuje z rangi wniosku do rangi faktu, jest właśnie tym, co sprawia, że debugujesz opowieść zamiast przebiegu.

Odtwarzanie tego tak często, jak tylko chcesz, za darmo.

Czytanie wyjaśnia. Powtórka dowodzi. Gdy masz już hipotezę (sprawdzenie nie powiodło się, ponieważ edycja usunęła wywołanie resetu), chcesz uruchomić to ponownie i zobaczyć, jak do tego dochodzi. Ponowne uruchomienie aktywnego agenta zapewnia ci nową trajektorię i nowy rachunek.

Odtworzenie nagrania daje ci ten sam przebieg: powtórka działa przy zablokowanej sieci, więc nie kosztuje tokenów i nie ma żadnej zmienności. Te same zdarzenia, za każdym razem, offline. To właśnie ta właściwość zmienia debugowanie agentów z hazardu w inżynierię: niepowodzenie stało się deterministyczne, a deterministyczne niepowodzenia naprawia się.

To narzędzie również nie jest czarną skrzynką. OrcaReplay jest open source na licencji Apache-2.0, a format zapisu jest objęty licencją CC BY 4.0, więc każdy może stworzyć własną implementację: twoje nagrania nie są zakładnikami zastrzeżonego formatu — nasze również. Co więcej, jest testowane w praktyce, a nie tylko pokazywane w demo: 1393 testy na Node 20 i Node 22. Możesz sam przeczytać kod źródłowy, sprawdzić format i uruchomić zestaw testów, zanim w ogóle powierzysz temu narzędziu przebiegi swojego zespołu.

Przesłanie

Dashboard to rachunek. Zapisany ślad to przebieg. Jeśli Twój plan debugowania agentów AI kończy się na dashboardzie kosztów, to nie masz planu debugowania: masz system rozliczeniowy. Dashboard zawsze będzie w stanie powiedzieć Ci, ile kosztował przebieg, ale nigdy nie powie Ci, {{1}}dlaczego{{/1}} agent usunął Twój plik, ponieważ "dlaczego" żyje w {{2}}sekwencji{{/2}}, a sekwencja istnieje tylko wtedy, gdy ją {{3}}zachowałeś{{/3}}.

Cała metoda to cztery kroki:

• Zapisz przebiegi.

• Przeczytaj oś czasu.

• Sprawdź krawędzie grafu.

• Odtwarzaj te, które Cię przerażają, za darmo, tak często, jak chcesz.

Nota o źródłach: wszystkie dane w tym artykule są raportowane przez producenta i pochodzą z naszego własnego produktu oraz z repozytorium OrcaReplay i jego dokumentacji. Dotyczą one zachowania kodu wyjścia przy uruchomieniu, zarejestrowanej poprawki 14 zdarzeń z diffem +1 -3 i sprawdzeniem exit-1, etykietowania krawędzi w grafie orca, wykonywania migawek raz na turę, odtwarzania offline z zablokowaną siecią oraz zestawu 1393 testów na Node 20 i Node 22. W żadnym miejscu tego artykułu nie przywołano pomiarów zewnętrznych. Zestaw 1393 testów to jedyne twierdzenie, które możesz zweryfikować samodzielnie, klonując repozytorium i uruchamiając te testy. Wszystkie powyższe elementy sprawdzono ostatnio 4 września 2026 r.