Begreber for Agent 365-observerbarhed

Denne artikel forklarer datamodellen bag Agent 365-observerbarhed – hvad telemetriagenter udsender, hvem der kan udsende det, hvor det lander, og hvilke grænser der gælder. Disse begreber gælder for alle integrationsstier: Microsoft OpenTelemetry Distro, Agent 365 SDK og direct OTel.

Bemærk

Wireniveaudetaljer – URL-adressen sender i Godkendelse, HTTP-fejlkoderne i grænser og dropbetingelser, samt størrelses- og hastighedsgrænser pr. anmodning – gælder specifikt for den direkte OTel-sti. SDK'en og distro'en abstraherer disse for dig. Resten af denne artikel (ordliste, dataflow, identitetsmodeller, omfang, dropbetingelser, hvor data vises) gælder for alle integrationsstier.

Vælg din integrationssti

Tre integrationsstier udsender den samme span-datamodel til Agent 365. Vælg én:

  • Microsoft OpenTelemetry Distro - anbefales til nye integrationer. SDK for samlet observerbarhed på tværs af Agent 365, Microsoft Foundry, Azure Monitor og andre.
  • Agent 365 SDK (Observerbarhed SDK) – den tidligere SDK. Fortsætter med at fungere uden væsentlige ændringer, men er ikke længere den anbefalede sti for nye integrationer; migrationsvejledning for eksisterende SDK-brugere er på vej.
  • Direct OTel – den rå OTLP/HTTP-sti. Brug det kun, hvis du allerede har en OpenTelemetry-pipeline på plads, din agentstruktur kan ikke bruge Agent 365 SDK'en, eller din agent er på et sprog, som SDK'en endnu ikke understøtter (såsom Java).

Uanset hvilken integrationssti du vælger, gælder datamodellen, identitetsmodellerne, omfang, begrænsningerne og downstream-overfladerne beskrevet nedenfor.

Ordliste

  • App-id (appId): Program-id, der udstedes, når en Microsoft Entra-app eller Microsoft Entra-agent ID-agentidentitet registreres.
    • Lig med OAuth client_id, ikke Microsoft Entra-objekt-ID'et.
    • Gennem disse dokumenter betyder "agent-id" og "plan-id" begge en appId.
  • Samtale: En logisk tråd af agentinteraktioner, såsom en Teams-chattråd.
    • Identificeret af gen_ai.conversation.id.
    • Den primære join-nøgle for en kørsel.
  • Kanal: Overfladen, hvor agenten kører i: msteams, outlook, web osv.
  • Kør: Én brugerbesked ind, ét agent-svar ud. Modelleret som et træ af OTel -spænd, der deler en traceId.

Sådan fungerer det

For et overblik over Microsoft Agent 365 og hvad telemetri indgår i, se Oversigt over Microsoft Agent 365.

Du sender telemetri som sporingsdata fra OpenTelemetry:

  • Et træ af spans der beskriver én kørsel (én brugerbesked ind, ét agentsvar ud).
  • Hvert span beskriver et enkelt trin – agentens topniveau-kald, et LLM-kald, et værktøjskald eller det endelige svar.

Dataflow

   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 fuld forklaring af agentidentitetsmodeller (standard Microsoft Entra-appregistrering vs. Microsoft Entra-agent-id-agentidentitets plan, inklusive AI-holdkammerater), se Kom i gang med udviklingen af Agent 365. Dit valg af identitetsmodel bestemmer, hvilket godkendelsesflow og slutpunkt du bruger.

Hvis din agent ikke har Microsoft Entra-registrering, kan den ikke bruge disse ruter direkte. Identificer agenten via de alternative ID-attributter (se Attributreference) og kontakt Agent 365-teamet om den relevante adgangssti.

Godkendelse

Godkendelse opdeles efter, om din tjeneste godkender sig selv eller på vegne af en bruger. Forgreningen bestemmer OAuth-flowet, tokenpåstanden, der bærer tilladelsen, og URL-adresse-ruten.

  • Tjenesten godkender sig selv: Ingen bruger logget på – autonom, planlagt eller hændelsesdrevet.

    • OAuth-flow: Service-to-service (S2S) klientlegitimationsoplysninger.
    • Tokenkrav: roles.
    • URL-adresse-rute: /observabilityService/....

  • Tjenesten godkender på vegne af en bruger: For AI-holdkammerater eller for agentens egen brugerkonto.

    • OAuth-flow: På vegne af (OBO).
    • Tokenkrav: scp.
    • URL-adresse-rute: /observability/....

Den samme agent-app kan deltage i begge flows, såsom en AI-teammedlem, der også kører en natlig autonom opsummeringsrunde. Du kan finde flere oplysninger i autonom app OAuth-flow og on-behalf-of-flow.

For de fulde tokenkonfigurationer for hver kombination af identitetsmodel og flow, se Godkendelsesopskrifter i Integrationsguiden.

Agentidentiteten er bundet til URL-adressen

{agentId} i URL-adressen skal være lig med det kaldende programs appId (appid eller azp påstanden i dit token). Uoverensstemmelser returnerer 403 Forbidden. For planafledte identiteter er {agentId}agentidentitetens appId, ikke planens appId.

Derudover skal hver span, du sender, angive gen_ai.agent.id til det samme appId; serveren validerer agentidentiteten i nyttedataene mod den godkendte agent og afviser uoverensstemmelser. Dette trin opdager utilsigtet blanding af spans fra flere agenter i én forespørgsel.

Et omfang (delegeret) eller app-rolle (program) er den navngivne tilladelse, som Microsoft Entra udsteder i adgangstokenet. For Agent 365-telemetri er tilladelsen Agent365.Observability.OtelWrite på ressourcen Agent 365-observerbarhed (målgruppe 9b975845-388f-4429-889e-eab1ef63949c).

Det samme tilladelsesnavn registreres som begge typer:

  • App-rollen for det autonome (S2S/klientlegitimationsoplysninger)-flow. Lander i roles-kravet. Valgt af <resource>/.default.
  • Delegeret omfang for OBO-flowet. Lander i scp-kravet. Valgt af <resource>/Agent365.Observability.OtelWrite (eller <resource>/.default).

Agent 365 udstiller også en læsetilladelse, Agent365.Observability.OtelRead, som bruges af operatører, der forespørger Agent 365-telemetri. De fleste partnere har ikke brug for det – disse dokumenter dækker kun indtagelse.

Tilføj tilladelsen til din app

  • For en standard Microsoft Entra app-registrering: tilføj Agent365.Observability.OtelWrite (app-rolle for S2S, omfang for delegeret) under API-tilladelser på agentens app-registrering i Azure-portalen.
  • For en plan: agenter præget fra et Microsoft Entra-agent-id-agentidentitetsblueprint arver OAuth-tilladelserne, der er defineret på planen, så en lejeradministrator klargør på forhånd tilladelser på én gang. Hver agentforekomst, der er baseret på denne plan, modtager dem automatisk. Se Konfigurér arvelige tilladelser for agentidentitetsplaner.

Før tokens bærer rollen/omfanget, skal en lejeradministrator i kundens lejer give samtykke. Se Giv adgang til Microsoft 365-ressourcer for agenter.

Uden samtykke mislykkes token-indhentning med AADSTS65001 ("brugeren eller administratoren har ikke givet samtykke") eller token udstedes uden roles / scp krav, og indlæsningsslutpunktet afviser anmodningen med 403.

Samtykke gives én gang pr. lejer og gælder for alle forekomster, der derefter bygges ud fra en plan. Gensamtykke er kun nødvendigt, når en ny tilladelse tilføjes til planen.

Grænser og betingelser for bortfald

Når disse grænser kendes på forhånd forhindrer det overraskelser under integrationen – de fleste er uovervåget (API'en accepterer anmodningen, men data vises aldrig nedstrøms).

Grænseværdier for wire-niveau:

  • api-version=1 er påkrævet ved hver anmodning.
  • Maksimal størrelse på anmodningsbrødtekst er 1 MB. Større anmodninger får 413 Payload Too Large.
  • De to ruter har separate hastighedsgrænser. Ved 429, skal du respektere Retry-After (sat til 1 sekund) og forsøge igen med backoff og jitter.

Fejlsvar:

  • 403 Forbidden – token mangler den nødvendige app-rolle/omfang, eller {agentId} i URL-adressen matcher ikke appid / azp i dit token.
  • 413 Payload Too Large – brødtekst overstiger 1 MB.
  • 429 Too Many Requests – hastighedsgrænse ramt; respekter Retry-After: 1 og forsøg igen med backoff og jitter.

Dropbetingelser (anmodning accepteres af HTTP, men data vises ikke nedstrøms):

# Betingelse Adfærd
1 Span gen_ai.operation.name mangler eller findes ikke i {invoke_agent, execute_tool, chat, output_messages} Fald per span. Vises i partialSuccess.rejectedSpans + errorMessage.
2 Ingen bruger i kundens lejer har en Microsoft 365 E7- eller Microsoft Agent 365-licens tildelt. Mindst én bruger i lejeren skal have licens tildelt (det er ikke tilstrækkeligt, at SKU'en blot er til stede i lejeren – tildeling igangsætter Defender-backend-workflowet). Den licenserede bruger behøver ikke være den person, der interagerer med agenten personligt. Hele anmodningen droppes uden besked. Angivelser 200 { "partialSuccess": null }

200 OK er ikke bevis for indtagelse. Brug verifikationsflowet til at bekræfte, at data lander.

Hvor dine data vises

Når de er accepteret, bliver dine spans synlige i tre kundevendte løsninger. Alle tre er afhængige af en gyldig invoke_agent span ved roden af kørslen. En kørsel kun med chat / execute_tool / output_messages spans kan forespørges i Defender avanceret jagt (CloudAppEvents-tabellen), men er usynlig i alle andre visninger nedenfor.

Microsoft Defender. Agentaktivitet (invoke_agent, execute_tool, chat) vises i agentaktivitetsvisningerne. Lejeradministratorer og sikkerhedsanalytikere kan undersøge individuelle kørsler, værktøjer og udledningskald. Agent-aktivitetsvisningerne afhænger af invoke_agent span; uden en sådan vises kørslen ikke der, selvom underordnede spans stadig kan forespørges via avanceret jagt. Avanceret jagtvisningen – CloudAppEvents – accepterer alle operationer: ActionType afspejler operationen (InvokeAgent, InferenceCall, ExecuteToolBySDK, ExecuteToolByGateway, ExecuteToolByMCPServer), og felterne for hver span findes i RawEventData. De feltnavne, der er synlige for kunden, matcher direkte de span-attributter, du har sendt: ConversationId ← gen_ai.conversation.id, SessionIdentity ← microsoft.session.id, AgentId ← gen_ai.agent.id, PlatformTargetAgentId ← microsoft.a365.agent.platform.id, og så videre. Se Attributreference for den fulde tilknytning.

Microsoft 365 Administration. Agentaktivitet vises også i agentlager- og sikkerhedsvisninger, som lejeradministratorer bruger til at administrere agenter i deres lejer. Administrator indtager kun invoke_agent-rækker: agenter uden invoke_agent-telemetri vises ikke på lageret, og kørsler, der kun udsender chat / execute_tool / output_messages er usynlige her. De attributter Administration læser (agent-id, agentnavn, plan-id, opkalders identitet, samtale-id, kanal, fejlstatus) kommer alle fra invoke_agent span.

Microsoft Purview. Administratorer af overholdelse kan også se agentaktivitet i Microsoft Purview, hvor de kan konfigurere regler for datahåndtering og politikker for agentkørsler (datatabsforebyggelse, opbevaring, kommunikationsoverholdelse og lignende). De attributter, som Purview-politikkerne aktiverer (agent-id/plan-id, opkaldsidentitet, samtale/kanal, anmodning og svarbeskeder) kommer alle fra invoke_agent-spanen og dens underordnede.

Næste trin

  • Attributreference – Specifikation, krav og vejledning om valg af værdier for hver attribut.
  • Fejlfinding - Bekræftelse af indtagelse, almindelige faldgruber og fejlrespons.
  • Last updated on