Rozwiązywanie problemów związanych z rozmowami agentów za pomocą narzędzia Agent Debugger w pakiecie agentów funkcji Copilot

Agent Debugger to narzędzie diagnostyczne, które umożliwia załadowanie zarejestrowanej rozmowy i przeanalizowanie każdej decyzji podjętej przez agenta. Dla każdej rundy rozmowy można sprawdzić ścieżkę wykonania, czas trwania poszczególnych kroków, wykorzystanie tokenów, źródła wiedzy, argumenty kroków oraz uzasadnienie orkiestratora.

Debugger Agent obsługuje dwa źródła danych:

• Transkrypcja rozmowy (Dataverse): gdy rozmowa toczy się w Copilot Studio, platforma rejestruje dziennik aktywności w postaci transkrypcji rozmowy w Dataverse. Narzędzie Agent Debugger pobiera te rekordy bezpośrednio, dzięki czemu każdy opublikowany agent zawierający dane z transkrypcji jest natychmiast dostępny.
• Zrzut ekranu z Copilot Studio (ZIP): Panel testowy Copilot Studio zawiera opcję Pobierz zrzut ekranu, która pozwala wyeksportować bieżącą rozmowę testową jako plik ZIP. Przesłanie tego pliku do programu Agent Debugger pozwala uzyskać pełny podgląd analizy bez konieczności nawiązywania połączenia z Dataverse. Ta metoda przydaje się do debugowania rozmów przedprodukcyjnych, odtwarzania problemów w trybie offline lub udostępniania sesji, w której wystąpił błąd, współpracownikowi.

Oba źródła danych zasilają ten sam interfejs analityczny. Panele, szczegóły kroków i wizualizacje są takie same niezależnie od sposobu ładowania danych.

Wymagania wstępne

Aby korzystać z Agent Debugger, upewnij się, że spełnione są następujące wymagania:

• Agent jest obecny w Inwentarzu agenta i ma zarejestrowany przynajmniej jeden zapis rozmowy na jego stronie. Można to sprawdzić, otwierając widok listy „Agent Inventory”, wybierając agenta, a następnie klikając Pokaż więcej, aby rozwinąć dodatkowe pola. Pole Czy transkrypt jest dostępny musi być ustawione na Tak. Synchronizacja Inwentarza Agenta automatycznie ustawia to pole, gdy w Dataverse istnieje przynajmniej jeden transkrypt rozmowy dla agenta.
• Zalogowany użytkownik posiada rolę bezpieczeństwa CSK – administrator lub administrator systemu w środowisku zestawu.
• Zalogowany użytkownik posiada uprawnienia Odczytu do tabel conversationtranscripts, bot i botcomponents w środowisku docelowym.

Wybierz konwersację

Gdy otwierasz Agent Debugger, pasek filtrujący dostarcza kontrolki potrzebne do zlokalizowania rozmowy do analizy.

Po wybraniu identyfikatora rozmowy dostępna staje się funkcja Analiza. Wybierz go, aby otworzyć widok analizy.

Prześlij zdjęcie z Copilot Studio

Zakładka Prześlij migawkę stanowi alternatywny punkt dostępu, który nie wymaga dostępu do Dataverse. Zamiast wybierać rozmowę na żywo z rozwijanych list, przesyłasz plik snapshot ZIP pobrany z panelu testowego Copilot Studio.

Aby pobrać migawkę z programu Copilot Studio:

1. Otwórz swojego agenta w Copilot Studio i przejdź do panelu Przetestuj swojego agenta.
2. Uruchom lub sprawdź rozmowę.
3. Wybierz opcję Pobierz migawkę na pasku narzędzi panelu testowego.

Copilot Studio pobiera plik .zip, który zawiera:

• dialog.json: Wszystkie aktywności Bot Framework do rozmowy (wymagane).
• botContent.yml: Pełne definicje składników i przepływów agenta, wykorzystywane do rozpoznawania nazw etapów (opcjonalnie; w przypadku braku tych danych wyświetlane są surowe nazwy schematów).

Aby przesłać migawkę do Agent Debugger:

1. Przełącz się na zakładkę Prześlij migawkę w nagłówku Agent Debugger.
2. Przeciągnij i upuść plik .zip na obszar docelowy lub wybierz opcję, aby go wyszukać.

Agent Debugger przeprowadza weryfikację poprawności pliku ZIP, rozpakowuje pliki i otwiera okno analizy. Nie jest wymagany wybór środowiska, agenta ani rozmowy. Wszystkie ogólne metryki informacyjne są wyprowadzane z przesłanego pliku.

Z trybu „Prześlij migawkę” należy korzystać, gdy:

• Debuguj rozmowę, która miała miejsce w panelu testowym przed publikacją agenta.
• Przeanalizuj rozmowę z miejsca, w którym nie możesz się zweryfikować.
• Odtwarzanie problemów offline lub udostępnianie nieudanej sesji współpracownikowi bez udzielenia dostępu do Dataverse.
• Walidacja zachowania agentów w lokalnym środowisku deweloperskim.

Analiza konwersacji

Widok analizy otwiera się po wybraniu Analizuj lub przesłaniu migawki. Zawiera on u góry wiersz podsumowujący Informacje ogólne, zwijaną sekcję analizy z czterema panelami (Ścieżka wykonania, Oś czasu wydajności, Szczegóły agenta oraz Zalecenia), a także układ z dwoma panelami, w którym obok panelu Informacje debugowania wyświetlany jest Wersja zapoznawcza rozmowy.

Informacje ogólne

Wiersz ogólnych informacji pokazuje podsumowanie kafelków metrycznych dla rozmowy.

Po załadowaniu aktywnego agenta w nagłówku zawierającym ogólne informacje pojawia się link Otwórz agenta. Kliknięcie tego linku powoduje otwarcie strony konfiguracji agenta w Copilot Studio.

Ścieżka wykonania

Ścieżka wykonania generuje pełną kolejność wykonania we wszystkich turach rozmowy jako skierowany diagram przepływu. Kroki płyną od lewej do prawej w kolejności wykonania. Przerywane pionowe linie wyznaczają granice zakrętów, a każda wiadomość użytkownika rozpoczyna nową sekcję. Etykiety tur pojawiają się na górze każdej sekcji. Wybranie etykiety zwrotu powoduje przewinięcie Wersji zapoznawczej rozmowy do tej wiadomości.

Każdy typ kroku ma przypisany inny kolor, a legenda umieszczona na dole diagramu przyporządkowuje kolory do kategorii kroków, takich jak: Temat, Wiedza, Narzędzie, Łącznik, Przepływ, Kod, MCP i Połączony agent. Każdy węzeł pokazuje nazwę kroku oraz czas trwania wykonania. Nieudane kroki są podświetlone na czerwono. Połączone agenty są wyświetlane jako pola kontenerowe, w których zgrupowane są wykonane przez nie podległe kroki.

Harmonogram realizacji

Na wykresie wydajności przedstawiono wykres kaskadowy pokazujący czasy wykonania poszczególnych kroków pogrupowane według tur rozmowy. Paski krokowe są skalowane w zależności od całkowitego czasu trwania zwrotu, aby uwidocznić względną synchronizację. Oznaczenia kolorystyczne odpowiadają legendzie ścieżki wykonania, a etapy, które zakończyły się niepowodzeniem, są zaznaczone na czerwono.

Panel posiada następujące funkcje:

• Przyciski Rozwiń/Zwiń wszystko powodują jednoczesne rozwijanie lub zwijanie wszystkich sekcji. Każda sekcja jest również składana osobno.
• Statystyki dla poszczególnych okrążeń pokazują liczbę kroków, nazwę najwolniejszego kroku i czas jego trwania oraz liczbę niepowodzeń.
• W górnej części ekranu znajduje się podsumowanie ogólne, w którym widoczna jest łączna liczba kroków, łączny czas trwania, najwolniejszy krok w całej rozmowie oraz łączna liczba niepowodzeń.
• Kroki trwające dłużej niż 10 sekund są oznaczane wskaźnikiem ostrzegawczym.

Szczegóły agenta

W panelu szczegółów agenta wyświetlana jest pełna konfiguracja agenta w stanie, w jakim znajdowała się w momencie analizy rozmowy. Informacje są zorganizowane w sześć zakładek.

Rekomendacje

Panel rekomendacji automatycznie wykrywa problemy pojawiające się w rozmowie i wyświetla je w postaci kart z możliwością podjęcia działań, wraz z oceną poziomu ważności.

Wykrywa się następujące typy problemów:

Każda karta z zaleceniem zawiera ikonę i kolor wskazujące poziom ważności, znacznik kategorii, tytuł i opis wykrytego problemu, sugestię dotyczącą sposobu zbadania lub rozwiązania problemu oraz przycisk Przejdź do, który przewija podgląd rozmowy do odpowiedniej wiadomości użytkownika. Gdy nie wykryto żadnych problemów, panel wyświetla komunikat o stanie pustym.

Wersja zapoznawcza rozmowy

W panelu wersji zapoznawczej rozmowy wyświetlana jest pełna treść rozmowy w takiej postaci, w jakiej była widoczna dla użytkownika, łącznie z dymkami wiadomości bota i użytkownika, kartami adaptacyjnymi wyświetlanymi bezpośrednio w tekście, sugestiami działań oraz promptami o opinię.

Wybranie dymku z komunikatem użytkownika powoduje załadowanie czynności z tej tury do panelu Informacje debugowania. Wybrana wiadomość jest podświetlona, dzięki czemu możesz śledzić, która tura jest aktywna. Panel można przewijać niezależnie. Wybranie opcji Wyświetl JSON w nagłówku wersji zapoznawczej rozmowy powoduje otwarcie okna dialogowego z pełną transkrypcją w formacie JSON.

Informacje o debugowaniu

Panel informacji debugowania wyświetla szczegóły na poziomie poszczególnych kroków dla wybranej rundy komunikatów użytkownika. Panel zawiera listę kroków po lewej stronie oraz widok szczegółowy kroku, który otwiera się po zaznaczeniu danego kroku.

Lista kroków zawiera wszystkie kroki orkiestratora wykonane w wybranej turze wraz z ikoną i kolorem wskazującym typ kroku, nazwą kroku (w miarę możliwości przekształconą na przyjazną nazwę wyświetlaną), czasem trwania wykonania oraz wskaźnikiem powodzenia lub niepowodzenia. Kroki przypisane do danego agenta są zgrupowane w rozwijanej karcie kontenera, na której widoczna jest nazwa agenta oraz łączny czas wykonania. Przycisk Pobierz szczegóły podłączonego agenta na kontenerze powoduje wyświetlenie pełnego zapisu rozmowy agenta podrzędnego na żądanie.

Obsługiwane są następujące typy kroków:

Wybranie etapu powoduje otwarcie panelu szczegółów zawierającego następujące sekcje, wyświetlane w przypadku, gdy dane są zawarte w transkrypcji:

• Proces myślowy: tekst rozumowania orkiestratora zapisany przed wywołaniem kroku. Pokazuje, jak model nazwał ten etap i czego od niego oczekiwał.
• Typ kroku: Etykieta tajna dla tego kroku.
• Argumenty: Składany widok drzewa JSON z parametrami wejściowymi przekazanymi do kroku. Zawiera opcję kopiowania JSON do zgłaszania zgłoszeń do wsparcia.
• Obserwacja: Wartość wyjściowa lub zwrotna z kroku. Również wyświetlane jako składane drzewo JSON z wsparciem dla kopiowania.
• Podgląd kodu: w przypadku kroków kodu w Pythonie kod źródłowy jest wyświetlany z podświetleniem składni.
• Użycie tokenów: Liczba tokenów promptu, liczba tokenów ukończenia oraz suma dla kroku, wraz z nazwą modelu.
• Źródła wiedzy: Źródła, które zostały przeszukane, wyniki zwrócone (wyjście) oraz źródła faktycznie cytowane w ostatecznej odpowiedzi. Każdy wpis zawiera nazwę źródła, typ, adres URL tam, gdzie jest dostępny, oraz link do otwarcia źródła.
• Informacje o serwerze MCP: W przypadku kroków MCP pokazuje wersję protokołu serwera, zadeklarowane możliwości oraz listę narzędzi udostępnionych przez serwer podczas inicjalizacji.
• Informacje o błędzie: gdy krok się nie powiódł, pokazuje kod błędu, komunikat o błędzie oraz (dla bloków Odpowiedzialnych AI) kategorię bezpieczeństwa treści, która wywołała filtr.
• Karty adaptacyjne: gdy krok generuje odpowiedź karty adaptacyjnej, karta jest renderowana w linii w panelu szczegółów dokładnie tak, jak użytkownik by ją widział.

Transkrypcja JSON

Gdy wybierzesz Zobacz JSON w nagłówku podglądu rozmowy, otwiera się okno oka z pełnymi aktywnościami surowego zapisu z podświetleniem składni, pełnotekstowym wyszukiwaniem w drzewie JSON oraz opcją kopiowania do schowka dla całego ładunku.

Z tego widoku należy korzystać, gdy:

• Należy sprawdzić typ zdarzenia, który nie jest wyświetlany w panelu Informacje debugowania.
• Chcesz skopiować określone pola z zgłoszenia do pomocy technicznej.
• Zajmujesz się badaniem nieoczekiwanych zachowań w przeanalizowanych widokach.

Rozwiązywanie problemów

Poniższe sekcje opisują typowe problemy i sposoby ich rozwiązania.

Agent nie pojawia się w rozwijanym menu „Środowisko” ani „Agent”

Agent nie jest zsynchronizowany z modułem „Agent Inventory” lub nie ma żadnych transkrypcji rozmów.

Aby rozwiązać ten problem:

1. Przeprowadź ręczną synchronizację zasobów agenta dla danego środowiska.
2. Sprawdź, czy rekord agenta istnieje w tabeli „Szczegóły agenta” w Dataverse.
3. Sprawdź, czy w rekordzie w kolumnie Czy dostępny jest transkrypt? jest zaznaczona opcja Tak. Synchronizacja ustawia tę wartość, jeśli istnieje co najmniej jeden transkrypt.

Więcej informacji można znaleźć w sekcji Monitorowanie agentów za pomocą funkcji Agent Inventory w agentach funkcji Copilot.

W rozwijanym menu nie ma identyfikatora rozmowy

Aby zapewnić wydajność, menu rozwijane wstępnie ładuje tylko 50 najnowszych rozmów z aktywnego przedziału czasowego. Starsze transkrypcje nadal istnieją w Dataverse, ale domyślnie się nie pojawiają. Alternatywnie, transkrypcja może jeszcze nie być napisana, jeśli rozmowa właśnie się zakończyła.

Aby rozwiązać ten problem:

1. Wpisz identyfikator rozmowy bezpośrednio w polu Identyfikator rozmowy. Wpisanie tekstu powoduje przeprowadzenie pełnego wyszukiwania we wszystkich transkrypcjach dotyczących danego agenta, z pominięciem przedziału czasowego.
2. Jeśli zakres czasu jest wąski (na przykład Ostatnie 30 minut), powiększ go lub przełącz na niestandardowy zakres obejmujący datę rozmowy.
3. Jeśli rozmowa właśnie się zakończyła, odczekaj 35–40 minut, aż transkrypcja zostanie zapisana w Dataverse, a następnie odśwież stronę.

Przeprowadzono analizę obciążeń, ale w panelu informacji o debugowaniu nie wyświetlają się żadne kroki

Transkrypcja istnieje, ale zawiera wyłącznie operacje typu „wiadomość” i nie zawiera żadnych zdarzeń śledzenia diagnostycznego. Problem ten zwykle pojawia się, gdy rozmowa pochodzi z kanału, który nie emituje danych śledzenia, takich jak niektóre niestandardowe kanały lub starsze wersje schematu.

Aby rozwiązać ten problem:

1. Wybierz Zobacz JSON w nagłówku podglądu rozmowy, aby potwierdzić obecność aktywności.
2. Szukaj wpisów type: "trace" lub type: "event". Jeśli ich nie ma, kanał może nie emitować danych śladowych.

Dostęp odrzucony lub pusta strona przy ładowaniu

Brakuje ról lub uprawnień w jednym lub obu środowiskach.

Aby rozwiązać ten problem:

1. W środowisku zestawu należy upewnić się, że użytkownik posiada rolę CSK – administrator lub administrator systemu.
2. W środowisku docelowym upewnij się, że zalogowany użytkownik ma uprawnienia do odczytu w tabelach conversationtranscripts, bot i botcomponents.

Transkrypcje wydają się niekompletne (brakuje wczesnych wiadomości)

Długie rozmowy są podzielone na wiele rekordów Dataverse (limit 1 MB na rekord). Jeśli polityka przechowywania usuwa część zapisów, połączony wykaz wykazów ma luki.

Aby rozwiązać ten problem:

1. Dataverse domyślnie usuwa transkrypcje rozmów starsze niż 30 dni. Jeśli problemem jest okres przechowywania danych, zaktualizuj harmonogram zadania zbiorczego usuwania w Power Apps>Ustawienia>Ustawienia zaawansowane>Zarządzanie danymi>Zbiorcze usuwanie rekordów.
2. Jeśli przyczyną nie jest zatrzymanie danych, sprawdź, czy wszystkie rekordy transkrypcji tej rozmowy znajdują się w tabeli conversationtranscripts w Dataverse.

Kroki pokazują surowe nazwy schematów zamiast czytelnych nazw tematów

Wyszukiwanie w tabeli botcomponents nie powiodło się lub rekord składnika został usunięty.

Aby rozwiązać ten problem:

1. Należy sprawdzić, czy zalogowany użytkownik ma uprawnienia do odczytu tabeli botcomponents w środowisku docelowym.
2. Jeśli składnik został usunięty z programu Copilot Studio, nie ma pasującego rekordu, a program Agent Debugger powraca do surowej nazwy schematu, np. cr123_mytopic. Takie zachowanie jest oczekiwane przy usuniętych tematach lub działaniach.

Panel szczegółów agenta nie pokazuje danych

Pobieranie konfiguracji agenta nie powiodło się lub połączenie zalogowanego użytkownika nie ma uprawnień do odczytu tabel bot i botcomponents w środowisku docelowym.

Aby rozwiązać ten problem:

1. Sprawdź, czy odwołanie do połączenia, z którego korzysta aplikacja, ma uprawnienia do odczytu w tabelach bot i botcomponents.
2. Jeśli agent został usunięty lub jego publikacja została cofnięta po zarejestrowaniu rozmowy, jego rekordy konfiguracyjne mogą już nie istnieć. W tym przypadku panel Szczegóły agenta pozostaje pusty, ale panele transkrypcji i debugowania nadal działają bez ograniczeń.

Panel zaleceń nie wskazuje żadnych problemów, ale rozmowa nie doszła do skutku

Rekomendacje wynikają z wzorców w zdarzeniach śledzenia transkrypcji. Jeśli w transkrypcji brakuje danych śledzących lub jeśli awaria wystąpiła poza rozmową (na przykład w przypadku cichego przekroczenia limitu czasu połączenia sieciowego, którego transkrypcja nie rejestruje), system nie generuje żadnych zaleceń.

Aby rozwiązać ten problem:

1. Otwórz plik JSON z transkrypcją, aby znaleźć surowe dane dotyczące błędów, które nie zostały uwidocznione jako zalecenia.
2. Sprawdź ścieżkę wykonania pod kątem kroków oznaczonych na czerwono. Te kroki wskazują na awarie, które nie odpowiadają znanemu wzorcowi rekomendacji.

Informacje pokrewne

• Monitorowanie agentów przy użyciu spisu agentów w zestawie agentów funkcji Copilot Studio
• Konfiguracja agentów w zestawie agenta funkcji Copilot Studio
• Omówienie zestawu agentów funkcji Copilot