Debuguj agentów za pomocą Agent Inspector w Microsoft Foundry Toolkit

Narzędzie Agent Inspector w Microsoft Foundry Toolkit for Visual Studio Code umożliwia wysyłanie żądań do lokalnego agenta, inspekcję działania modelu i narzędzi oraz debugowanie kodu. Użyj go, aby zbadać nieoczekiwane odpowiedzi przed wdrożeniem zmiany.

Ten przepływ pracy jest przydatny w przypadku agentów hostowanych, które uruchamiają niestandardowy kod w usłudze Foundry Agent Service. Inspekcja na komputerze lokalnym pomaga analizować ten kod. Przed użyciem w środowisku produkcyjnym przetestuj również wdrożonego agenta przy użyciu jego tożsamości środowiska uruchomieniowego, konfiguracji i dostępu do sieci.

W tym artykule nawiążesz połączenie z agentem lokalnym, zbadasz żądanie i zapiszesz zdarzenia diagnostyczne. Ścieżka główna używa protokołu Responses. Dostępne widoki zależą od protokołu i diagnostyki udostępnianej przez serwer agenta.

Prerequisites

• Visual Studio Code z aktualnie publicznie dostępnym rozszerzeniem Foundry Toolkit. Zobacz Zainstaluj Foundry Toolkit.
• Projekt agenta lokalnego ze skonfigurowanymi zależnościami, konfiguracją modelu i poświadczeniami. Aby rozpocząć od przykładu, postępuj zgodnie z przewodnikiem Szybki start hostowanego agenta w ramach testowania lokalnego.
• Debugger wymagany przez Twój projekt. W przykładzie Python użyto rozszerzenia Python i debugpy. Inne języki i przykłady mają różne wymagania.

W przypadku istniejącego projektu narzędzia Foundry Toolkit Copilot mogą pomóc w przygotowaniu konfiguracji. Przejrzyj wygenerowane pliki i postępuj zgodnie z projektem README.md. Nie zamieniaj jego plików uruchamiania na konfigurację ogólną.

Połącz i debuguj

Uruchom serwer agenta przed nawiązaniem połączenia z Inspector. Użyj wygenerowanej konfiguracji uruchamiania projektu, aby dopasować serwer, katalog roboczy, interpreter i debuger.

1. Uruchom agenta z udokumentowaną konfiguracją debugowania. W przypadku przykładu hostowanego agenta Python wybierz pozycję Debug Local Agent HTTP Server i naciśnij klawisz F5.
2. Jeśli inspektor nie jest otwarty, wybierz pozycję Foundry Toolkit na pasku działań, a następnie Developer Tools>Build>Agent Inspector.
3. Sprawdź endpoint w nagłówku Inspector. Bieżący szkielet Python używa elementu http://localhost:8088. W przypadku innego portu serwera wybierz przycisk ołówka obok endpointu, wprowadź port i wybierz pozycję Połącz.
4. Upewnij się, że w nagłówku jest wyświetlana wartość Połączono. Inspektor automatycznie wykrywa protokół Responses lub Invocations, gdy punkt końcowy jest osiągalny.
5. Ustaw punkt przerwania w kodzie agenta i wyślij komunikat w Playground. Sprawdź zmienne po wstrzymaniu wykonywania, a następnie kontynuuj i przejrzyj odpowiedź.

Otwieranie samego inspektora nie uruchamia serwera ani nie dołącza debugera. Wygenerowana konfiguracja Python używa portu 5679 dla debugera i portu 8088 dla żądań HTTP agenta. Te porty są oddzielone od portów śledzenia OTLP.

Nawiązywanie połączenia z generycznym punktem końcowym Responses

Inspektor może nawiązać połączenie z lokalnym ogólnym punktem końcowym Responses bez pełnego interfejsu diagnostyki programowania. Możesz sprawdzić zdarzenia Responses wysyłane przez serwer, ale wykres przepływu pracy i jego widok wejścia i wyjścia nie są dostępne.

Pomyślne połączenie nie oznacza, że serwer dostarcza lokalizacje źródłowe, użycie tokenu lub rozumowanie.

Wysyłanie wywołania HTTP

Użyj wywołań HTTP, gdy agent akceptuje niestandardową treść żądania, a nie wiadomość konwersacyjną. Format żądania i protokół odpowiedzi serwera określają sposób wysyłania i wyświetlania wyniku przez inspektora.

1. Połącz się z uruchomionym serwerem wywołań HTTP. Inspektor wykrywa protokół automatycznie.
2. Wprowadź treść żądania wymaganą przez agenta. Jeśli serwer uwidacznia zgodną specyfikację interfejsu OpenAPI, Inspector może uzupełnić przykład. Przejrzyj go przed wysłaniem lub postępuj zgodnie z formatem żądania z przykładu, jeśli nie jest dostępny żaden przykład.
3. Wybierz koło zębate Ustawienia żądania obok danych wejściowych, aby ustawić Content-Type i Accept zgodnie z wymaganiami serwera. Na przykład użyj polecenia application/json dla treści JSON i text/event-stream gdy serwer obsługuje odpowiedź strumieniową.
4. Wybierz pozycję Wyślij i sprawdź stan odpowiedzi i treść.
5. Przełączaj się między Preview dla sformatowanych danych wyjściowych i Raw dla odpowiedzi źródłowej. Okienko szczegółów zawiera również WE/WY i wywołania LLM. Szczegóły modelu, narzędzia i tokenu zależą od rozpoznanych zdarzeń serwera, więc nie każda odpowiedź wypełnia każdą kartę.

Inspektor obsługuje normalną odpowiedź HTTP, strumień zdarzeń wysyłanych przez serwer lub asynchroniczną odpowiedź. W przypadku odpowiedzi asynchronicznej 202 Accepted sprawdza stan wywołania do momentu ukończenia lub niepowodzenia. Wybranie formatu odpowiedzi nie powoduje dodania obsługi przesyłania strumieniowego ani obsługi asynchronicznej na serwerze.

W przypadku odpowiedzi przesyłania strumieniowego Stop rozłącza strumień klienta. W przypadku wywołania sondowanego Anuluj wysyła żądanie anulowania do serwera. Żadna akcja nie gwarantuje, że proces agenta lub operacja narzędzia zewnętrznego zostały zatrzymane.

Ten widok nie jest klientem protokołu WebSocket. Przykłady protokołu Activity Protocol korzystają z innego środowiska testowego. Zobacz Wybierz inny protokół lub przykład, aby uzyskać odpowiednią lokalną ścieżkę testowania.

Używanie Inspektora

Zacznij od żądania, które pozwala sprawdzić działanie, które chcesz zrozumieć. Na przykład w przypadku narzędzia do obsługi pogody poproś o informacje, które wymagają tego narzędzia, a nie ogólną odpowiedź, którą model może wygenerować bez niego.

1. Wyślij żądanie w Playground i przejrzyj odpowiedź strumieniową.
2. Użyj kart szczegółów, aby znaleźć powolną lub nieudaną operację.
3. Sprawdź odpowiednie zdarzenie lub wywołanie narzędzia, zmień kod lub konfigurację i powtórz żądanie.

Naciśnij klawisz Enter , aby wysłać lub klawisz Shift+Enter , aby dodać nowy wiersz. Aby przywołać wcześniejsze żądanie, umieść kursor na początku danych wejściowych i naciśnij strzałkę w górę. Naciśnij klawisz strzałki w dół na końcu, aby przejść do nowszych żądań i wrócić do niewysłanej wersji roboczej.

Przed wysłaniem żądania można edytować odwołane żądanie. Historia danych wejściowych jest wygodą w obszarze Inspector, a nie trwałym magazynem zapisanych monitów.

Stopka odpowiedzi zawiera informacje dotyczące modelu, czasu trwania, użycia tokenu i sygnatury czasowej. Tekst rozumowania i podsumowania rozumowania są wyświetlane w osobnych zwijanych sekcjach, gdy agent je emituje. Inspektor nie generuje brakujących przyczyn ani nie ujawnia informacji, które dostawca modelu nie zwraca.

Sprawdź narzędzia i uprawnienia

Użyj narzędzi , aby sprawdzić, czy agent nazwał oczekiwane narzędzie oczekiwanymi argumentami i otrzymał wynik. Pomyślna odpowiedź modelu nie dowodzi, że uruchomiono narzędzie. Jeśli kod używa mocka, wyświetlany wynik jest nadal wynikiem mocka.

Gdy odpowiedź zostanie wstrzymana dla zatwierdzenia protokołu MCP (Model Context Protocol) lub zgody protokołu OAuth, oczekujące żądania pojawiają się powyżej danych wejściowych komunikatu. Przyznaj tylko dostęp, na który zamierzasz zezwolić.

W przypadku wywołania narzędzia MCP wybierz pozycję Pokaż argumenty, przejrzyj dane wejściowe, a następnie wybierz pozycję Zatwierdź lub Odmów. Zatwierdź wszystkie i Odmów wszystkie mają zastosowanie do oczekujących żądań, a nie do stałej polityki zatwierdzania narzędzi.

Aby uzyskać zgodę na OAuth, wykonaj zarówno autoryzację w przeglądarce, jak i potwierdzenie w Inspectorze:

1. Wybierz pozycję Otwórz zgodę dla oczekującego żądania.
2. Ukończ autoryzację w przeglądarce, wróć do pozycji Inspektor i wybierz pozycję Zgoda gotowa. Aby odrzucić autoryzację, wybierz pozycję Anuluj zamiast tego.
3. Rozpatrz pozostałe prośby o zgodę. Użyj opcji Wszystko gotowe, jeśli jest dostępna, tylko po zakończeniu autoryzacji dla wszystkich otwartych żądań.

Otwarcie strony zgody nie powoduje wznowienia żądania. Inspektor czeka na decyzję dotyczącą każdej oczekującej zgody przed ponownym sprawdzeniem serwera. Żądania mogą pojawić się ponownie, jeśli serwer nadal potrzebuje autoryzacji.

Sprawdź wynik następnego narzędzia, nie tylko zatwierdzenie, aby potwierdzić ukończenie. Aby uzyskać informacje o konfiguracji połączenia i uwierzytelniania, zobacz Katalog narzędzi. Nie zmieniaj poświadczeń narzędzia ani uprawnień wyłącznie po to, aby usunąć błąd diagnostyczny.

Sprawdź przepływy pracy i kod źródłowy

W przypadku obsługiwanych przepływów pracy Microsoft Agent Framework serwer deweloperski może zapewnić diagnostykę przepływu pracy i lokalizacje źródłowe. Inspektor używa tych informacji do wyświetlania wykresu wykonywania i pomaga przejść do kodu.

1. Wybierz węzeł przepływu pracy, aby sprawdzić dostępne dane wejściowe i wyjściowe.
2. Kliknij dwukrotnie węzeł, aby otworzyć jego lokalizację źródłową.
3. Ustaw punkt przerwania i powtórz żądanie, aby sprawdzić operację w debugerze.

Możesz przetestować przepływy pracy LangGraph w playground, ale wizualizacja przepływu pracy nie jest dla nich obsługiwana. Serwer bez metadanych przepływu pracy może nadal zwracać przydatne zdarzenia odpowiedzi.

Zbadaj problemy za pomocą Copilot

Użyj akcji dotyczących błędów w obszarze Zdarzenia, aby przygotować ukierunkowane żądanie dla GitHub Copilot zamiast kopiować całą konwersację.

1. Znajdź zdarzenie, które zakończyło się niepowodzeniem, i przejrzyj jego szczegóły dotyczące poufnej zawartości przed ich udostępnieniem.
2. Wybierz pozycję Napraw obok zdarzenia, które zakończyło się niepowodzeniem, aby przygotować monit dotyczący tego niepowodzenia. W przypadku kilku niepowodzeń zawęź listę z filtrami wyszukiwania i kategorii, a następnie wybierz pozycję Rozwiąż przy użyciu Copilot. Ta akcja obejmuje widoczne awarie.
3. Przed wysłaniem go przejrzyj przygotowany monit w usłudze GitHub Copilot Chat. Przejrzyj proponowane zmiany, a następnie ponownie uruchom oryginalne żądanie agenta, aby potwierdzić wynik.

Te akcje nie wymagają kolektora OTLP. Przygotowanie monitu diagnostycznego nie naprawia agenta ani nie uruchamia ponownie operacji, która zakończyła się niepowodzeniem.

Zapisz zdarzenia diagnostyczne

Zapisz migawkę zdarzenia, aby porównać błąd z późniejszym uruchomieniem lub udostępnić ukierunkowane odtworzenie problemu.

1. W obszarze Zdarzenia zawęź listę za pomocą pola wyszukiwania i filtra kategorii.
2. Wybierz pozycję Kopiuj widoczne zdarzenia , aby skopiować przefiltrowane zdarzenia jako JSONL. Alternatywnie wybierz pozycję Pobierz widoczne zdarzenia , aby otworzyć eksport w programie VS Code.
3. W przypadku otwartego wyeksportowanego pliku przed zamknięciem dokumentu użyj polecenia Plik>, aby zapisać kopię w lokalizacji, którą kontrolujesz. Otwarty plik eksportu jest plikiem tymczasowym, a nie trwale pobranym plikiem.

Migawka zawiera zdarzenia widoczne w momencie wybrania akcji, a nie przyszłe zdarzenia z uruchomionego agenta. Nie zapisuje wersji agenta, wdrażania kodu ani tworzenia historii śledzenia chmury.

Rozpocznij nową konwersację

Wybierz pozycję Wyczyść czat , aby rozpocząć nową konwersację i wyczyścić stan czatu, zdarzenia i szczegóły. Wyeksportuj wszystkie potrzebne zdarzenia diagnostyczne. Odświeżenie tego samego połączonego agenta zachowuje stan inspekcji, podczas gdy zmiana agentów czyści nieaktualny stan.

W przypadku odpowiedzi funkcja Clear Chat jest wyłączona, gdy odpowiedź aktywnie przesyła strumieniowo. Pozostaje ona dostępna, gdy tura zostanie wstrzymana w celu zatwierdzenia lub wyrażenia zgody. Nie jest to ogólne polecenie, aby zatrzymać Twojego agenta.

Nie polegaj na stanie inspektora lokalnego jako trwałe archiwum konwersacji. Serwer jest właścicielem trwałości konwersacji, która może różnić się między lokalnym programowaniem a wdrożonym hostowanym agentem. Narzędzie Clearing Inspector nie usuwa śladów już zebranych lokalnie ani przechowywanych w usłudze Application Insights.

Czym różnią się Inspektor i śledzenie

Inspektor komunikuje się z serwerem lokalnym za pośrednictwem protokołu HTTP i przesyła strumieniowo zdarzenia odpowiedzi. Zgodny serwer programistyczny udostępnia również oddzielny strumień diagnostyczny na potrzeby szczegółów przepływu pracy i nawigacji źródłowej. Debuger dołącza niezależnie do uruchomionego procesu.

Te diagnostyki na żywo nie wymagają lokalnego modułu zbierającego OTLP. Karta Ślady inspektora otwiera oddzielną przeglądarkę śledzenia. Nie przekształca zdarzeń protokołu w przechowywane spany OpenTelemetry.

Aby zebrać span(y) na potrzeby późniejszej analizy, skonfiguruj śledzenie lokalne. W przypadku wdrożonych agentów użyj śladów hosted-agent.

Po przetestowaniu lokalnym wdróż hostowanego agenta. Przetestuj go oddzielnie, ponieważ jego tożsamość, środowisko i dostęp sieciowy różnią się od procesu uruchomionego lokalnie.

Troubleshooting

Treści powiązane

• Zbieraj i sprawdzaj ślady w Foundry Toolkit.
• Twórz przepływy pracy hostowanego agenta w programie VS Code.
• Uruchom inspektora agenta opartego na przeglądarce przy użyciu Azure Developer CLI.