Konsepter for Agent 365-observabilitet

Denne artikkelen forklarer datamodellen bak Agent 365-observabilitet – hva telemetriagenter sender ut, hvem som kan sende ut data, hvor det mottas, og hvilke grenser som gjelder. Disse konseptene gjelder for alle integrasjonsveier: Microsoft OpenTelemetrie-distribusjonen, Agent 365 SDK og direkte OTel.

Notat

Detaljer på trådnivå – nettadresserutene i Autentisering, HTTP-feilkodene i Grenser og bortfallsbetingelser, og grensene for størrelse og hastighet per forespørsel – gjelder spesifikt for den direkte OTel-integrasjonen. SDK-en og Distroen håndterer dette for deg. Resten av denne artikkelen (ordliste, dataflyt, identitetsmodeller, omfang, dropbetingelser, hvor dataen dukker opp) gjelder for alle integrasjonsveier.

Velg integrasjonsvei

Tre veier sender ut den samme span-baserte datamodellen til Agent 365. Velg én:

  • Microsoft OpenTelemetry-distribusjon - anbefales for nye integrasjoner. Unified observability SDK på tvers av Agent 365, Microsoft Foundry, Azure Monitor og flere plattformer.
  • Agent 365 SDK (Observability SDK) – den tidligere SDK-en. Fortsetter å fungere uten endringer som bryter kompatibilitet, men er ikke lenger den anbefalte løsningen for nye integrasjoner; migreringsveiledning for eksisterende SDK-brukere kommer.
  • Direct OTel - den rå OTLP/HTTP-stien. Bruk det kun hvis du allerede har en OpenTelemetry-kanal på plass, agent-rammeverket ditt ikke kan bruke Agent 365 SDK-en, eller agenten din er i et språk SDK-en ennå ikke støtter (som Java).

Uansett hvilken integrasjonsvei du velger, gjelder datamodellen, identitetsmodellene, omfang, begrensninger og nedstrømsflater som beskrevet nedenfor.

Ordliste

  • Microsoft Entra App-id (appId): Applikasjonsidentifikatoren som utstedes når en Microsoft Entra-app eller Microsoft Entra Agent-ID-agentidentitet registreres.
    • Lik OAuth client_id, ikke Microsoft Entra-objekt-ID-en.
    • I denne dokumentasjonen refererer både «agent-id» og «blueprint-id» til en appId.
  • Samtale: En logisk tråd med agentinteraksjoner, for eksempel en Teams-nettprattråd.
    • Identifisert av gen_ai.conversation.id.
    • Den primære join-nøkkelen for en kjøring.
  • Kanal: Plattformen eller miljøet agenten kjører i: msteams, outlook, web og så videre.
  • Kjøring: Én brukermelding inn, ett agentsvar ut. Modellert som et tre av OTel spans som deler en traceId.

Hvordan det fungerer

For en oversikt over Agent 365 og hvilke systemer telemetri leveres til, se Oversikt over Microsoft Agent 365.

Du sender telemetri som sporingsdata fra OpenTelemetry:

  • Et tre av spans som beskriver én kjøring (én brukermelding inn, ett agentsvar ut).
  • Hver span beskriver et enkelt trinn – toppnivå-agentkallet, et LLM-kall, et verktøykall eller det endelige svaret.

Dataflyt

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

Identitetsmodeller

For en fullstendig forklaring av agentidentitetsmodeller (standard Microsoft Entra-appregistrering vs. Microsoft Entra Agent ID-agentidentitetsblueprint, inkludert AI-lagkamerater), se Kom i gang med Agent 365-utvikling. Valg av identitetsmodell bestemmer hvilken autentiseringsflyt og hvilket endepunkt du bruker.

Hvis agenten din ikke har noen Microsoft Entra-registrering, kan den ikke bruke disse rutene direkte. Identifiser agenten via alternative ID-attributter (se Attributtreferanse) og kontakt Agent 365-teamet angående riktig inngangsvei.

Godkjenning

Autentisering deles opp basert på om tjenesten din autentiserer seg selv eller på vegne av en bruker. Grenen bestemmer OAuth-flyten, tokenkravet som bærer tillatelsen, og URL-ruten.

  • Tjenesten autentiserer seg: Ingen innlogget bruker – autonom, planlagt eller hendelsesdrevet.

    • OAuth-flyt: Service-to-service (S2S) klientlegitimasjon.
    • Tokenpåstand: roles.
    • URL-rute: /observabilityService/....

  • Tjenesten autentiserer på vegne av en bruker: For AI-teammedlemmer, eller for agentens egen brukerkonto.

    • OAuth-flyt: På vegne av (OBO).
    • Tokenpåstand: scp.
    • URL-rute: /observability/....

Den samme agent-appen kan delta i begge flytene, for eksempel som en AI-assistent som også utfører en automatisk oppsummering om natten. For mer informasjon, se autonom app OAuth-flyt og on-behalf-of-flyt.

For fullstendige tokenkonfigurasjoner for hver kombinasjon av identitetsmodell og flyt, se Autentiseringskonfigurasjoner i integrasjonsguiden.

Agentidentiteten er bundet til nettadressen

{agentId} i nettadresse må være identisk med den anropende applikasjonens appId (appid eller azp-claim i tokenet). Ved mismatch returneres 403 Forbidden. For blueprint-avledede identiteter er {agentId}agentidentitetens appId, ikke blueprint-appId.

I tillegg må hver span du sender ha gen_ai.agent.id satt til samme appId; serveren validerer agentidentiteten i nyttelasten mot den autentiserte agenten og avviser mismatcher. Dette trinnet fanger opp at spans fra flere agenter ved et uhell blandes i én forespørsel.

Et scope (delegert) eller app-rolle (applikasjon) er den navngitte tillatelsen Microsoft Entra minter inn i tilgangstokenet. For Agent 365-telemetri gjelder tillatelsen Agent365.Observability.OtelWrite for Agent 365 Observability-ressursen (audience 9b975845-388f-4429-889e-eab1ef63949c).

Samme tillatelsesnavn registreres for begge typer:

  • App-rollen for den autonome (S2S / klient-legitimasjonsflyt) flyten. Lander i roles-claimet. Valgt av <resource>/.default.
  • Delegert omfang for OBO-flyten. Lander i scp-claimet. Valgt av <resource>/Agent365.Observability.OtelWrite (eller <resource>/.default).

Agent 365 eksponerer også en lesetillatelse, Agent365.Observability.OtelRead, som brukes av operatører som forespør Agent 365-telemetri. De fleste partnere trenger ikke denne tillatelsen – disse dokumentene dekker kun datainntak.

Legge til tillatelsen i appen

  • For en standard Microsoft Entra-appregistrering: i Azure-portalen, legg til Agent365.Observability.OtelWrite (app-rolle for S2S, scope for delegert) under API-tillatelser på agentens appregistrering.
  • For en blueprint: agenter opprettet fra en Microsoft Entra Agent ID agentidentitetsblueprint arver OAuth-tillatelsene som er definert på blueprinten, slik at en leietakeradministrator forhåndsprovisjonerer tillatelser én gang. Alle agentinstanser som er opprettet fra blueprinten får dem automatisk. Se Konfigurer arvelige tillatelser for agent identity blueprints.

Før tokens får rolle eller omfang, må en leietakeradministrator i kundens leietaker gi samtykke. Se Gi agenter tilgang til Microsoft 365-ressurser.

Uten samtykke mislykkes tokeninnhenting med AADSTS65001 ("bruker eller administrator har ikke gitt samtykke"), eller tokenet utstedes uten roles / scp-kravet, og inntaksendepunktet avviser forespørselen med 403.

Samtykke gis én gang per leietaker, og gjelder for alle instanser som opprettes fra en blueprint deretter. Samtykke må bare gis på nytt når en ny tillatelse legges til i blueprint.

Grenser og betingelser for bortfall

Å kjenne til disse begrensningene på forhånd forhindrer overraskelser under integrasjonen – de fleste er usynlige (API-et godtar forespørselen, men data vises ikke nedstrøms).

Grenser på wire-nivå:

  • api-version=1 er påkrevd ved hver forespørsel.
  • Maksimal størrelse på forespørselsbody er 1 MB. Større forespørsler får 413 Payload Too Large.
  • De to rutene har separate prisgrenser. På 429, honor Retry-After (satt til 1 andre) og trekk deg tilbake med jitter.

Feilsvar:

  • 403 Forbidden--token mangler den nødvendige app-rollen eller scope, eller {agentId} i nettadressen samsvarer ikke med appid / azp i tokenet ditt.
  • 413 Payload Too Large--body overstiger 1 MB.
  • 429 Too Many Requests--hastighetsgrense nådd; respekter Retry-After: 1 og vent med jitter.

Droppbetingelser (forespørsel akseptert av HTTP, men data vises ikke nedstrøms):

# Betingelse Funksjonalitet
1 Span gen_ai.operation.name mangler eller er ikke i {invoke_agent, execute_tool, chat, output_messages} Per spenn fall. Vises i partialSuccess.rejectedSpans + errorMessage.
2 Ingen bruker i kundeleietakeren har tildelt en Microsoft 365 E7- eller Microsoft Agent 365-lisens. Minst én bruker i leietakeren må ha lisensen tildelt (det er ikke tilstrekkelig at SKU-en finnes i leietakeren – tildeling starter Defender-backendarbeidsflyten). Den lisensierte brukeren trenger ikke å være den menneskelige oppringeren til agenten. Hele forespørselen droppes uten varsel. Returer 200 { "partialSuccess": null }.

En OK på 200 er ikke bevis på inntak. Bruk verifiseringsflyten for å bekrefte at data er mottatt.

Hvor dataen din vises

Når de er akseptert, vises spans i tre kundevendte opplevelser. Alle tre avhenger av en gyldig invoke_agent span ved roten av løpet. Et løp med kun chat / execute_tool / output_messages spans er søkbar i Defender avansert jakt (tabellen CloudAppEvents), men er usynlig for alle andre flater nedenfor.

Microsoft Defender. Agentaktivitet (invoke_agent, execute_tool, chat) vises i agentaktivitetsvisninger. Leietakeradministratorer og sikkerhetsanalytikere kan undersøke individuelle kjøringer, verktøy og inferensanrop. Agent-aktivitetsvisningene baserer seg på invoke_agentspan; uten en span vises ikke kjøringen der, selv om underordnede spans fortsatt er søkbare via avansert jakt. Avansert jakt-visning - CloudAppEvents - godtar alle operasjoner: ActionType viser operasjonen (InvokeAgent, InferenceCall, ExecuteToolBySDK, ExecuteToolByGateway, ExecuteToolByMCPServer), og per-span-feltene finnes i RawEventData. Kundesynlige feltnavn samsvarer direkte med span-attributtene du sendte: ConversationId ← gen_ai.conversation.id, SessionIdentity ← microsoft.session.id, AgentId ← gen_ai.agent.id, PlatformTargetAgentId ← microsoft.a365.agent.platform.id, og så videre. Se Attributtreferanse for full kartlegging.

Administrasjonssenter for Microsoft 365. Agentaktivitet vises også i agentinventar- og sikkerhetsvisningene som leietakeradministratorer bruker for å administrere agenter i sin leietaker. Administrasjonssenteret importerer kun invoke_agent-rader: agenter uten invoke_agent-telemetri vises ikke i inventaret, og kjøringer som kun sender ut chat / execute_tool / output_messages er usynlige her. Attributtene som administrasjonssenteret leser (agent-ID, agentnavn, blueprint-ID, anroperidentitet, samtale-ID, kanal, feilstatus) kommer alle fra invoke_agent-spanen.

Microsoft Purview. Agentaktivitet vises også for compliance-administratorer i Microsoft Purview, hvor de kan konfigurere datahåndterings- og policyregler over agentkjøringer (forebygging av datatap, oppbevaring, kommunikasjonsoverholdelse og lignende). Attributtene som Purview-policyene baserer seg på (agent-ID / blueprint-ID, anroperidentitet, samtale / kanal, forespørsels- og svarmeldinger) kommer alle fra invoke_agentspanen og dens etterkommere.

Neste trinn

  • Attributtreferanse – Spesifikasjon, krav og veiledning for valg av verdier per attributt.
  • Feilsøking – Verifisering av inntak, vanlige fallgruver og feilsvar.
  • Last updated on