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 d’abandon et emplacement d’affichage des données) s’applique à tous les scénarios.

Choisir votre chemin d’intégration

Trois scénarios produisent 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 Le SDK hérité. 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 de l’assistant en sortie. Modélisé sous la forme d’une arborescence de spans OTel partageant un même 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é.

Authentification

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 de jeton qui contient l’autorisation, et le chemin de l’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 Agent365.Observability.OtelWrite rôle 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’assistant peut participer aux deux flux, par exemple un coéquipier IA qui exécute également chaque nuit un processus autonome de synthèse. Pour plus d’informations, consultez 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 blueprint, {agentId} est l’appId de l’identité de l’assistant, et non l’appId du blueprint.

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 permet de détecter le mélange accidentel de spans provenant de plusieurs assistants dans une même requête.

Une étendue (déléguée) ou un rôle d’application (application) correspond à l’autorisation nommée que Microsoft Entra émet dans le jeton d’accès. Pour la télémétrie 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 voie S2S, une instance d’assistant inscrite auprès d’Agent 365 peut effectuer une exportation à l’aide d’un jeton d’application uniquement ne disposant pas du 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 inscrite 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 d’API dans l’inscription d’application de l’assistant. 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 contiennent le rôle ou l’étendue nécessaire, 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 (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’assistant inscrite auprès d’Agent 365 qui effectue une exportation via la voie S2S ne nécessite pas le consentement de l’administrateur pour Observabilité. Le consentement reste obligatoire pour les identités S2S non inscrites qui utilisent le rôle d’application, ainsi que pour toutes les exportations effectuées via la voie déléguée qui utilisent l’étendue des autorisations déléguées.

Lorsque le consentement est requis, il est accordé une fois par locataire et s’applique ensuite à chaque instance construite à partir d’un blueprint. 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. En cas de 429, respectez Retry-After (défini à 1 seconde) et appliquez un délai d’attente progressif avec gigue.

Les intégrations tierces intégrées qui utilisent l’authentification S2S peuvent appeler le point de terminaison d’éligibilité du locataire en tant que vérification préalable facultative avant d’envoyer des données de 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 code 503 Service Unavailable sans corps de réponse signifie que l’éligibilité n’a pas pu ê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 appliquez un délai d’attente progressif avec gigue.

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} Abandon par span. Apparaît dans partialSuccess.rejectedSpans + errorMessage.
2 Aucun utilisateur du locataire client ne possède de licence Microsoft 365 E7 ou Microsoft Agent 365 attribuée. 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. Ces 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 locataire et les analystes de sécurité peuvent explorer en détail les exécutions, les outils et les appels d’inférence individuels. Les vues d’activité de l’assistant reposent sur le span invoke_agent ; sans celui-ci, l’exécution n’y apparaît pas, même si les spans enfants peuvent toujours faire l’objet de requêtes au moyen de 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é des assistants apparaît également dans les vues d’inventaire et de sécurité des assistants utilisées par les administrateurs de locataire pour gérer les assistants dans leur locataire. Le centre d’administration n’ingère que les lignes invoke_agent : les assistants 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