Concepts d’observabilité de l’agent 365

Cet article explique le modèle de données d’observabilité de l’Agent 365, y compris ce que les agents de télémétrie émettent, qui peut l’émettre, où il atterrit et les limites applicables. Utilisez ces concepts pour planifier votre intégration et comprendre la télémétrie à travers le Microsoft OpenTelemetry Distro, le SDK d’observabilité Agent 365 déprécié, et l’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 :

Path Description
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.
SDK d’observabilité de l’Agent 365 obsolète L’ancien SDK. Les intégrations existantes continuent de fonctionner, mais n'en utilisez pas pour de nouvelles intégrations. L’article inclut des guides de migration.
Direct OTel Le chemin OTLP/HTTP brut. Utilisez-le uniquement si vous avez déjà un pipeline OpenTelemetry en place, si votre framework d'agents ne peut pas utiliser la distribution Microsoft OpenTelemetry, ou si votre agent est dans un langage que la distribution ne prend pas encore en charge (comme 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 d’observabilité de l’Agent 365

Terme Description
Id d’application (appId) L’identifiant d’application délivré lorsqu’une application Microsoft Entra ou un identifiant d’agent Microsoft Entra Agent ID est enregistré.
- Égal à OAuthclient_id, et non à l’ID d’objet Microsoft Entra.
- Dans tout ces documents, « agent id » et « blueprint id » signifient tous deux un appId.
Conversation Un fil logique d’interactions avec les agents, comme un fil de discussion Teams.
- Identifié par gen_ai.conversation.id.
- La clé de jointure principale pour une exécution.
Channel La surface sur laquelle l’agent se déplace : msteams, outlook, web, et ainsi de suite.
Exécuter Un message utilisateur en entrée, une réponse d’agent en sortie. Modélisé comme un arbre de spans OTel spans partageant un traceId.

Comment fonctionne l’observabilité de l’Agent 365

Pour un aperçu de l’Agent 365 et de la télémétrie qu’il collecte, voir Aperçu 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 d’observabilité de l’Agent 365

Le schéma suivant montre comment la télémétrie des agents passe par l’authentification et l’ingestion de l’observabilité de l’Agent 365 vers les expériences Microsoft 365 en aval.

Diagramme de flux de données d’observabilité Agent 365.

Modèles d’identité

Pour une explication complète des modèles d’identité d’agent (enregistrement standard de l’application Microsoft Entra vs. blueprint d’identité d’agent Identifiant d’assistant Microsoft Entra, y compris les coéquipiers IA), voir Identité d’agent. Votre choix de modèle d’identité détermine le flux d’authentification et le point de terminaison que vous utilisez.

Une identité d’agent dérivée du blueprint devient une instance d’agent enregistrée à l’Agent 365 seulement après la fin de l’enregistrement de l’Agent 365, par exemple via a365 setup all. Créer une identité Microsoft Entra seule ne permet pas d'enregistrer l'instance. Les enregistrements standards des applications Microsoft Entra, comme ceux utilisés par les agents du moteur personnalisé, ne sont pas des instances d’agent enregistrées.

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 de l’Agent 365 pour connaître le chemin d’entrée approprié.

Authentication

L’authentification dépend du fait que votre service s’authentifie lui-même ou s’authentifie au nom d’un utilisateur. Cette distinction détermine le flux OAuth, la revendication dans le jeton qui contient l’autorisation, et la route 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. Une identité non enregistrée nécessite le rôle Agent365.Observability.OtelWrite d’application. Une instance d’agent enregistrée auprès d’Agent 365 peut utiliser un jeton uniquement applicatif sans ce rôle.
    • 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).
    • Demande de 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.

De plus, chaque span que vous envoyez doit avoir gen_ai.agent.id défini sur le même appId. Le serveur valide l’identité de l’agent dans la charge utile par rapport à l’agent authentifié et rejette les discordances. 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 les identités non enregistrées sur le flux autonome (S2S / client credentials). Terres visées par la roles revendication. Sélectionné par <resource>/.default.
  • Étendue déléguée pour le flux OBO. Terres visées par la scp revendication. Sélectionné par <resource>/Agent365.Observability.OtelWrite (ou <resource>/.default).

Sur la route S2S, une instance d’agent enregistrée Agent 365 peut effectuer une exportation à l’aide d’un jeton uniquement applicatif qui ne comporte aucun rôle Agent365.Observability.OtelWrite. Il n’a pas besoin d’une autorisation d’observabilité ni d’un consentement administrateur pour l’exportation de télémétrie. Une identité non enregistrée nécessite toujours le rôle de l’application, et le flux délégué nécessite toujours l’étendue déléguée ainsi que le consentement de l’administrateur.

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.

Ajoutez la permission à votre application

  • Pour une inscription d’application Microsoft Entra standard : dans le portail Azure, ajoutez Agent365.Observability.OtelWrite sous Autorisations API dans l’inscription d’application de l’agent. Utilisez le rôle d’application pour S2S et la portée déléguée pour OBO.
  • Pour une instance d’agent dérivée de blueprint sur la route S2S : complétez l’enregistrement Agent 365 pour l’instance agent. Une instance enregistrée n’a pas besoin de la permission de l’API d’Observabilité ni du consentement administrateur pour exporter la télémétrie sur la route S2S.
  • Pour une instance d’agent dérivée du blueprint sur la route déléguée : ajoutez le Agent365.Observability.OtelWrite scope délégué au blueprint afin que les instances d’agent l’héritent. Consultez Configurer les autorisations héritables pour les modèles d’identité d’agent. Pour l’ajouter avec la CLI de l’Agent 365, voir Permissions d’observabilité.

Avant que les jetons ne comportent un rôle ou une portée requis, un administrateur du locataire du client doit donner son consentement. Consultez Autoriser les agents à accéder aux ressources Microsoft 365.

Sans consentement, l’acquisition du jeton échoue avec AADSTS65001 (The user or administrator has not consented to use the application with ID...) ou le jeton est émis sans la revendication roles ou scp, et le point de terminaison d’ingestion rejette la requête avec 403.

Une instance d’agent enregistrée dans Agent 365 qui exporte sur la route S2S n’a pas besoin du consentement de l’administrateur Observabilité. Le consentement reste requis pour les identités S2S non enregistrées qui utilisent le rôle de l’application et pour toutes les exportations via la route déléguée qui utilisent le périmètre délégué.

Lorsque le consentement est requis, il est accordé une fois par tenant et s’applique à chaque instance construite à partir d’un modèle par la suite. La reconsente n’est nécessaire que lorsqu’une nouvelle autorisation est ajoutée au blueprint.

Limites et conditions de suppression

Connaître ces limites à l’avance évite les surprises lors de l’intégration. Certaines défaillances renvoient un statut HTTP réussi même si la réponse indique que la télémétrie n’a pas été acceptée.

Limites au niveau du câble :

  • Vous devez inclure api-version=1 dans chaque requête.
  • La taille maximale du corps de la requête est de 1 Mo. Les demandes plus volumineuses retournent 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.

Les intégrations tierces déjà intégrées qui utilisent l’authentification S2S peuvent appeler le point de terminaison d’éligibilité du locataire dans le cadre d’une vérification préalable facultative avant d’envoyer la télémétrie. Lorsque vous utilisez le point de terminaison, fiez-vous à sa décision au lieu d’inférer l’éligibilité uniquement par consentement ou licence. Une enabled: false réponse signifie que le locataire n’est pas actuellement éligible. Un sans-corps 503 Service Unavailable signifie que l’éligibilité ne peut pas être déterminée. Réessayez en fonction de son en-tête Retry-After si vous avez toujours besoin d’un résultat d’éligibilité.

Réponses d’erreur :

  • 403 Forbidden: Un jeton qui manque du rôle ou du scope requis dans l’application, ou {agentId} dans l’URL, ne correspond pas au appid ou azp de votre jeton.
  • 413 Payload Too Large: Le corps du message dépasse 1 Mo.
  • 429 Too Many Requests: Limite de débit atteinte ; respectez Retry-After: 1 et réessayez après un délai aléatoire.

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

# Pathologie Comportement
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. La requête retourne 200 OK, mais chaque entrée de results span a un rejected statut et la raison tenant_not_licensed.

Un 200 OK ne prouve pas l’ingestion. Inspectez la réponse results, et utilisez le flux de vérification pour confirmer que les données arrivent.

Où apparaissent les données d’observabilité de l’Agent 365

Une fois que vous acceptez les spans, ils apparaissent dans trois expériences destinées aux clients. Les trois expériences dépendent d’un span invoke_agent valide à la racine de l’exécution. Une exécution avec seulement des étendues chat, execute_tool ou output_messages est interrogeable dans la recherche avancée Defender (la table CloudAppEvents), mais elle est invisible dans toutes les autres interfaces.

Experience Description
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 n’ingère que les lignes invoke_agent : les agents sans télémétrie invoke_agent n’apparaissent pas dans l’inventaire, et les exécutions qui n’émettent que chat, execute_tool ou output_messages sont invisibles ici. Le centre d’administration lit des attributs tels que l’ID de l’agent, le nom de l’agent, l’ID du blueprint, l’identité de l’appelant, l’ID de la conversation, le canal et le statut d’erreur à partir de l’élément invoke_agent.
Microsoft Purview L’activité des agents est également accessible aux administrateurs de conformité dans Microsoft Purview, où ils peuvent configurer les règles de gestion des données et de politiques lors des exécutions d’agents (prévention de la perte de données, rétention, conformité des communications, etc.). Les attributs sur lesquels s’appuient les stratégies Purview (identifiant de l’agent, identifiant du plan, identité de l’appelant, conversation, canal, requête et messages de réponse) proviennent de l’élément invoke_agent et de ses descendants.

Étapes suivantes

  • Last updated on