Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
C’est la spécification canonique attribut par attribut utilisée par le pipeline d’ingestion de l’Agent 365. Chaque plage ingérée par l’Agent 365 – qu’elle soit émise par la distribution OpenTelemetry Microsoft, le SDK Agent 365, ou envoyée via direct OTel – doit y être conforme. Chaque entrée liste les types d’opérations auxquels l’attribut s’applique, s’il est obligatoire, le nom du champ dans lequel votre valeur apparaît pour les requêtes de chasse avancée (là où il existe), et l’impact si vous le sautez.
Si vous utilisez le SDK ou la distribution, le SDK émet ces attributs pour vous et la section Choix de valeurs ne s’applique que lorsque vous devez remplacer un défaut. Si vous êtes sur le chemin OTel direct, vous émettez chaque attribut manuellement ; pour savoir comment les assembler en requête, voir le guide d’intégration.
Attribute table
Toutes les valeurs sont envoyées comme stringValue - les comptes de jetons doivent être "42" (non 42) ; les ports doivent être "443" (non 443).
Opération Légende.IA = invoke_agent, ET, = execute_toolCH, = chatOM, = output_messagesTous = s’appliquent à chaque opération.
Required legend.
- M: mandatory.
- M*¹ : obligatoire uniquement pour les agents incarnés (l’agent possède son propre compte utilisateur Identifiant d’assistant Entra).
- M*² : obligatoire uniquement pour les appels entre agents.
-
M*³ : obligatoire uniquement pour les travées non racinaires. La racine
invoke_agentn’a pas de parent. - O*⁴ : optionnel, significatif seulement lorsque l’état d’étendue est Error.
- O: optional.
- N/A : ne pas émettre. L’agent 365 se remplit automatiquement.
La colonne « champ RawEventData » nomme une clé JSON à l’intérieur CloudAppEvents.RawEventData de laquelle la requête canonique de chasse avancée dans la vérification de l’ingestion analyse les données. Une cellule vierge signifie que l'attribut est pas exposé dans CloudAppEvents aujourd'hui — vous devriez toujours l'émettre (selon la colonne Required) car l'Agent 365 l'utilise pour l'ingestion, la résolution parent, et les vues d'activité de Microsoft Defender, mais il n'est pas directement interrogable depuis Microsoft Defender chasse avancée aujourd'hui.
Note
L’Agent 365 remplit automatiquement les champs d’enregistrement statiques (Id, RecordType, Workload, UserType, Version) ainsi que les identifiants de requête/réponse générés.
| Attribute | Applies to | Required | RawEventData field | Notes / impact en cas d’absence |
|---|---|---|---|---|
gen_ai.operation.name |
All | M | Operation |
Un des invoke_agent, execute_tool, chat, output_messages. Span perdu s’il manque ou non reconnu. |
microsoft.tenant.id |
All | M | OrganizationId |
L’URL {tenantId} est autoritaire. Si vous activez cela et que la demande n’est pas d’accord, la demande est rejetée (403). |
gen_ai.agent.id |
All | M |
TargetAgentId (IA, également de haut niveau AgentId) ; AgentId (ET, CH) |
L’application d’appel est appId. Il faut correspondre à l’URL {agentId} et à l’application authentifiée. Le Mismatch revient 403. |
gen_ai.agent.name |
All | M |
TargetAgentName (IA) ; AgentName (ET, CH) |
Defender / centre d’administration affichent le GUID brut au lieu d’un nom en cas de défaut. |
microsoft.a365.agent.blueprint.id |
All | M |
TargetAgentBlueprintID (IA) ; AgentBlueprintId (ET, CH) |
Le plan est appId. Pour les applications Entra standard sans blueprint, réutilisez l’appID de l’agent. Les roll-ups de blueprint dans le centre d’administration se cassent sinon. |
gen_ai.agent.description |
All | O | -- | La vue détaillée dans le centre administratif est vide pour l’agent. |
gen_ai.agent.type |
All | O |
PlatformTargetAgentType (IA) ; PlatformAgentType (ET) ; CopilotEventData.PlatformAgentType (CH) |
Une étiquette pour votre système d’identité, associée au microsoft.a365.agent.platform.id moment où l’agent n’a pas d’immatriculation Entra. Texte libre ; Choisissez une valeur qui identifie de manière unique votre système d’identité. Omettez lorsque l’agent a une immatriculation Entra — l’Agent 365 se classe automatiquement. N'utilisez pas les valeurs Microsoft-réservées (voir Picking values). |
microsoft.a365.agent.platform.id |
All | O |
PlatformTargetAgentId (IA, également de haut niveau AlternateId) ; PlatformAgentId (ET, CH) |
L’identifiant unique de l’agent dans votre système d’identité non-Entra. Free-form text. Posez ensemble avec gen_ai.agent.type. Omettez lorsque l’agent a une immatriculation Entra.
Voir Valeurs de picking. |
gen_ai.conversation.id |
All | M |
ConversationId (IA, ET) ; CopilotEventData.ConversationId / CopilotEventData.ThreadId (CH) |
La clé principale de joint pour une partie. Sans cela, la run n'apparaît pas dans les vues d'activité des agents Defender ni dans le centre d'administration. |
microsoft.channel.name |
All | M |
ChannelName (IA, ET) |
La surface sur laquelle l’agent s’écoule. Utilisez un petit jeton minuscule ; Les valeurs canoniques utilisées aujourd’hui par les filtres Defender / Admin Center sont et . Les chaînes personnalisées (par exemple web, <your-product-name>) sont acceptées mais ne pivotent pas dans les filtres de canal intégrés. Même valeur sur chaque travée.
Voir Valeurs de picking. |
microsoft.channel.link |
All | O | -- | Channel deep-link. |
microsoft.session.id |
All | O | SessionIdentity |
La session pivote vide si elle manque. |
microsoft.session.description |
All | O | -- | Session description. |
microsoft.conversation.item.link |
All | O | -- | Lien profond vers le message. |
correlation.id |
All | O | -- | Cross-service tracing. Pas réapparu dans la chasse avancée aujourd’hui. |
operation.source |
All | O |
InvokeSource (IA) |
Identifiant du SDK / service émettant la télémétrie. Peut être un attribut de Ressource. |
client.address |
IA, ET, CH | M |
ClientIP (IA, ET) |
Caller IP. Enquête basée sur IP bloquée s’il est vide. |
server.address |
IA, ET, CH | M |
ServerAddress (IA, ET) |
Endpoint que votre service appelle. |
server.port |
IA, ET, CH | M |
ServerPort (IA) |
Encodé par chaîne (par exemple "443"). |
user.id |
IA | M | UserKey |
Microsoft Entra identifiant objet de l’appelant humain. « Qui a dirigé cet agent » est vide sans ça. |
user.email |
IA | O | UserId |
UPN de l’appelant. |
user.name |
IA | O | -- | Affichez le nom de l’appelant. |
gen_ai.input.messages |
IA, CH | M | -- | Charge utile de demande (chaîne JSON). Capturé pour une analyse en aval mais pas encore refait surface lors de chasse avancée. |
gen_ai.output.messages |
IA, CH, OM | M | -- | Charge utile de réponse (chaîne JSON). |
gen_ai.execution.type |
IA | O | -- | L’un des HumanToAgent, Agent2Agent, EventToAgent. |
microsoft.a365.agent.thought.process |
IA, CH | O | -- | Raisonnement en texte libre / chaîne de pensée. |
gen_ai.author.app.id |
OM | O | -- | ID de l’application Microsoft Entra de l’application qui a créé / a créé l’agent. |
gen_ai.tool.name |
ET | M | ToolName |
Tool name. Les vues d’utilisation des outils Defender sont vides si elles manquent. |
gen_ai.tool.type |
ET | M | ToolType |
L’un des function, Power Platform Connector, MCP Server, API, Knowledge Source, bing_grounding, code_interpreter, , . file_search |
gen_ai.tool.call.id |
ET | M | ToolId |
Identifiant pour cet appel d’outil. |
gen_ai.tool.call.arguments |
ET | M | -- | Arguments d’outils (chaîne JSON). Capturés mais pas encore remontés lors de la chasse avancée. |
gen_ai.tool.call.result |
ET | M | -- | Résultat de l’outil (chaîne JSON). |
gen_ai.tool.description |
ET | O | ToolDescription |
Tool description. |
gen_ai.tool.server.name |
ET | O | -- | Nom d’hôte du serveur d’outils. Définissez cet attribut pour les outils MCP. |
gen_ai.request.model |
CH | M | -- | Nom du modèle (par exemple, gpt-4o). Capturés mais pas encore remontés lors de la chasse avancée. |
gen_ai.provider.name |
CH | M | -- | Nom du fournisseur (par exemple, openai). |
gen_ai.usage.input_tokens |
CH | O | -- | Nombre de jetons d’entrée, encodé par chaîne. |
gen_ai.usage.output_tokens |
CH | O | -- | Nombre de jetons de sortie, encodé par chaîne. |
gen_ai.response.finish_reasons |
CH | O | -- | Finish reason(s). |
microsoft.a365.caller.agent.id |
IA | M*² | -- | Appel à l’agent appId. Obligatoire pour un agent à un agent. |
microsoft.a365.caller.agent.name |
IA | M*² | -- | Nom d’affichage de l’agent appelé. |
microsoft.a365.caller.agent.blueprint.id |
IA | M*² | AgentBlueprintId |
Appel à l’appID du blueprint de l’agent. Nécessaire pour l’A2A incarné. |
microsoft.a365.caller.agent.user.id |
IA | M*² | -- | Appel de l’identifiant utilisateur de l’agent. |
microsoft.a365.caller.agent.user.email |
IA | M*² | -- | J’appelle l’agent UPN. |
microsoft.a365.caller.agent.platform.id |
IA | N/A | -- | Réservé aux identifiants alternatifs non-Entra. |
gen_ai.caller.agent.type |
IA | N/A | -- | L’agent 365 auto-classe. |
microsoft.agent.user.id |
IA, ET, CH | M*¹ |
TargetAgentUserKey (IA) ; UserKey (ET, CH) |
ID d'objet Microsoft Entra du compte utilisateur propre à l'agent. Obligatoire pour les coéquipiers IA / agents incarnés. |
microsoft.agent.user.email |
IA, ET, CH | O*¹ |
UserId (ET, CH) |
UPN du compte utilisateur de l’agent. |
span.SpanId |
All | M | OpId |
Le SDK OTel émet cela. |
span.ParentSpanId |
All | M*³ | ParentId |
Obligatoire uniquement pour les travées non racinaires ; La racine invoke_agent n’en a pas. |
span.StartTimeUnixNano |
All | M | Niveau TimeGenerated supérieur (également CreationTime dans RawEventData) |
Unix Epoch Nanos en tant que chaîne. |
span.EndTimeUnixNano |
All | M |
CompletionTime (IA, ET) ; CopilotEventData.CompletionTime (CH) |
La durée ne peut pas être calculée en cas de disparition. |
span.Status.Message |
All | O*⁴ |
ErrorMessage (IA, ET) ; CopilotEventData.ErrorMessage (CH) |
La cause principale des échecs est vide si elle manque. |
span.Status.Code |
All | O*⁴ |
ErrorType (IA) ; CopilotEventData.ErrorType (CH) |
Catégorie d’erreur vide si elle manque. |
Note
Plusieurs attributs que vous émettez (tels que les arguments / résultats de l'outil, les paramètres du modèle et les liens profonds de canal) sont acceptés par l'Agent 365 et utilisés par les vues Microsoft Defender en aval, mais ne sont pas encore exposés en tant que clé JSON CloudAppEvents.RawEventData. Définissez-les de toute façon selon la colonne Requise – ils pourraient être ajoutés à la charge utile de chasse dans une future version.
Choisir des valeurs quand on n’a pas de valeur naturelle
Certains attributs requis décrivent des concepts qui n’existent peut-être pas dans l’architecture de votre agent. Si la valeur naturelle n’est pas là, voici ce qu’il faut régler à la place. Ne laissez pas un champ obligatoire vide — même un GUID entièrement zéro cachera votre run à certaines expériences en contact avec les clients.
| Question / scénario | Field(s) | Que régler |
|---|---|---|
| Mon agent est un enregistrement standard de l’application Entra (pas construit à partir d’un plan Identifiant d’assistant Entra). | gen_ai.agent.id |
L’appId de l’application Entra. |
| ↑ même scénario | microsoft.a365.agent.blueprint.id |
Réutilisez la même valeur que gen_ai.agent.id (l’appId de l’agent). Le schéma nécessite une valeur non vide ; Réutiliser l’AppId de l’agent est la valeur sûre par défaut lorsqu’il n’y a pas de blueprint. |
| Mon agent est construit à partir d’un plan Identifiant d’assistant Entra - une ou plusieurs identités d’agent créées à partir du même plan. | gen_ai.agent.id |
L’appId de l’identité de l’agent (l’appId de l’instance, pas celui du blueprint). |
| ↑ même scénario | microsoft.a365.agent.blueprint.id |
Le plan est appId. Toutes les instances frappées à partir du même plan partagent cette valeur. |
| L’appelant est un utilisateur humain, pas un autre agent. | Tous microsoft.a365.caller.agent.* et gen_ai.caller.agent.* attributs |
Omit. Ils ne sont obligatoires que dans les scénarios agent à agent. |
| En agent-à-agent : l’agent appelant est une application Entra standard (sans blueprint). | microsoft.a365.caller.agent.blueprint.id |
Réutilisez l’appID de l’agent appelant. |
| Mon agent n’est pas un coéquipier IA - il n’a pas son propre compte utilisateur dans le locataire. | Tous les microsoft.agent.user.* attributs |
Omit. Ils ne sont obligatoires que lorsque l'agent possède son propre compte utilisateur Identifiant d’assistant Entra. |
| Mon agent n’a aucune notion d’une session au-delà d’une seule exécution. | microsoft.session.id |
Optionnel - omettre. Si vous voulez que chaque partie soit une session à part, réglez un GUID par exécution. |
| Mon agent n’a aucune notion de conversation (one-shot, sans patrie). | gen_ai.conversation.id |
Générez un nouveau GUID à chaque partie. Le champ est obligatoire ; Le sauter supprime l’exécution des vues d’activité des agents Defender et du Microsoft 365 admin center. |
| L’appelant n’a pas d’IP (par exemple, un déclencheur programmé autonome). | client.address |
Utilisez un substitut stable que vous contrôlez (par exemple, "0.0.0.0"). Le champ est obligatoire ; une valeur vide supprime la course des pivots d’investigation basés sur IP. |
| L’agent est en cours ; Il n’y a pas de « serveur » séparé qui est appelé. | server.address / server.port |
Utilisez le nom d’hôte de la machine qui a exécuté l’agent (par exemple, myagent.example.com) et le port sur lequel votre point d’écoute écoute. Obligatoire même lorsqu’il n’y a pas de service séparé en aval. |
Mon chat Span n’utilise pas de token de modèle. |
gen_ai.usage.input_tokens / gen_ai.usage.output_tokens |
Optionnel - omettre. Si vous avez des décomptes approximatifs, envoyez-les comme stringValue. |
| Mon span n’a aucune erreur à signaler. |
span.Status.Message, span.Status.Code |
Mettez le statut OTel à OK (code numérique 1) et omettez le message. Le pipeline ne consulte ces champs que lorsque le statut est Error. |
| Mon agent utilise un système d’identité non-Entra (l’agent n’a pas d’immatriculation Entra). |
microsoft.a365.agent.platform.id et gen_ai.agent.type |
Mets les deux, sur chaque travée.
platform.id est l’identifiant unique de l’agent dans votre système d’identité ; agent.type est une courte étiquette qui identifie à quel système d’identité il s’agit. Les deux sont du texte libre – choisissez ce qui a du sens pour votre système.
N'utilisez pas les valeurs de type Microsoft-réservées : CustomBuiltAgentsUsingSDK, CopilotStudio, Foundry, DeclarativeAgent, Custom (ces valeurs sont réservées aux surfaces Microsoft internes). L’application appelante que vous authentifiez nécessite toujours une inscription Entra pour utiliser ces routes - la paire d’identifiant alternatif décrit un agent cible , pas l’appelant. |
Quelle valeur devrais-je y microsoft.channel.nameaccorder ? |
microsoft.channel.name |
La surface sur laquelle l’agent s’écoule. Defender et admin center filtrent la touche à partir de la chaîne littérale, donc utilisez un jeton court, stable et minuscule. Aujourd’hui, les valeurs canoniques sont msteams et outlook; les surfaces couramment orientées vers le client utilisent webégalement , office, sharepoint, ou <your-product-name>. Choisissez une valeur et tenez-vous à elle – les outils ne peuvent pas concilier msteams et Microsoft Teams comme même canal. |
Dois-je régler gen_ai.agent.type? |
gen_ai.agent.type |
Seulement si vous êtes aussi en train de régler microsoft.a365.agent.platform.id (par exemple, si votre agent n’a pas d’immatriculation Entra). Le duo indique à l’Agent 365 de quel système d’identité l’agent provient. Choisissez une étiquette courte qui identifie de manière unique votre système d’identité.
N'utilisez pas CustomBuiltAgentsUsingSDK, CopilotStudio, Foundry, DeclarativeAgent ou Custom – ces valeurs sont réservées à l'usage interne Microsoft. Pour les agents enregistrés chez Entra, il faut omettre le champ ; L’agent 365 le remplit en arrière. |
Quel autre plan de traitement kind original devrais-je définir sur mes travées ? |
span.kind |
Utilisez la valeur entière enum, et non la chaîne proto-enum - 1 (INTERNAL), 2 (SERVER), 3 (CLIENT), 4 (), (PRODUCER), 5 (CONSUMER). L’agent 365 accepte l’une de ces catégories et ne déduit pas le comportement visible par le client à partir de kind, donc 1 (INTERNAL) est un défaut sûr pour chaque span. Si vous voulez que le type reflète la forme de l’appel, INTERNAL pour / output_messagesinvoke_agentet CLIENT pour chat / execute_tool est raisonnable. |