Koncepty pozorovatelnosti Agent 365

Tento článek vysvětluje datový model pozorovatelnosti Agenta 365 – jakou telemetrii agenti odesílají, kdo ji může odesílat, kam směřuje a jaké limity platí. Tyto koncepty se vztahují na všechny integrační cesty: Microsoft OpenTelemetry Distro, Agent 365 SDK a přímý OTel.

Poznámka:

Detaily na úrovni komunikace – URL cesty v autentizaci, chybové kódy v limitech a podmínkách zahození a limity velikosti a frekvence požadavků – platí specificky pro přímou OTel cestu. SDK a Distro tyto údaje abstrahují za vás. Zbytek tohoto článku (glosář, tok dat, modely identit, rozsahy, podmínky zahození, kde se data zobrazují) platí pro každou cestu.

Vyberte integrační cestu

Tři cesty emitují stejný spanový datový model do Agent 365. Vyberte jednu možnost:

  • Microsoft OpenTelemetry Distro - je doporučená pro nové integrace. SDK sjednocené pozorovatelnosti napříč Agent 365, Microsoft Foundry, Azure Monitor a dalšími.
  • Agent 365 SDK (SDK pozorovatelnosti) – dřívější SDK. Stále funguje bez zásadních změn, ale už není doporučenou cestou pro nové integrace; migrační pokyny pro stávající uživatele SDK budou brzy k dispozici.
  • Direct OTel – nezpracovaná cesta OTLP/HTTP. Použijte ho pouze, pokud už máte kanál OpenTelemetry, Agent Framework nemůže použít Agent 365 SDK, nebo pokud je váš agent v jazyce, který SDK dosud nepodporuje (například Java).

Ať už si vyberete jakoukoli cestu, platí datový model, modely identit, oprávnění, limity a cílová rozhraní popsaná níže.

Slovníček

  • App id (appId): Identifikátor aplikace vydaný při registraci aplikace Microsoft Entra nebo identity agenta ID agenta Microsoft Entra.
    • Shodné s OAuth client_id, nikoli s ID objektu Microsoft Entra.
    • V těchto dokumentech „agent id“ a „blueprint id“ znamenají totéž: appId.
  • Konverzace: Logické vlákno interakcí agentů, například chat vlákno v Teams.
    • Identifikován pomocí gen_ai.conversation.id.
    • Primární spojovací klíč pro běh.
  • Kanál: Prostředí, ve kterém agent běží: msteams, outlook, web a tak dále.
  • Běh: Jeden uživatelský vstup, jedna odpověď agenta. Modelováno jako strom OTel spanů sdílejících traceId.

Jak to funguje

Pro přehled Agent 365 a informace o tom, kam telemetrie směřuje, viz Přehled Microsoft Agent 365.

Telemetrii zasíláte jako sledovací data OpenTelemetry:

  • Strom spanů popisující jeden běh (jedna uživatelská zpráva dovnitř, jedna odpověď agenta ven).
  • Každý span popisuje jeden krok – volání hlavního agenta, volání LLM, volání nástroje nebo závěrečnou odpověď.

Tok dat

   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)                  |
  +-------------------------------------+

Modely identity

Pro úplné vysvětlení modelů identity agenta (standardní registrace aplikace Microsoft Entra vs. blueprint identity agenta ID agenta Microsoft Entra, včetně AI spolupracovníků) viz Začínáme s vývojem Agent 365. Zvolený model identity určuje, který autentizační tok a koncový bod použijete.

Pokud agent nemá registraci Microsoft Entra, nemůže tyto cesty využívat přímo. Identifikujte agenta pomocí alternativních atributů ID (viz Reference atributů) a obraťte se na tým Agent 365 ohledně příslušné vstupní cesty.

Ověřování

Autentizace se větví podle toho, zda se vaše služba autentizuje sama, nebo jménem uživatele. Větev rozhoduje o toku OAuth, deklaraci identity tokenu, který nese oprávnění, a cestě adresy URL.

  • Služba se ověřuje sama: Žádný přihlášený uživatel – autonomní, plánovaný nebo řízený událostmi.

    • Tok OAuth: Přihlašovací údaje klienta mezi službami (S2S).
    • Deklarace identity tokenu: roles.
    • Trasa adresy URL: /observabilityService/....

  • Služba se ověřuje jménem uživatele: Pro AI spolupracovníky nebo pro vlastní uživatelský účet agenta.

    • Tok OAuth: Jménem (OBO).
    • Deklarace identity tokenu: scp.
    • Trasa adresy URL: /observability/....

Stejná agentní aplikace se může účastnit obou toků, například AI spolupracovník, který také provádí noční autonomní shrnutí. Další informace naleznete v části Autonomní tok OAuth aplikace a Tok typu on-behalf-of.

Kompletní návody pro tokeny pro každou kombinaci modelu identity a toku najdete v návodech autentizace v průvodci integrací.

Identita agenta je vázána na URL

Hodnota {agentId} v URL musí být rovna appId volající aplikace (deklarace identity appid nebo azp ve vašem tokenu). Při nesouladu server vrací 403 Forbidden. U identit odvozených z blueprintu {agentId} je appId identity agenta, nikoli appId blueprintu.

Navíc každý span, který odešlete, musí mít gen_ai.agent.id nastavený na stejný appId. Server ověřuje identitu agenta v datové části vůči autentizovanému agentovi a odmítá nesoulady. Tento krok zamezí neúmyslnému smíšení spanů od více agentů v jednom požadavku.

Rozsah (delegovaný) nebo role aplikace (aplikace) je pojmenované oprávnění, které Microsoft Entra vkládá do přístupového tokenu. Pro telemetrii Agent 365 je oprávnění Agent365.Observability.OtelWrite na zdroji pozorovatelnosti Agent 365 (cílová entita 9b975845-388f-4429-889e-eab1ef63949c).

Stejný název oprávnění je registrován jako oba typy:

  • Role aplikace pro autonomní (S2S / klientské přihlašovací údaje) tok. Skončí v deklaraci identity roles. Vybráno <resource>/.default.
  • Delegovaný rozsah pro tok OBO. Skončí v deklaraci identity scp. Vybráno <resource>/Agent365.Observability.OtelWrite (nebo <resource>/.default).

Agent 365 také zpřístupňuje oprávnění na straně čtení, Agent365.Observability.OtelRead, které používají operátoři dotazující se na telemetrii Agent 365. Většina partnerů to nepotřebuje – tyto dokumenty pokrývají pouze příjem.

Přidání oprávnění do aplikace

  • Pro standardní registraci aplikace Microsoft Entra: na webu Azure Portal přidejte Agent365.Observability.OtelWrite (role aplikace pro S2S, rozsah pro delegované) v části Oprávnění rozhraní API na registraci aplikace agenta.
  • Pro blueprint: agenti vytvoření z blueprintu identity agenta ID agenta Microsoft Entra dědí oprávnění OAuth definovaná na blueprintu, takže správce tenantu provede nastavení oprávnění pouze jednou. Každá instance agenta vytvořená z tohoto blueprintu je automaticky obdrží. Viz Konfigurace dědičných oprávnění pro blueprinty identity agenta.

Než mohou tokeny nést roli/rozsah, musí správce v zákaznickém tenantovi udělit souhlas. Viz Udělení přístupu agentům ke zdrojům Microsoft 365.

Bez uděleného souhlasu selže získání tokenu s AADSTS65001 („uživatel nebo administrátor nedal souhlas“) nebo je token vydán bez deklarace identity roles / scp a koncový bod příjmu zamítne žádost s 403.

Souhlas je udělen jednou na tenanta a platí pro každou instanci vytvořenou podle blueprintu poté. Opětovný souhlas je potřeba pouze tehdy, když je do blueprintu přidáno nové oprávnění.

Limity a zahazovací podmínky

Znalost těchto limitů předem zabraňuje překvapením během integrace – většina se neprojevuje (API přijímá požadavek, ale data se nikdy neobjeví dál).

Limity na úrovni protokolu:

  • api-version=1 je vyžadováno pro každý požadavek.
  • Maximální velikost těla požadavku je 1 MB. Větší požadavky dostávají 413 Payload Too Large.
  • Oba směry mají samostatné limity rychlosti. Na 429 dodržte Retry-After (nastaveno na 1 sekund) a snižte frekvenci s náhodným zpožděním.

Chybové odpovědi:

  • 403 Forbidden--token nemá požadovanou roli/rozsah aplikace nebo {agentId} v adrese URL neodpovídá appid / azp ve vašem tokenu.
  • 413 Payload Too Large--tělo přesahuje 1 MB.
  • 429 Too Many Requests--byl dosažen limit počtu požadavků, respektujte Retry-After: 1 a snižte frekvenci náhodným zpožděním.

Podmínky zahazování (požadavek přijatý protokolem HTTP, ale data se nedostanou do následných částí):

# Podmínka Chování
1 Span gen_ai.operation.name chybí nebo není v {invoke_agent, execute_tool, chat, output_messages} Zahození jednotlivých spanů. Zobrazeno v partialSuccess.rejectedSpans + errorMessage.
2 Žádný uživatel v tenantovi zákazníka nemá přiřazenou licenci Microsoft 365 E7 nebo Microsoft Agent 365. Alespoň jeden uživatel v tenantu musí mít přiřazenou licenci (pouhá přítomnost SKU v tenantu nestačí – přiřazení spouští backendový pracovní postup Defender). Licencovaný uživatel nemusí být osobou, která volá agenta. Celá žádost byla tiše zahozena. Vrátí 200 { "partialSuccess": null }.

200 OK není důkazem ingesce. Použijte ověřovací postup k potvrzení, že data byla přijata.

Kde se objevují vaše data

Po přijetí se vaše spany zobrazí ve třech zákaznických prostředích. Všechny tři závisí na platném spanu invoke_agent na počátku běhu. Běh obsahující pouze spany chat / execute_tool / output_messages je možné dotazovat v pokročilém proaktivním vyhledávání Defender (tabulka CloudAppEvents), ale není viditelný v žádném dalším rozhraní níže.

Microsoft Defender. Aktivita agenta (invoke_agent, execute_tool, chat) se zobrazuje v zobrazeních aktivity agenta. Správci tenantů a bezpečnostní analytici mohou prozkoumat jednotlivé běhy, nástroje a inferenční volání. Zobrazení aktivity agenta používají span invoke_agent, bez něj se běh neobjevuje, i když podřízené spany jsou stále dotazovatelné pomocí pokročilého proaktivního vyhledávání. Zobrazení pokročilého proaktivního vyhledávání – CloudAppEvents – přijímá každou operaci: ActionType zobrazuje operaci (InvokeAgent, InferenceCall, ExecuteToolBySDK, ExecuteToolByGateway, ExecuteToolByMCPServer) a pole pro každý span jsou uvnitř RawEventData. Názvy polí viditelných zákazníkům se přímo mapují na atributy spanu, které jste poslali: ConversationId ← gen_ai.conversation.id, SessionIdentity ← microsoft.session.id, AgentId ← gen_ai.agent.id, PlatformTargetAgentId ← microsoft.a365.agent.platform.id a tak dále. Viz referenci atributů pro kompletní mapování.

Centrum pro správu Microsoft 365. Aktivita agentů se také objevuje v inventáři agentů a bezpečnostních pohledech, které administrátoři tenantů používají ke správě agentů ve svém tenantu. Centrum pro správu přijímá pouze řádky invoke_agent: agenti bez telemetrie invoke_agent se v inventáři nezobrazují a běhy, které generují pouze chat / execute_tool / output_messages, jsou zde neviditelné. Všechny atributy, které centrum pro správu čte (ID agenta, jméno agenta, ID blueprintu, identita volajícího, ID konverzace, kanál, stav chyby), pocházejí ze spanu invoke_agent.

Microsoft Purview. Aktivita agentů je také zpřístupněna správcům pro dodržování předpisů v Microsoft Purview, kde mohou definovat pravidla pro zpracování dat a zásady pro běhy agentů (prevence ztráty dat, retence, komunikační soulad a podobně). Atributy, na které se zásady Purview zaměřují (ID agenta / ID blueprintu, identita volajícího, konverzace/kanál, zprávy o požadavcích a odpovědích), pocházejí všechny ze spanu invoke_agent a jeho potomků.

Další kroky

  • Last updated on