Agent 365-waarneembaarheidsconcepten

Dit artikel legt het datamodel uit achter de waarneembaarheid van Agent 365 - wat telemetrieagenten uitzenden, wie het kan uitzenden, waar het terechtkomt en welke grenzen gelden. Deze concepten zijn van toepassing op elk integratiepad: de Microsoft OpenTelemetry Distro, de Agent 365 SDK en direct OTel.

Notitie

Draaddetails - de URL-routes in Verificatie, de HTTP-foutcodes in Limieten en dropcondities, en de limieten per verzoek en -snelheid - zijn specifiek van toepassing op het directe OTel-pad. De SDK en Distro abstraheren deze voor u. De rest van dit artikel (woordenlijst, gegevensstroom, identiteitsmodellen, bereiken, dropcondities, waar data verschijnt) is van toepassing op elk pad.

Kies uw integratiepad

Drie paden zenden dezelfde reeks gegevensmodellen in Agent 365. Kies er één:

  • Microsoft OpenTelemetry Distro - wordt aanbevolen voor nieuwe integraties. Uniforme waarneembaarheids-SDK op Agent 365, Microsoft Foundry, Azure Monitor en meer.
  • Agent 365 SDK (Waarneembaarheids-SDK) - de eerdere SDK. Blijft functioneren zonder ingrijpende wijzigingen, maar is niet langer het aanbevolen pad voor nieuwe integraties; migratierichtlijnen voor bestaande SDK-gebruikers zullen binnenkort beschikbaar zijn.
  • Direct OTel - het ruwe OTLP/HTTP-pad. Gebruik dit alleen als u al een OpenTelemetry-pijplijn heeft, uw agentframework de Agent 365 SDK niet kan gebruiken, of uw agent in een programmeertaal is geschreven die door de SDK nog niet wordt ondersteund (zoals Java).

Welk pad u ook kiest, het gegevensmodel, identiteitsmodellen, bereiken, limieten en downstream locaties zoals hieronder beschreven zijn allemaal van toepassing.

Woordenlijst

  • App-id (appId): de programma-identificatie die wordt uitgegeven wanneer een Microsoft Entra-app of Microsoft Entra Agent-ID-agentidentiteit wordt geregistreerd.
    • Gelijk aan de OAuth client_id, niet de object-ID van Microsoft Entra.
    • In deze documenten betekenen "agent id" en "blueprint id" allebei een appId.
  • Gesprek: een logische thread van agentinteracties, zoals een Teams-chatthread.
    • Geïdentificeerd door gen_ai.conversation.id.
    • De primaire join-sleutel voor een uitvoering.
  • Kanaal: de locatie waar de agent wordt uitgevoerd in: msteams, outlook, , webenzovoort.
  • Uitvoering: één gebruikersbericht binnen, één agentantwoord eruit. Gemodelleerd als een boom van OTel-spans die een traceId delen.

Hoe het werkt

Voor een overzicht van Agent 365 en waar telemetrie naartoe leidt, raadpleegt u Overzicht van Microsoft Agent 365.

U stuurt telemetrie als OpenTelemetry-traceringsgegevens:

  • Een boom van spans die één uitvoering beschrijft (één gebruikersbericht binnen, één agentantwoord eruit).
  • Elke span beschrijft één stap - de top-level agent-aanroep, een LLM-aanroep, een tool-aanroep of het laatste antwoord.

Gegevensstroom

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

Identiteitsmodellen

Voor een volledige uitleg van agentidentiteitsmodellen (standaard Microsoft Entra-appregistratie versus Microsoft Entra Agent-ID-agentidentiteits-blueprint, inclusief AI-teamgenoten), raadpleegt u Aan de slag met de ontwikkeling van Agent 365. Uw keuze van identiteitsmodel bepaalt welke verificatiestroom en welk eindpunt u gebruikt.

Als uw agent geen Microsoft Entra-registratie heeft, kan hij deze routes niet direct gebruiken. Identificeer de agent via de alternatieve ID-attributen (zie Attribuutreferentie) en neem contact op met het Agent 365-team over het juiste inkomende pad.

Verificatie

Verificatie is afhankelijk van of uw service zichzelf verificeert of dit namens een gebruiker doet. De branche bepaalt de OAuth-stroom, de tokenclaim die de toestemming draagt en de URL-route.

  • Service verificeert zichzelf: geen ingelogde gebruiker - autonoom, gepland of gebeurtenisgestuurd.

    • OAuth-stroom: Service-to-service (S2S) clientreferenties.
    • Tokenclaim: roles.
    • URL-route: /observabilityService/....

  • De service verificeert namens een gebruiker: voor AI-teamgenoten of voor het gebruikersaccount van de agent.

    • OAuth-stroom: Namens (OBO).
    • Tokenclaim: scp.
    • URL-route: /observability/....

Dezelfde agent-app kan aan beide stromen deelnemen, zoals een AI-teamgenoot die ook elke nacht een autonome samenvattingsronde uitvoert. Voor meer informatie, zie autonome app OAuth-stroom en On-Behalf-Of-stroom.

Voor de volledige tokenrecepten voor elke combinatie van identiteitsmodel en stroom raadpleegt u Verificatierecepten in de integratiegids.

De agentidentiteit is gebonden aan de URL

De {agentId} in de URL moet gelijk zijn aan de appId van de aanroepende applicatie (de appid of azp claim in uw token). Mismatches retourneren 403 Forbidden. Voor blueprint-afgeleide identiteiten is {agentId} de agent identity appId, niet de blueprint appId.

Daarnaast moet elke span die je verzendt gen_ai.agent.id op dezelfde appId zetten; de server valideert de in-payload agentidentiteit tegen de geverificeerde agent en weigert mismatches. Deze stap vangt per ongeluk door elkaar gemengde, meerdere agenten in één verzoek.

Een bereik (gedelegeerd) of app-rol (applicatie) is de benoemde toestemming die Microsoft Entra in het toegangstoken verwerkt. Voor Agent 365-telemetrie is de toestemming Agent365.Observability.OtelWrite op de Agent 365 waarneembaarheidsresource (publiek 9b975845-388f-4429-889e-eab1ef63949c).

Dezelfde toestemmingsnaam wordt geregistreerd als beide soorten:

  • Approl voor de autonome (S2S / clientreferenties) stroom. Komt terecht in de roles-claim. Geselecteerd door <resource>/.default.
  • Gedelegeerd bereik voor de OBO-stroom. Komt terecht in de scp-claim. Geselecteerd door <resource>/Agent365.Observability.OtelWrite (of <resource>/.default).

Agent 365 biedt ook een leesmachtiging, Agent365.Observability.OtelRead, gebruikt door operators die Agent 365-telemetrie opvragen. De meeste partners hebben het niet nodig – deze documenten dekken alleen opname.

De machtiging aan uw app toevoegen

  • Voor een standaard Microsoft Entra-appregistratie: voeg in de Azure Portal Agent365.Observability.OtelWrite (approl voor S2S, bereik voor gedelegeerd) toe onder API-machtigingen op de appregistratie van de agent.
  • Voor een blueprint: agents die zijn gemunt vanuit een Microsoft Entra Agent-ID-agentidentiteits-blueprint erven de OAuth-machtigingen die op de blauwdruk zijn gedefinieerd, dus een tenant-beheerder richt de machtigingen eenmaal vooraf in. Elk agentexemplaar die op die blueprint is gebouwd, ontvangt ze automatisch. Zie Erfbare rechten voor agentidentiteits-blueprints configureren.

Voordat tokens de rol/het bereik dragen, moet een tenantbeheerder toestemming geven in de tenant van de klant. Zie Agents toegang geven tot Microsoft 365-bronnen.

Zonder toestemming mislukt de tokenverwerving met AADSTS65001 ("gebruiker of beheerder heeft geen toestemming gegeven") of wordt de token uitgegeven zonder de roles / scp claim en weigert het invoerend eindpunt het verzoek met 403.

Toestemming wordt eenmaal per tenant gegeven en geldt voor elk exemplaar, dat daarna op basis van een blueprint wordt gebouwd. Nieuwe instemming is alleen nodig wanneer een nieuwe toestemming aan de blueprint wordt toegevoegd.

Limieten en dropcondities

Deze limieten vooraf kennen voorkomt verrassingen tijdens de integratie. De meeste zijn stil (de API accepteert het verzoek, maar de data verschijnt nooit stroomafwaarts).

Draadniveaulimieten:

  • api-version=1 is bij elk verzoek vereist.
  • De maximale aanvraagbody van het verzoek is 1 MB. Grotere verzoeken krijgen 413 Payload Too Large.
  • De twee routes hebben aparte tarieflimieten. Aan 429, waarborg Retry-After (ingesteld op 1 seconde) en ga terug met jitter.

Foutresponsen:

  • 403 Forbidden--token mist de vereiste app-rol / bereik, of {agentId} in de URL komt niet overeen met de appid / azp van uw token.
  • 413 Payload Too Large--body is groter dan 1 MB.
  • 429 Too Many Requests--snelheidslimiet bereikt; Waarborg Retry-After: 1 en ga terug met jitter.

Dropcondities (verzoek geaccepteerd door HTTP maar gegevens verschijnen niet stroomafwaarts):

# Voorwaarde Gedrag
1 Span gen_ai.operation.name ontbreekt of niet in {invoke_agent, execute_tool, chat, output_messages} Per-span-drop. Kwam boven in partialSuccess.rejectedSpans + errorMessage.
2 Geen enkele gebruiker in de klanttenant heeft een Microsoft 365 E7- of Microsoft Agent 365-licentie toegewezen. Minstens één gebruiker in de tenant moet de licentie toegewezen hebben (het feit dat de SKU in de tenant aanwezig is, is niet voldoende - de toewijzing start de back-end-workflow van Defender). De gelicentieerde gebruiker hoeft niet de menselijke aanroeper van de agent te zijn. Het hele verzoek werd stilletjes verworpen. Retourzendingen 200 { "partialSuccess": null }.

Een 200 OK is geen bewijs van gegevensopname. Gebruik de verificatiestroom om te bevestigen dat data aankomt.

Waar uw gegevens verschijnen

Zodra u bent geaccepteerd, komt uw span aan het licht in drie klantgerichte ervaringen. Alle drie zijn afhankelijk van een geldige invoke_agent span in de hoofdmap van de uitvoering. Een uitvoering met alleen chat / execute_tool / output_messages spans is opzoekbaar in geavanceerde opsporing van Defender (de CloudAppEvents tabel), maar is onzichtbaar voor alle andere oppervlakken eronder.

Microsoft Defender. Agentactiviteit (invoke_agent, execute_tool, chat) verschijnt in de agentactiviteitsweergaven. Tenantbeheerders en beveiligingsanalisten kunnen zich verdiepen in individuele uitvoeringen, tools en inferentiegesprekken. De agentactiviteitsweergaven zijn afgesloten van de invoke_agent span; zonder deze verschijnt de uitvoering daar niet, ook al zijn onderliggende spans nog steeds opzoekbaar via geavanceerde opsporing. De geavanceerde opsporingsweergave - CloudAppEvents - accepteert elke bewerking: ActionType weerspiegelt de bewerking (InvokeAgent, InferenceCall, ExecuteToolBySDK, ExecuteToolByGateway, ExecuteToolByMCPServer) en de per-span-velden bevinden zich binnen RawEventData. De door klanten zichtbare veldnamen worden direct gekoppeld aan de span-kenmerken die u hebt gestuurd: ConversationId ← gen_ai.conversation.id, SessionIdentity ← microsoft.session.id, AgentId ← gen_ai.agent.id, PlatformTargetAgentId ← microsoft.a365.agent.platform.id, enzovoort. Zie Kenmerkreferentie voor de volledige toewijzing.

Microsoft 365-beheercentrum. Agentactiviteit verschijnt ook in de agent-inventaris- en beveiligingsweergaven die door tenant-beheerders worden gebruikt om agenten in hun tenant te beheren. Het Beheercentrum neemt alleen invoke_agent rijen op: agents zonder invoke_agent telemetrie verschijnen niet in de voorraad en uitvoeringen die alleen chat / execute_tool / output_messages uitzenden, zijn hier onzichtbaar. De kenmerken die het Beheercentrum leest (agent-id, agentnaam, blueprint-id, beller-identiteit, gespreks-id, kanaal, foutstatus) komen allemaal uit de invoke_agent span.

Microsoft Purview. Agentactiviteit wordt ook aan beheerders voor naleving in Microsoft Purview getoond, waar zij gegevensverwerkings- en beleidsregels kunnen configureren voor agentuitvoeringen (gegevensverliespreventie, retentie, communicatienaleving en dergelijke). De kenmerken die het Purview-beleid heeft (agent-id / blueprint-id, belleridentiteit, gesprek/kanaal, verzoek- en antwoordberichten) komen allemaal van de invoke_agent span en haar descendants.

Volgende stappen

  • Last updated on