Szybki start: śledź swojego hostowanego agenta

Note

Śledzenie jest obecnie dostępne w wersji zapoznawczej.

W tym przewodniku Szybki start wyświetlisz ślady end-to-end dla hostowanego agenta wdrożonego w sekcji Wdrażanie pierwszego hostowanego agenta. Wywołujesz swojego agenta, aby generować dane śledzenia i przeglądać ślady w portalu Foundry.

Biblioteki hosta (azure-ai-agentserver-responses i azure-ai-agentserver-invocations) płynnie integrują dystrybucję Microsoft OpenTelemetry, która udostępnia gotową instrumentację dla Microsoft Agent Framework i LangChain oraz eksportuje ślady do usługi Application Insights. Ponadto usługa Foundry Agent Service automatycznie generuje po stronie serwera telemetrię dotyczącą wywołań agenta — bez konieczności wprowadzania zmian w kodzie.

Śledzenie zapewnia wgląd w sposób, w jaki agent obsługuje każde żądanie, dzięki czemu można debugować problemy, monitorować opóźnienia i rozumieć zachowanie agenta przed udostępnieniem zmian użytkownikom.

Prerequisites

Przed rozpoczęciem potrzebne są następujące elementy:

  • Wdrożony hostowany agent, który można wywoływać, z przewodnika Szybki start Wdróż pierwszego hostowanego agenta, oraz katalog projektu azd, który został utworzony w ramach tego przewodnika Szybki start.

  • Rola Użytkownika usługi Foundry w zasobie Foundry.

  • Aby użyć ścieżki interfejsu użytkownika, uzyskaj dostęp do portalu Foundry. Informacje o ścieżce azd znajdują się w poniższych wymaganiach.

  • Azure interfejs wiersza polecenia dewelopera (azd) 1.27.1 lub nowszy z azd microsoft.foundry rozszerzeniem:

    azd ext install microsoft.foundry

  • Uwierzytelniona sesja azd . Sprawdź swój status za pomocą azd auth status, a jeśli nie jesteś zalogowany, uruchom azd auth login.

    Important

    Niedawno zmieniono nazwy ról RBAC w usłudze Foundry. Użytkownik Foundry, właściciel Foundry, właściciel konta Foundry i menedżer projektu Foundry były wcześniej nazywane odpowiednio użytkownikiem Azure AI, właścicielem Azure AI, właścicielem konta Azure AI i menedżerem projektu Azure AI. Poprzednie nazwy mogą być nadal widoczne w niektórych miejscach, podczas gdy zmiana nazwy jest wdrażana. Identyfikatory ról i uprawnienia podstawowe są niezmienione przez zmianę nazwy.

  • Zasób usługi Application Insights Azure Monitor połączony z projektem Foundry. Aby ją skonfigurować, zobacz Konfigurowanie śledzenia w rozwiązaniu Microsoft Foundry.

  • Rola czytelnika Log Analytics w zasobie usługi Application Insights połączonym z projektem. Jeśli bazowe tabele Log Analytics są chronione, przypisz również rolę Czytelnik uprzywilejowanych danych monitorowania.

Krok 1. Wywoływanie agenta

Generuj dane śledzenia, wysyłając żądanie do wdrożonego agenta.

azd W katalogu projektu wyślij monit testowy:

azd ai agent invoke "Summarize the benefits of distributed tracing for AI agents."

Powinna zostać wyświetlona odpowiedź w ciągu kilku sekund.

Każde wywołanie generuje pełny ślad. Aby uzyskać bogatsze ślady, wysyłaj monity powodujące wywołania narzędzi lub rozumowanie wieloetapowe.

Krok 2. Wyświetlanie śladów w portalu Foundry

Ślady można przeglądać w portalu Foundry po wywołaniu.

  1. W portalu Foundry otwórz projekt.
  2. W obszarze nawigacji po lewej stronie wybierz pozycję Agenci.
  3. W górnej części wybierz pozycję Ślady.
  4. Znajdź ślad na liście. Możesz wyszukiwać według identyfikatora śledzenia, identyfikatora odpowiedzi lub filtrować według zakresu czasu.

Trajektoria

Zrzut ekranu przedstawiający widok wodospadu śledzenia w portalu Foundry, pokazujący spany dla invoke_agent, uzupełnień czatu i żądań tokenów, z danymi wejściowymi/wyjściowymi po prawej stronie.

Widok użytkownika

Animacja widoku śladów użytkownika w portalu Foundry.

Wskazówka

Jeśli agent używa Microsoft Agent Framework, automatycznie generuje własne spany OpenTelemetry. Te spany pojawiają się jako elementy podrzędne spanów warstwy hostującej, co daje pełne drzewo śledzenia — od żądania HTTP przez orkiestrację agenta po poszczególne wywołania narzędzi i interakcje z LLM.

Uprzątnij zasoby

Dane śledzenia są przechowywane w usłudze Application Insights i są zgodne z ustawieniami przechowywania danych obszaru roboczego. Ten przewodnik Szybki start nie tworzy żadnych dodatkowych zasobów. Aby wyczyścić poprzedni przewodnik Szybki start, uruchom polecenie azd down z katalogu projektu agenta. To, co usuwa polecenie, zależy od tego, czy inicjowanie zostało utworzone, czy ponownie użyte w projekcie Foundry.

Warning

Jeśli bieżące azd środowisko utworzyło projekt Foundry, azd down trwale usunie grupę zasobów projektu i wszystko w nim. Jeśli podczas inicjowania wybrano istniejący projekt, azd down pozostawi projekt, jego grupę zasobów, hostowanego agenta i inne zasoby szybkiego startu. Aby usunąć zasoby, których już nie potrzebujesz z istniejącego projektu, usuń je oddzielnie.

Troubleshooting

Kwestia Rozwiązanie
Gdy nie używasz agentów hostowanych przez usługę Foundry, ślady nie są wyświetlane Ten przewodnik Szybki start obejmuje tylko hostowanych agentów. Aby uzyskać informacje o agentach śledzenia hostowanych poza usługą Foundry, zobacz Rejestrowanie agenta zewnętrznego.
Po uruchomieniu agenta nie pojawiają się żadne ślady Upewnij się, że usługa Application Insights jest połączona z projektem Foundry. Jeśli nie jest włączona, zobacz Konfigurowanie śledzenia w usłudze Microsoft Foundry. Sprawdź, czy agent odpowiedział pomyślnie za pomocą polecenia azd ai agent invoke.
Ślady są wyświetlane, ale brakuje atrybutów danych wejściowych/wyjściowych Włącz nagrywanie zawartości, ustawiając zmienną środowiskową OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true w konfiguracji agenta.
AuthorizationFailed podczas przeglądania śladów Potrzebna jest rola Log Analytics Reader w zasobie Application Insights. Jeśli tabele są chronione, przypisz również rolę Privileged Monitoring Data Reader.
Ślady są wyświetlane, ale brakuje zakresów wywołań narzędzi Sprawdź, czy agent definiuje narzędzia, a model wywołuje je podczas żądania. Jeśli używasz platformy Microsoft Agent Framework, upewnij się, że narzędzia są zarejestrowane w konstruktorze Agent za pomocą parametru tools . Zobacz Dodawanie narzędzi do agenta.
AuthenticationError lub DefaultAzureCredential niepowodzenie Odśwież poświadczenia za pomocą azd auth logout, a następnie azd auth login.

Czego się nauczyłeś

W ramach tego szybkiego przewodnika wykonasz następujące czynności:

  • Okazało się, że biblioteki hostujące integrują dystrybucję Microsoft OpenTelemetry, aby zapewnić gotową instrumentację.
  • Wywołano wdrożonego agenta w celu wygenerowania danych śledzenia.
  • Wyświetlane kompleksowe ślady w portalu Foundry.

Następne kroki

Konfigurowanie śledzenia w Microsoft Foundry

Treści powiązane

  • Last updated on