Concepts d’observabilité de l’agent 365

Cet article explique le modèle de données derrière l’observabilité de l’Agent 365 : quels agents de télémétrie émettent, qui peuvent l’émettre, où il atterrit et les limites qui s’appliquent. Ces concepts s’appliquent à chaque parcours d’intégration : le Microsoft OpenTelemetry Distro, le Agent 365 SDK et OTel direct.

Note

Détails au niveau du protocole : les routes d’URL de Authentication, les codes d’erreur HTTP de Limits and drop conditions, ainsi que les limites de taille et de débit par requête s’appliquent spécifiquement au chemin OTel direct. Le Kit de développement logiciel (SDK) et la distribution résument ceux-ci pour vous. Le reste de cet article (glossaire, flux de données, modèles d’identité, étendues, conditions de dépôt, où les données s’affichent) s’applique à chaque chemin d’accès.

Choisir votre chemin d’intégration

Trois chemins émettent le même modèle de données d’étendue dans Agent 365. Choisissez-en un :

  • Microsoft OpenTelemetry Distro - recommandé pour les nouvelles intégrations. Kit de développement logiciel (SDK) d’observabilité unifiée entre agent 365, Microsoft Foundry, Azure Monitor, etc.
  • Agent 365 SDK (SDK d’observabilité) - l’ancien SDK. Continue à fonctionner sans introduire de changement cassant, mais ce n’est plus l’approche recommandée pour les nouvelles intégrations ; des recommandations de migration pour les utilisateurs existants du SDK seront bientôt disponibles.
  • Direct OTel : chemin OTLP/HTTP brut. Utilisez-la uniquement si vous disposez déjà d'un pipeline OpenTelemetry en place, votre infrastructure d'agent ne peut pas utiliser le Kit de développement logiciel (SDK) Agent 365, ou si votre agent se trouve dans un langage que le SDK ne prend pas encore en charge (par exemple, Java).

Quel que soit le chemin choisi, le modèle de données, les modèles d’identité, les étendues, les limites et les surfaces en aval décrites ci-dessous s’appliquent tous.

Glossaire

  • App id (appId) : identificateur d’application émis lorsqu’une application Microsoft Entra ou une identité d’agent Identifiant d’assistant Microsoft Entra est inscrite.
    • Identique à l’OAuth client_id, pas à l’ID d’objet Entra de Microsoft.
    • Dans l’ensemble de cette documentation, « identifiant de l’agent » et « identifiant du blueprint » désignent tous deux un appId.
  • Conversation : thread logique d’interactions de l’agent, tel qu’un fil de conversation Teams.
    • Identifié par gen_ai.conversation.id.
    • Clé primaire de jointure pour une exécution.
  • Canal : surface dans laquelle l’agent s’exécute : msteams, outlook, web, et ainsi de suite.
  • Exécution : un message utilisateur en entrée, une réponse de l’agent en sortie. Modélisée comme une arborescence de spans OTel partageant un traceId.

Fonctionnement

Pour obtenir une vue d’ensemble de l’Agent 365 et des flux de télémétrie, consultez Overview de Microsoft Agent 365.

Vous envoyez des données de télémétrie en tant que données de trace OpenTelemetry :

  • Un arbre de spans décrivant une exécution (un message utilisateur en entrée, une réponse de l’agent en sortie).
  • Chaque étendue décrit une seule étape : l’appel de l’agent de niveau supérieur, un appel LLM, un appel d’outil ou la réponse finale.

Flux de données

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

Modèles d’identité

Pour obtenir une explication complète des modèles d’identité d’agent (inscription d’application Microsoft Entra standard par rapport au plan d’identité d’agent Identifiant d’assistant Microsoft Entra, y compris les coéquipiers IA), consultez Prise en main du développement Agent 365. Votre choix de modèle d’identité détermine le flux d’authentification et le point de terminaison que vous utilisez.

Si votre agent n'a pas d'inscription Microsoft Entra, il ne peut pas utiliser ces itinéraires directement. Identifiez l’agent via les attributs d’ID alternatifs (voir Référence d’attribut) et contactez l’équipe Agent 365 sur le chemin d’entrée approprié.

Authentification

L’authentification diffère selon que votre service s’authentifie lui-même ou pour le compte d’un utilisateur. La branche détermine le flux OAuth, la revendication contenue dans le jeton qui porte l’autorisation, et la route d’URL.

  • Le service s’authentifie lui-même : aucun utilisateur connecté - autonome, planifié ou déclenché par des événements.

    • Flux OAuth : informations d’identification du client service à service (S2S ).
    • Demande de jeton : roles.
    • Itinéraire d’URL : /observabilityService/....

  • Le service s’authentifie pour le compte d’un utilisateur : pour les collègues d’IA ou pour le compte d’utilisateur de l’agent.

    • Flux OAuth : au nom de (OBO).
    • Réclamation du jeton : scp.
    • Itinéraire d’URL : /observability/....

La même application d’agent peut participer aux deux flux, comme un coéquipier d’IA qui exécute également une passe de synthèse autonome nocturne. Pour plus d’informations, consultez le flux OAuth pour application autonome et le flux On-Behalf-Of.

Pour obtenir les recettes de jeton complètes pour chaque combinaison de modèle d’identité et de flux, consultez les recettes d’authentification dans le guide d’intégration.

L’identité de l’agent est liée à l’URL

Le {agentId} dans l’URL doit être identique à l’appId de l’application appelante (la revendication appid ou azp dans votre jeton). Les non-correspondances renvoient 403 Forbidden. Pour les identités dérivées du modèle, {agentId} est l’appId de l’identité de l’agent, et non l’appId du modèle.

En outre, chaque span que vous envoyez doit définir gen_ai.agent.id avec le même appId ; le serveur valide l’identité de l’agent dans la charge utile par rapport à celle de l’agent authentifié et rejette toute discordance. Cette étape détecte le mélange accidentel de spans provenant de plusieurs agents dans une seule requête.

Un scope (délégué) ou rôle d’application (application) est l’autorisation nommée que Microsoft Entra intègre au jeton d’accès. Pour la télémétrie d’Agent 365, l’autorisation est Agent365.Observability.OtelWrite sur la ressource Observability d’Agent 365 (audience 9b975845-388f-4429-889e-eab1ef63949c).

Le même nom d’autorisation est enregistré comme relevant des deux types :

  • Rôle d’application pour le flux autonome (S2S / identifiants client). Terres visées par la roles revendication. Sélectionné par <resource>/.default.
  • Étendue déléguée pour le flux OBO. Terres dans la scp réclamation. Sélectionné par <resource>/Agent365.Observability.OtelWrite (ou <resource>/.default).

Agent 365 expose également une autorisation en lecture, Agent365.Observability.OtelRead, utilisée par les opérateurs qui interrogent la télémétrie d’Agent 365. La plupart des partenaires n’en ont pas besoin . ces documents couvrent uniquement l’ingestion.

Ajout de l’autorisation à votre application

  • Pour une inscription d’application Microsoft Entra standard : dans le portail Azure, ajoutez Agent365.Observability.OtelWrite (rôle d’application pour S2S, portée pour délégué) sous Autorisations d’API dans l’inscription d’application de l’agent.
  • Pour un blueprint : les agents créés à partir d’un blueprint d’identité d’agent Identifiant d’assistant Microsoft Entra inherit les autorisations OAuth définies dans le blueprint, de sorte qu’un administrateur du locataire préconfigure les autorisations une seule fois. Chaque instance de l’agent créée à partir de ce blueprint les reçoit automatiquement. Consultez Configurer les autorisations héritables pour les modèles d’identité d’agent.

Avant que les jetons ne contiennent le rôle ou l’étendue, un administrateur du locataire du client doit accorder le consentement. Consultez Autoriser les agents à accéder aux ressources Microsoft 365.

Sans consentement, l’acquisition du jeton échoue avec AADSTS65001 (« l’utilisateur ou l’administrateur n’a pas consenti »), ou le jeton est émis sans la revendication roles / scp et le point de terminaison d’ingestion rejette la requête avec 403.

Le consentement est accordé une fois par locataire et s’applique à chaque instance générée à partir d’un blueprint par la suite. La reconsente n’est nécessaire que lorsqu’une nouvelle autorisation est ajoutée au blueprint.

Limites et conditions de suppression

Le fait de connaître ces limites au début empêche les surprises lors de l’intégration : la plupart sont silencieux (l’API accepte la demande, mais les données n’apparaissent jamais en aval).

Limites au niveau du câble :

  • api-version=1 est requis pour chaque demande.
  • La taille maximale du corps de la requête est de 1 Mo. Les demandes plus volumineuses obtiennent 413 Payload Too Large.
  • Les deux itinéraires ont des limites de débit distinctes. 429, respecter Retry-After (réglé sur 1 seconde) et appliquer un délai avec gigue.

Réponses d’erreur :

  • 403 Forbidden--token manquant le rôle/l’étendue d’application requis, ou {agentId} dans l’URL ne correspond pas à votre appid / azp jeton.
  • 413 Payload Too Large--body dépasse 1 Mo.
  • 429 Too Many Requests--limite de débit atteinte ; respectez Retry-After: 1 et temporisez avec une temporisation aléatoire.

Conditions de suppression (demande acceptée par HTTP, mais les données n’apparaissent pas en aval) :

# Pathologie Behavior
1 Span gen_ai.operation.name manquant ou absent de {invoke_agent, execute_tool, chat, output_messages} Chute par étendue. Apparaît dans partialSuccess.rejectedSpans + errorMessage.
2 Aucun utilisateur du locataire du client ne s’est vu attribuer de licence Microsoft 365 E7 ou Microsoft Agent 365. Au moins un utilisateur du locataire doit avoir la licence attribuée (le fait que la référence SKU soit présente dans le locataire ne suffit pas - l’attribution déclenche le flux de travail du backend de Defender). L’utilisateur sous licence n’a pas besoin d’être l’appelant humain de l’agent. L’intégralité de la requête a été abandonnée sans notification. Retourne 200 { "partialSuccess": null }.

Un code 200 OK n’est pas une preuve d’ingestion. Utilisez le processus de vérification pour confirmer que les données arrivent à destination.

Où vos données s’affichent

Une fois acceptés, vos spans apparaissent dans trois expériences destinées aux clients. Les trois éléments dépendent d’un span invoke_agent valide à la racine de l’exécution. Une exécution avec uniquement des étendues chat / execute_tool / output_messages peut faire l’objet d’une requête dans la chasse avancée de Defender (la table CloudAppEvents), mais elle est invisible sur toutes les autres surfaces ci-dessous.

Microsoft Defender. L’activité de l’agent (invoke_agent, , execute_toolchat) apparaît dans les vues d’activité de l’agent. Les administrateurs de locataires et les analystes de sécurité peuvent explorer des exécutions, des outils et des appels d’inférence individuels. Les vues d’activité de l’agent s’appuient sur le invoke_agent span ; sans span, l’exécution n’y apparaît pas, même si les spans enfants restent interrogeables via la chasse avancée. La vue de recherche avancée - CloudAppEvents - prend en charge toutes les opérations : ActionType reflète l’opération (InvokeAgent, InferenceCall, ExecuteToolBySDK, ExecuteToolByGateway, ExecuteToolByMCPServer) et les champs par étendue se trouvent dans RawEventData. Les noms de champs visibles par le client correspondent directement aux attributs d’étendue que vous avez envoyés : ConversationId ← gen_ai.conversation.id, SessionIdentity ← microsoft.session.id, AgentId ← gen_ai.agent.id, PlatformTargetAgentId ← microsoft.a365.agent.platform.id, et ainsi de suite. Consultez la référence d’attribut pour le mappage complet.

Centre d’administration Microsoft 365. L’activité de l’agent s’affiche également dans les vues d’inventaire et de sécurité de l’agent utilisées par les administrateurs de locataires pour régir les agents de leur locataire. Le centre d’administration prend en compte uniquement les lignes invoke_agent : les agents sans données de télémétrie invoke_agent n’apparaissent pas dans l’inventaire, et les exécutions qui n’émettent que chat / execute_tool / output_messages sont invisibles ici. Les attributs que le centre d’administration lit (id de l’agent, nom de l’agent, id de blueprint, identité de l’appelant, ID de conversation, canal, état d’erreur) proviennent tous de l’étendue invoke_agent .

Microsoft Purview. L’activité de l’agent est également exposée aux administrateurs de conformité dans Microsoft Purview, où ils peuvent configurer la gestion des données et les règles de stratégie sur les exécutions de l’agent (protection contre la perte de données, rétention, conformité des communications et similaires). Les attributs sur lesquels les stratégies Purview s’appuient (ID de l’agent / ID du blueprint, identité de l’appelant, conversation / canal, messages de requête et de réponse) proviennent tous de l’élément invoke_agent et de ses descendants.

Étapes suivantes

  • Last updated on