Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Esta é a especificação canónica atributo a atributo usada pelo pipeline de ingestão do Agente 365. Cada espaço ingerido pelo Agente 365 - seja emitido pela Distribuição OpenTelemetry Microsoft, pelo SDK Agente 365, ou enviado por diretamente OTel - deve estar em conformidade com ele. Cada entrada lista os tipos de operações a que o atributo se aplica, se é obrigatório, se o nome do campo do teu valor aparece para consultas de caça avançada (quando existe), e o impacto se o ignorares.
Se estiveres a usar o SDK ou a distribuição, o SDK emite estes atributos por ti e a secção Escolhendo valores aplica-se apenas quando precisas de sobrescrever um padrão. Se estiveres no caminho direto OTel, emites todos os atributos manualmente; para saber como os montar num pedido, consulte o guia de Integração.
Attribute table
Todos os valores são enviados como stringValue - as contagens de tokens devem ser "42" (não 42); portas devem ser "443" (não 443).
Operação Lenda.IA = invoke_agent, ET, = execute_toolCH, = chatOM, = output_messagesAll = aplica-se a todas as operações.
Required legend.
- M: mandatory.
- M*¹: obrigatório apenas para agentes incorporados (o agente tem a sua própria conta de utilizador ID do Agente Entra).
- M*²: obrigatório apenas para chamadas entre agentes.
-
M*³: obrigatório apenas para vãos que não sejam raízes. A raiz
invoke_agentnão tem progenitor. - O*⁴: opcional, só relevante quando o estado de expansão é Erro.
- O: optional.
- N/A: não emitas. O Agente 365 preenche automaticamente.
A coluna "campo RawEventData" nomeia uma chave JSON dentro CloudAppEvents.RawEventData da qual a consulta canónica de caça avançada em Verificação de Ingestão analisa. Uma célula em branco significa que o atributo está not exposto em CloudAppEvents hoje — deves continuar a emiti-lo (segundo a coluna Required) porque o Agente 365 usa-o para ingestão, resolução parental e as vistas de atividade do agente da Microsoft Defender, mas não é consultável diretamente a partir de Microsoft Defender caça avançada atualmente.
Note
O Agente 365 preenche automaticamente os campos de registo estático (Id, RecordType, Workload, UserType, Version) e os IDs de pedido/resposta gerados.
| Attribute | Applies to | Required | RawEventData field | Notas / impacto em caso de falta |
|---|---|---|---|---|
gen_ai.operation.name |
All | M | Operation |
Um de invoke_agent, execute_tool, chat, output_messages. Span perdido se estiver ausente ou não reconhecido. |
microsoft.tenant.id |
All | M | OrganizationId |
O URL {tenantId} é autoritativo. Se definires isto e ele discordar, o pedido é rejeitado (403). |
gen_ai.agent.id |
All | M |
TargetAgentId (IA, também de topo AgentId); AgentId (ET, CH) |
A app de chamadas é appId. Tem de corresponder ao URL {agentId} e à aplicação autenticada. O desajuste devolve 403. |
gen_ai.agent.name |
All | M |
TargetAgentName (IA); AgentName (ET, CH) |
Defender / centro de administração mostram o GUID bruto em vez de um nome, caso falte. |
microsoft.a365.agent.blueprint.id |
All | M |
TargetAgentBlueprintID (IA); AgentBlueprintId (ET, CH) |
A planta é appId. Para aplicações Entra padrão sem blueprint, reutilize o appID do agente. Os roll-ups de blueprint no centro de administração quebram caso contrário. |
gen_ai.agent.description |
All | O | -- | A vista de detalhes no centro de administração está em branco para o agente. |
gen_ai.agent.type |
All | O |
PlatformTargetAgentType (IA); PlatformAgentType (ET); CopilotEventData.PlatformAgentType (CH) |
Uma etiqueta para o seu sistema de identidade, associada ao microsoft.a365.agent.platform.id momento em que o agente não tem registo Entra. texto livre; Escolha um valor que identifique de forma única o seu sistema de identidade. Omita quando o agente tiver uma matrícula Entra — Agente 365 auto-classifica. Não use os valores Microsoft-reservados (ver Picking values). |
microsoft.a365.agent.platform.id |
All | O |
PlatformTargetAgentId (IA, também de topo AlternateId); PlatformAgentId (ET, CH) |
O ID único do agente no seu sistema de identidade não-Entra. Free-form text. Conjunto com gen_ai.agent.type. Omita quando o agente tiver registo no Entra.
Veja Escolher valores. |
gen_ai.conversation.id |
All | M |
ConversationId (IA, ET); CopilotEventData.ConversationId / CopilotEventData.ThreadId (CH) |
A chave principal de junção para uma corrida. Sem ele, a execução não aparece nas vistas de atividade de agentes do Defender nem no centro de administração. |
microsoft.channel.name |
All | M |
ChannelName (IA, ET) |
A superfície onde o agente corre. Use uma ficha minúscula curta; Os valores canónicos usados hoje pelos filtros Defender / Admin Center são e . Strings personalizadas (por exemplo web, <your-product-name>) são aceites mas não mudam de pivô nos filtros de canal incorporados. O mesmo valor em todos os vãos.
Veja Escolher valores. |
microsoft.channel.link |
All | O | -- | Channel deep-link. |
microsoft.session.id |
All | O | SessionIdentity |
A sessão fica em branco se estiver em falta. |
microsoft.session.description |
All | O | -- | Session description. |
microsoft.conversation.item.link |
All | O | -- | Link profundo para a mensagem. |
correlation.id |
All | O | -- | Cross-service tracing. Não surgiu na caça avançada atualmente. |
operation.source |
All | O |
InvokeSource (IA) |
Identificador do SDK / serviço que emite a telemetria. Pode ser um atributo de Recurso. |
client.address |
IA, ET, CH | M |
ClientIP (IA, ET) |
Caller IP. Investigação baseada em IP bloqueada se estiver em branco. |
server.address |
IA, ET, CH | M |
ServerAddress (IA, ET) |
Endpoint que o seu serviço está a chamar. |
server.port |
IA, ET, CH | M |
ServerPort (IA) |
Codificado por strings (por exemplo "443"). |
user.id |
IA | M | UserKey |
Microsoft Entra object ID do chamador humano. "Quem mandou este agente" fica em branco sem ele. |
user.email |
IA | O | UserId |
UPN do interlocutor. |
user.name |
IA | O | -- | Mostrar o nome do chamador. |
gen_ai.input.messages |
IA, CH | M | -- | Carga útil de pedido (string JSON). Capturado para análise a jusante, mas ainda não emergiu em caça avançada. |
gen_ai.output.messages |
IA, CH, OM | M | -- | Carga útil de resposta (string JSON). |
gen_ai.execution.type |
IA | O | -- | Um dos HumanToAgent, Agent2Agent, EventToAgent. |
microsoft.a365.agent.thought.process |
IA, CH | O | -- | Raciocínio em texto livre / cadeia de pensamento. |
gen_ai.author.app.id |
OM | O | -- | ID da aplicação Microsoft Entra da aplicação que criou/criou o agente. |
gen_ai.tool.name |
ET | M | ToolName |
Tool name. As vistas de utilização da ferramenta do Defender ficam em branco se estiverem em falta. |
gen_ai.tool.type |
ET | M | ToolType |
Um de function, Power Platform Connector, MCP Server, API, Knowledge Source, bing_grounding, code_interpreter, , . file_search |
gen_ai.tool.call.id |
ET | M | ToolId |
Identificador para esta chamada de ferramenta. |
gen_ai.tool.call.arguments |
ET | M | -- | Argumentos de ferramenta (string JSON). Capturado mas ainda não emergido em caça avançada. |
gen_ai.tool.call.result |
ET | M | -- | Resultado da ferramenta (cadeia JSON). |
gen_ai.tool.description |
ET | O | ToolDescription |
Tool description. |
gen_ai.tool.server.name |
ET | O | -- | Nome de host do servidor de ferramentas. Defina este atributo para as ferramentas MCP. |
gen_ai.request.model |
CH | M | -- | Nome do modelo (por exemplo, gpt-4o). Capturado mas ainda não emergido em caça avançada. |
gen_ai.provider.name |
CH | M | -- | Nome do fornecedor (por exemplo, openai). |
gen_ai.usage.input_tokens |
CH | O | -- | Contagem de tokens de entrada, codificada por string. |
gen_ai.usage.output_tokens |
CH | O | -- | Contagem de tokens de saída, codificada por string. |
gen_ai.response.finish_reasons |
CH | O | -- | Finish reason(s). |
microsoft.a365.caller.agent.id |
IA | M*² | -- | A ligar ao agente AppId. Obrigatório para agente para agente. |
microsoft.a365.caller.agent.name |
IA | M*² | -- | A chamar o nome de exibição do agente. |
microsoft.a365.caller.agent.blueprint.id |
IA | M*² | AgentBlueprintId |
A ligar ao appID do blueprint do agente. Necessário para A2A incorporado. |
microsoft.a365.caller.agent.user.id |
IA | M*² | -- | A ligar o ID de utilizador do agente. |
microsoft.a365.caller.agent.user.email |
IA | M*² | -- | A ligar para o agente UPN. |
microsoft.a365.caller.agent.platform.id |
IA | N/A | -- | Reservado para IDs alternativos que não sejam do Entra. |
gen_ai.caller.agent.type |
IA | N/A | -- | Agente 365 auto-classifica. |
microsoft.agent.user.id |
IA, ET, CH | M*¹ |
TargetAgentUserKey (IA); UserKey (ET, CH) |
ID de objeto Microsoft Entra da conta de utilizador do agente. Obrigatório para colegas de equipa controlados pela IA / agentes incorporados. |
microsoft.agent.user.email |
IA, ET, CH | O*¹ |
UserId (ET, CH) |
UPN da conta de utilizador do agente. |
span.SpanId |
All | M | OpId |
O SDK original emite isto. |
span.ParentSpanId |
All | M*³ | ParentId |
Obrigatório apenas para vãos que não sejam raízes; a raiz invoke_agent não tem nenhuma. |
span.StartTimeUnixNano |
All | M | Nível TimeGenerated superior (também CreationTime em RawEventData) |
Unix epoch nanos como uma cadeia. |
span.EndTimeUnixNano |
All | M |
CompletionTime (IA, ET); CopilotEventData.CompletionTime (CH) |
A duração não pode ser calculada se estiver em falta. |
span.Status.Message |
All | O*⁴ |
ErrorMessage (IA, ET); CopilotEventData.ErrorMessage (CH) |
A causa raiz das execuções falhadas fica vazia se estiver em falta. |
span.Status.Code |
All | O*⁴ |
ErrorType (IA); CopilotEventData.ErrorType (CH) |
Categoria de erro em branco se estiver em falta. |
Note
Vários atributos que emites (como argumentos / resultados de ferramentas, parâmetros do modelo e ligações profundas de canal) são aceites pelo Agente 365 e usados pelas vistas de Microsoft Defender a jusante, mas ainda não estão expostos como uma chave JSON CloudAppEvents.RawEventData. Defini-as pela coluna Required de qualquer forma – podem ser adicionadas à carga útil de caça numa versão futura.
Escolher valores quando não tens um natural
Alguns atributos exigidos descrevem conceitos que podem não existir na arquitetura do seu agente. Se o valor natural não estiver lá, aqui está o que definir em vez disso. Não deixe um campo obrigatório vazio — mesmo um GUID totalmente zeros esconde a sua corrida de algumas experiências com clientes.
| Pergunta / cenário | Field(s) | O que definir |
|---|---|---|
| O meu agente é um registo standard da app Entra (não construído a partir de um blueprint ID do Agente Entra). | gen_ai.agent.id |
O appID da aplicação Entra. |
| ↑ mesmo cenário | microsoft.a365.agent.blueprint.id |
Reutilize o mesmo valor que gen_ai.agent.id (o appId do agente). O esquema requer um valor não vazio; reutilizar o appID do agente é o padrão seguro quando não há blueprint. |
| O meu agente é construído a partir de um blueprint ID do Agente Entra - uma ou várias identidades de agentes criadas a partir do mesmo blueprint. | gen_ai.agent.id |
O appId da identidade do agente (o appId da instância , não o do blueprint). |
| ↑ mesmo cenário | microsoft.a365.agent.blueprint.id |
A planta é appId. Todas as instâncias cunhadas a partir do mesmo plano partilham este valor. |
| O interlocutor é um utilizador humano, não outro agente. | Todos microsoft.a365.caller.agent.* e gen_ai.caller.agent.* atributos |
Omit. São obrigatórios apenas em cenários de agente para agente. |
| No agente para agente: o agente que chama é uma aplicação Entra padrão (sem blueprint). | microsoft.a365.caller.agent.blueprint.id |
Reutilizar o appId do agente que chama. |
| O meu agente não é um colega de equipa de IA – não tem conta de utilizador própria no tenant. | Todos os microsoft.agent.user.* atributos |
Omit. São obrigatórios apenas quando o agente tem a sua própria conta de utilizador ID do Agente Entra. |
| O meu agente não tem noção de uma sessão para além de uma única corrida. | microsoft.session.id |
Opcional - omitir. Se quiseres que cada corrida seja uma sessão própria, define um GUID por execução. |
| O meu agente não tem qualquer noção de conversa (one-shot, sem estado). | gen_ai.conversation.id |
Gera um GUID novo por cada tentativa. O campo é obrigatório; ao saltá-la remove a execução das vistas de atividade do agente do Defender e do centro de administração do Microsoft 365. |
| O chamador não tem IP (por exemplo, um disparador programado autónomo). | client.address |
Use um marcador estável que controla (por exemplo, "0.0.0.0"). O campo é obrigatório; um valor vazio remove a execução dos pivots de investigação baseados em IP. |
| O agente corre em processo; Não há nenhum "servidor" separado a ser chamado. | server.address / server.port |
Use o nome de host da máquina que executou o agente (por exemplo, myagent.example.com) e a porta onde o endpoint escuta. É obrigatório mesmo quando não há serviço separado a jusante. |
O meu chat Span não tem uso de token de modelo. |
gen_ai.usage.input_tokens / gen_ai.usage.output_tokens |
Opcional - omitir. Se tiver contagens aproximadas, envie-as como stringValue. |
| O meu span não tem erro para reportar. |
span.Status.Message, span.Status.Code |
Defina o estado OTel para OK (código numérico 1) e omita a mensagem. O pipeline só consulta estes campos quando o estado é Error. |
| O meu agente usa um sistema de identidade que não é Entra (o agente não tem registo Entra). |
microsoft.a365.agent.platform.id e gen_ai.agent.type |
Coloque ambos, em cada vão.
platform.id é o ID único do agente no seu sistema de identidade; agent.type é uma etiqueta curta que identifica qual é o sistema de identidade que se identifica. Ambos são texto livre – escolhe o que fizer sentido para o teu sistema.
Não use os valores de tipo Microsoft-reservados: CustomBuiltAgentsUsingSDK, CopilotStudio, Foundry, DeclarativeAgent, Custom (estes valores são reservados para superfícies Microsoft internas). A aplicação de chamadas que acredita ainda precisa de um registo Entra para usar estas rotas – o par de id-alternativo descreve um agente-alvo , não o chamador. |
Que valor devo atribuir microsoft.channel.name? |
microsoft.channel.name |
A superfície onde o agente corre. O Defender e o admin center filtram a tecla da string literal, por isso usa um token curto, estável e minúsculo. Hoje, os valores canónicos são msteams e outlook; superfícies comuns voltadas para o cliente também usam web, office, sharepoint, ou <your-product-name>. Escolhe um valor e mantém-te fiel a ele – as ferramentas não conseguem conciliar msteams e Microsoft Teams no mesmo canal. |
Devo definir gen_ai.agent.type? |
gen_ai.agent.type |
Só se também estiveres a configurar microsoft.a365.agent.platform.id (por exemplo, o teu agente não tiver registo no Entra). A dupla diz ao Agente 365 de que sistema de identidade vem o agente. Escolhe uma etiqueta curta que identifique de forma única o teu sistema de identidade.
Não uses CustomBuiltAgentsUsingSDK, CopilotStudio, Foundry, DeclarativeAgent ou Custom – esses valores são reservados para uso interno Microsoft. Para agentes registados na Entra, omitam o campo; O Agente 365 preenche o problema. |
Que OTLP kind devo definir nos meus vãos? |
span.kind |
Use o valor inteiro do enum, não a cadeia proto-enum - 1 (INTERNAL), 2 (SERVER), 3 (CLIENT), 4 (PRODUCER), (), 5 (CONSUMER). O Agente 365 aceita qualquer um destes e não deriva comportamento visível pelo cliente a partir de kind, pelo que 1 (INTERNO) é um padrão seguro para cada span. Se quiseres que a amabilidade reflita a forma da chamada, INTERNAL for / output_messagesinvoke_agente CLIENT for chat / execute_tool é razoável. |