Koncepcje obserwowalności Agent 365

Ten artykuł wyjaśnia model danych stojący za obserwowalnością Agent 365 – co emitują agenty telemetryczne, kto może emitować telemetrię, gdzie jest ona przekazywana oraz jakie obowiązują limity. Te koncepcje mają zastosowanie do każdej ścieżki integracji: Microsoft OpenTelemetry Distro, Zestaw SDK agenta 365 oraz bezpośredniego OTel.

Notatka

Szczegóły na poziomie protokołu – trasy URL w sekcji Autoryzacja, kody błędów HTTP w sekcji Limity i warunki odrzucenia oraz limity wielkości i częstotliwości na każde żądanie – mają zastosowanie wyłącznie do bezpośredniej ścieżki OTel. SDK i Distro upraszczają te szczegóły za Ciebie. Pozostała część artykułu (glosariusz, przepływ danych, modele tożsamości, zakresy, warunki odrzucenia, gdzie pojawiają się dane) dotyczy każdej ścieżki.

Wybierz swoją ścieżkę integracji

Trzy ścieżki emitują ten sam model danych span do Agent 365. Wybierz jeden:

  • Microsoft OpenTelemetry Distro - zalecana dla nowych integracji. Ujednolicony zestaw SDK do monitorowania obejmujący Agent 365, Microsoft Foundry, Azure Monitor i inne rozwiązania.
  • Agent 365 SDK (zestaw SDK wglądu) – poprzedni SDK. Zestaw SDK nadal działa bez zmian niezgodnych wstecz, ale nie jest już zalecaną ścieżką dla nowych integracji; nadchodzą wytyczne dotyczące migracji dla obecnych użytkowników SDK.
  • Direct OTel – surowa ścieżka OTLP/HTTP. Używaj go tylko wtedy, gdy masz już skonfigurowany potok OpenTelemetry, twoja struktura agenta nie może korzystać z zestawu SDK Agenta 365 lub twój agent jest w języku, którego SDK jeszcze nie obsługuje (np. Java).

Bez względu na wybraną ścieżkę, model danych, modele tożsamości, zakresy, limity i powierzchnie poniżej opisane poniżej mają zastosowanie.

Glosariusz

  • Identyfikator aplikacji (appId): Identyfikator aplikacji nadany podczas rejestracji aplikacji Microsoft Entra lub tożsamości agenta Identyfikator agenta Microsoft Entra.
    • Równe OAuth client_id, a nie ID obiektu Microsoft Entra.
    • W całej dokumentacji terminy „agent id” i „blueprint id” są równoznaczne z appId.
  • Konwersacja: Logiczna nitka interakcji z agentami, taka jak wątek czatu Teams.
    • Zidentyfikowane na podstawie gen_ai.conversation.id.
    • Główny klucz sprzężenia dla uruchomienia.
  • Kanał: kontekst działania, w którym agent jest uruchamiany: msteams, outlook, web i tak dalej.
  • Przebieg: Jedna wiadomość od użytkownika, jedna odpowiedź agenta. Modelowane jako drzewo OTel span współdzielonych traceId.

Jak to działa

Aby uzyskać przegląd Agenta 365 oraz dowiedzieć się, gdzie trafia telemetria, zobacz Przegląd Microsoft Agent 365.

Wysyłasz telemetrię jako dane śledzenia OpenTelemetry:

  • Drzewo span opisujące jedno wywołanie (jedna wiadomość użytkownika wchodząca, jedna odpowiedź agenta wychodząca).
  • Każdy span opisuje pojedynczy krok – wywołanie agenta najwyższego poziomu, wywołanie LLM, wywołanie narzędzia lub udzielenie ostatecznej odpowiedzi.

Przepływ danych

   Your agent code

        |
        v

   +---------------+
   | OTel SDK or   |
   | raw HTTP      |
   +---------------+

        |
        v

   POST /traces  agent365.svc.cloud.microsoft

        |
        v

  +-------------------------------------+
  | Microsoft Defender                  |
  |   (CloudAppEvents table             |
  |    in advanced hunting)             |
  |                                     |
  | Microsoft Purview                   |
  |                                     |
  | Microsoft 365 admin center          |
  |   (agent inventory and              |
  |    security views)                  |
  +-------------------------------------+

Modele tożsamości

Pełne wyjaśnienie modeli tożsamości agentów (standardowa rejestracja aplikacji Microsoft Entra vs. plan tożsamości agenta Identyfikator agenta Microsoft Entra, w tym współpracowników AI), zobacz: Rozpocznij rozwój Agenta 365. Wybrany model tożsamości decyduje o tym, który przepływ uwierzytelniania i punkt końcowy zostaną użyte.

Jeśli agent nie ma rejestracji w Microsoft Entra, nie może bezpośrednio korzystać z tych ścieżek. Zidentyfikuj agenta za pomocą alternatywnych atrybutów ID (patrz referencja atrybutów) i skontaktuj się z zespołem Agenta 365 w sprawie odpowiedniej ścieżki wejścia.

Uwierzytelnianie

Uwierzytelnianie rozgałęzia się w zależności od tego, czy usługa uwierzytelnia się sama, czy w imieniu użytkownika. To odgałęzienie określa przepływ OAuth, roszczenie tokena, które niesie uprawnienia, oraz trasę URL.

  • Usługa uwierzytelnia się sama: brak zalogowanego użytkownika – działanie autonomiczne, zaplanowane lub sterowane zdarzeniem.

    • Przepływ OAuth: Usługa-do-usługi (S2S)dane uwierzytelniające klienta.
    • Roszczenie tokena: roles.
    • Trasa adresu URL: /observabilityService/....

  • Usługa uwierzytelnia się w imieniu użytkownika: dla członków zespołu AI lub dla własnego konta użytkownika agenta.

    • Przepływ OAuth: On-behalf-of (OBO).
    • Roszczenie tokena: scp.
    • Trasa adresu URL: /observability/....

Ta sama aplikacja agenta może uczestniczyć w obu przepływach, na przykład AI-asystent zespołowy, który również wykonuje nocną autonomiczną rundę podsumowania. Aby uzyskać więcej informacji, zobacz przepływ OAuth dla aplikacji autonomicznych oraz przepływ on-behalf-of.

Pełne przepisy tokenów dla każdej kombinacji modelu tożsamości i przepływu można znaleźć w przewodniku Recepty uwierzytelniania w przewodniku integracyjnym.

Tożsamość agenta jest powiązana z adresem URL

{agentId} w adresie URL musi być taki sam jak appId wywołującej aplikacji (czyli roszczenie appid lub azp w tokenie). W przypadku niezgodności zwracany jest 403 Forbidden. W przypadku tożsamości pochodzących z blueprint, {agentId} to identyfikator agenta appId, a nie blueprint appId.

Ponadto każdy przesyłany span musi mieć ustawiony gen_ai.agent.id na ten sam appId; serwer weryfikuje tożsamość agenta w przesyłanym spanie względem uwierzytelnionego agenta i odrzuca rozbieżności. Ten krok wykrywa przypadkowe mieszanie span od wielu agentów w jednym żądaniu.

Zakres (delegowany) lub rola aplikacji (aplikacja) to nazwane uprawnienia, które Microsoft Entra wprowadza do tokena dostępu. W przypadku telemetrii Agent 365 uprawnienie Agent365.Observability.OtelWrite dotyczy zasobu Agent 365 Observability (audience 9b975845-388f-4429-889e-eab1ef63949c).

To samo uprawnienie jest zarejestrowane jako oba typy:

  • Rola aplikacji dla autonomicznego przepływu (S2S / client-credentials). Występuje w roszczeniu roles. Wybrane przez <resource>/.default.
  • Zakres delegowany dla przepływu OBO. Występuje w roszczeniu scp. Wybrane przez <resource>/Agent365.Observability.OtelWrite (lub <resource>/.default).

Agent 365 udostępnia także uprawnienie odczytu, Agent365.Observability.OtelRead, używane przez operatorów, którzy wykonują zapytania dotyczące telemetrii Agent 365. Większość partnerów tego nie potrzebuje – ta dokumentacja dotyczy wyłącznie pozyskiwanie danych.

Dodawanie uprawnienia do aplikacji

  • Dla standardowej rejestracji aplikacji Microsoft Entra: w portalu Azure Portal dodaj Agent365.Observability.OtelWrite (rola aplikacji dla S2S, zakres dla delegowanych) pod uprawnieniami API przy rejestracji aplikacji agenta.
  • Dla blueprint: agenty utworzone na podstawie blueprint tożsamości agenta Identyfikator agenta Microsoft Entra dziedziczą uprawnienia OAuth określone w blueprint, więc administrator dzierżawy przydziela je z wyprzedzeniem tylko raz. Każda instancja agenta utworzona na podstawie tego szablonu otrzymuje je automatycznie. Zobacz Konfiguruj dziedziczne uprawnienia dla planów tożsamości agenta.

Zanim tokeny otrzymają rolę lub zakres, administrator dzierżawy w dzierżawie klienta musi udzielić zgody. Zobacz Udziel agentom dostępu do zasobów Microsoft 365.

Jeśli nie została udzielona zgoda, pobranie tokena kończy się błędem AADSTS65001 („użytkownik lub administrator nie wyraził zgody”) albo token zostaje wydany bez odpowiedniego atrybutu roles / scp i punkt końcowy pozyskiwania odrzuca żądanie z 403.

Zgoda jest udzielana raz dla dzierżawy i obowiązuje dla każdej instancji utworzonej z szablonu. Ponowna zgoda jest wymagana tylko wtedy, gdy do blueprint zostanie dodane nowe uprawnienie.

Limity i warunki odrzucenia

Znajomość tych ograniczeń wcześniej zapobiega niespodziankom podczas integracji – większość działa niezauważalnie (API akceptuje żądanie, ale dane nigdy nie pojawiają się w dalszym przepływie danych).

Limity poziomu przewodów:

  • api-version=1 jest wymagany przy każdym żądaniu.
  • Maksymalny rozmiar treści żądania to 1 MB. Większe żądania otrzymują 413 Payload Too Large.
  • Obie trasy mają oddzielne limity szybkości. Na 429, honoruj Retry-After (ustawiony na 1 drugi) i odsuń się z drżeniem.

Odpowiedzi błędów:

  • 403 Forbidden—token brakuje wymaganej roli / zakresu aplikacji lub {agentId} w URL, nie zgadza się z tokenem appid / azp.
  • 413 Payload Too Large—treść żądania przekracza 1 MB.
  • 429 Too Many Requests—przekroczono limit żądań; przestrzegaj Retry-After: 1 i wycofaj się z losowym opóźnieniem.

Warunki odrzutu (żądanie zaakceptowane przez HTTP, ale dane nie pojawiają się w systemach downstream):

# Warunek Zachowanie
1 przypada na wpłatę z zysku na rzecz budżetu państwa Span gen_ai.operation.name nieobecny lub nie znajduje się w {invoke_agent, execute_tool, chat, output_messages} Odrzucenie na poziomie span. Widoczne w partialSuccess.rejectedSpans + errorMessage.
2 Żaden użytkownik w dzierżawie klienta nie ma przypisanej licencji Microsoft 365 E7 lub Microsoft Agent 365. Przynajmniej jeden użytkownik w dzierżawie musi mieć licencję przypisaną (obecność SKU w dzierżawie nie jest wystarczająca — przypisanie uruchamia zaplecza przepływu pracy Defender). Licencjonowany użytkownik nie musi być osobą wywołującą agenta. Całe żądanie zostało odrzucone bez powiadomienia. Zwraca wartość 200 { "partialSuccess": null }.

200 OK nie jest dowodem pozyskiwania. Użyj procesu weryfikacji, aby potwierdzić, że dane trafiły.

Gdzie pojawiają się dane

Po zaakceptowaniu span pojawiają się w trzech obszarach dostępnych dla klientów. Wszystkie trzy zależą od prawidłowego invoke_agent rozpiętości u podstawy biegu. Przebieg zawierający wyłącznie chat / execute_tool / output_messages span może być wyszukiwany w zaawansowanym wyszukiwaniu Defender (tabela CloudAppEvents), ale jest niewidoczny dla pozostałych obszarów poniżej.

Microsoft Defender. Aktywność agenta (invoke_agent, execute_tool, chat) pojawia się w widokach aktywności agenta. Administratorzy dzierżawy i analitycy bezpieczeństwa mogą zgłębiać poszczególne przebiegi, narzędzia i wywołania inferencji. Widoki aktywności agenta opierają się na invoke_agentspan; jeśli go nie ma, przebieg nie pojawia się w tych widokach, choć spany będące elementami podrzędnymi nadal można wyszukiwać za pomocą zaawansowanego polowania. Widok zaawansowanego wyszukiwania – CloudAppEvents – przyjmuje każdą operację: ActionType odzwierciedla operację (InvokeAgent, InferenceCall, ExecuteToolBySDK, ExecuteToolByGateway, ExecuteToolByMCPServer), a pola dotyczące poszczególnych spanów znajdują się wewnątrz RawEventData. Nazwy pól widoczne dla klienta bezpośrednio odpowiadają atrybutom span, które wysłano: ConversationId ← gen_ai.conversation.id, SessionIdentity ← microsoft.session.id, AgentId ← gen_ai.agent.id, PlatformTargetAgentId ← microsoft.a365.agent.platform.id, i tak dalej. Zobacz Dokumentację atrybutów dla pełnego mapowania.

Centrum administracyjne Microsoft 365. Aktywność agentów jest również widoczna w widokach inwentarza agentów i bezpieczeństwa, z których korzystają administratorzy dzierżawy do zarządzania agentami w swojej dzierżawie. Admin center pobiera wyłącznie wierszeinvoke_agent: agenty bez telemetrii invoke_agent nie pojawiają się w zapasach, a uruchomienia, które emitują tylko chat / execute_tool / output_messages, są tutaj niewidoczne. Atrybuty, które odczytuje centrum administracyjne (identyfikator agenta, nazwa agenta, identyfikator blueprintu, tożsamość dzwoniącego, identyfikator rozmowy, kanał, status błędu) pochodzą ze span invoke_agent.

Microsoft Purview. Aktywność agentów jest również udostępniana administratorom ds. zgodności w Microsoft Purview, gdzie mogą konfigurować zasady przetwarzania danych i polityki dotyczące uruchomień agentów (zapobieganie utracie danych, retencja, zgodność komunikacyjna itp.). Atrybuty, które polityki Purview wyznaczają (identyfikator agenta / identyfikator blueprint, tożsamość dzwoniącego, rozmowa/kanał, komunikaty z żądaniami i odpowiedziami) pochodzą wszystkie z tego invoke_agent typu span i jego elementów pochodnych.

Następne kroki

  • Last updated on