Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Esta é a especificação canônica atributo por atributo usada pelo pipeline de ingestão do Agente 365. Todo intervalo ingerido pelo Agente 365 – seja emitido pela Distro
Se você estiver usando o SDK ou a distribuição, o SDK emite esses atributos para você e a seção Escolhendo valores só se aplica quando você precisa sobrescrever um padrão. Se você estiver no caminho direto OTel, emite todos os atributos manualmente; para saber como montá-los em um pedido, veja 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_agentET = execute_tool, CH, = chatOM, = output_messagesTodos = aplica-se a toda operação.
Required legend.
- M: mandatory.
- M*¹: obrigatório apenas para agentes incorporados (o agente tem sua própria conta de usuário 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 um pai. - O*⁴: opcional, só significativo quando o status de expansão é Erro.
- O: optional.
- N/A: não emita. O Agente 365 preenche automaticamente.
A coluna "RawEventData" nomeia uma chave JSON dentro CloudAppEvents.RawEventData da qual a consulta canônica avançada de caça em Verificação de Ingestão analisa. Uma célula em branco significa que o atributo está not exposto em CloudAppEvents hoje — você ainda deve emiti-lo (conforme a coluna Required) porque o Agente 365 o usa para ingestão, resolução de pais e as visões de atividade do agente da Microsoft Defender, mas ele não pode ser consultado diretamente a partir de Microsoft Defender caça avançada hoje.
Note
O Agente 365 preenche automaticamente os campos de registro estático (Id, RecordType, Workload, UserType, Version) e os IDs de solicitação/resposta gerados.
| Attribute | Applies to | Required | RawEventData field | Notas / impacto caso falte |
|---|---|---|---|---|
gen_ai.operation.name |
All | M | Operation |
Uma opção entre invoke_agent, execute_tool, chat, output_messages. O espaço caía se faltava ou não reconhecido. |
microsoft.tenant.id |
All | M | OrganizationId |
A URL {tenantId} é autoritativa. Se você configurar isso e ele discordar, o pedido é rejeitado (403). |
gen_ai.agent.id |
All | M |
TargetAgentId (IA, também de nível AgentIdsuperior); AgentId (ET, CH) |
O app de chamadas é appId. Deve corresponder à URL {agentId} e ao app autenticado. A descorrespondência retorna 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 se estiver faltando. |
microsoft.a365.agent.blueprint.id |
All | M |
TargetAgentBlueprintID (IA); AgentBlueprintId (ET, CH) |
A planta é appId. Para aplicativos padrão do Entra 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 visualização de detalhes no centro administrativo está em branco para o agente. |
gen_ai.agent.type |
All | O |
PlatformTargetAgentType (IA); PlatformAgentType (ET); CopilotEventData.PlatformAgentType (CH) |
Um rótulo para seu sistema de identidade, combinado com microsoft.a365.agent.platform.id quando o agente não tem registro Entra. texto livre; Escolha um valor que identifique de forma única seu sistema de identidade. Omita quando o agente tiver um registro Entra — o Agente 365 autoclassifica. Não use os valores reservados Microsoft (veja Escolhendo valores). |
microsoft.a365.agent.platform.id |
All | O |
PlatformTargetAgentId (IA, também de nível AlternateIdsuperior); PlatformAgentId (ET, CH) |
O ID único do agente no seu sistema de identidade fora da Entra. Free-form text. Colocado junto com gen_ai.agent.type. Omita quando o corretor tiver um registro no Entra.
Veja Escolhendo valores. |
gen_ai.conversation.id |
All | M |
ConversationId (IA, ET); CopilotEventData.ConversationId / CopilotEventData.ThreadId (CH) |
A chave principal de junção para uma sequência. Sem ele, a execução não aparece nas visualizações de atividade de agentes do Defender ou 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 pelos filtros Defender / Admin Center hoje são e . Strings personalizadas (por exemplo web, ) <your-product-name>são aceitas, mas não mudam em filtros de canal embutidos. Mesmo valor em todos os vãos.
Veja Escolhendo valores. |
microsoft.channel.link |
All | O | -- | Channel deep-link. |
microsoft.session.id |
All | O | SessionIdentity |
A sessão fica em branco se estiver faltando. |
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 hoje. |
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 seu serviço está chamando. |
server.port |
IA, ET, CH | M |
ServerPort (IA) |
Codificado em strings (por exemplo "443", ). |
user.id |
IA | M | UserKey |
ID de objeto Microsoft Entra do chamador humano. "Quem comandava esse agente" fica em branco sem ele. |
user.email |
IA | O | UserId |
UPN do interlocutor. |
user.name |
IA | O | -- | Mostre o nome do chamador. |
gen_ai.input.messages |
IA, CH | M | -- | Carga útil de solicitação (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 do aplicativo Microsoft Entra do aplicativo que criou/criou o agente. |
gen_ai.tool.name |
ET | M | ToolName |
Tool name. As visualizações de uso da ferramenta do Defender ficam em branco se estiverem faltando. |
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 essa 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 (string JSON). |
gen_ai.tool.description |
ET | O | ToolDescription |
Tool description. |
gen_ai.tool.server.name |
ET | O | -- | Nome do host do servidor de ferramentas. Defina esse 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 provedor (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*² | -- | Ligando para o agente AppId. Obrigatório para agente para agente. |
microsoft.a365.caller.agent.name |
IA | M*² | -- | Chamando o nome de exibição do agente. |
microsoft.a365.caller.agent.blueprint.id |
IA | M*² | AgentBlueprintId |
Ligando para o appID do blueprint do agente. Exigido para A2A incorporado. |
microsoft.a365.caller.agent.user.id |
IA | M*² | -- | Ligando o ID de usuário do agente. |
microsoft.a365.caller.agent.user.email |
IA | M*² | -- | Ligando 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 autoclassifica. |
microsoft.agent.user.id |
IA, ET, CH | M*¹ |
TargetAgentUserKey (IA); UserKey (ET, CH) |
ID de objeto Microsoft Entra da conta de usuário do próprio agente. Exigido para companheiros de equipe da IA / agentes incorporados. |
microsoft.agent.user.email |
IA, ET, CH | O*¹ |
UserId (ET, CH) |
UPN da conta de usuário do agente. |
span.SpanId |
All | M | OpId |
O SDK OTel emite isso. |
span.ParentSpanId |
All | M*³ | ParentId |
Exigido 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 string. |
span.EndTimeUnixNano |
All | M |
CompletionTime (IA, ET); CopilotEventData.CompletionTime (CH) |
A duração não pode ser calculada se estiver faltando. |
span.Status.Message |
All | O*⁴ |
ErrorMessage (IA, ET); CopilotEventData.ErrorMessage (CH) |
A causa raiz das execuções fracassadas fica vazia se estiver faltando. |
span.Status.Code |
All | O*⁴ |
ErrorType (IA); CopilotEventData.ErrorType (CH) |
Categoria de erro em branco se estiver faltando. |
Note
Vários atributos que você emite (como argumentos/resultados de ferramentas, parâmetros do modelo e links profundos de canal) são aceitos pelo Agente 365 e usados pelas visualizações de Microsoft Defender a jusante, mas ainda não são expostos como uma chave JSON CloudAppEvents.RawEventData. De qualquer forma, defina eles conforme a coluna Obrigatório – eles podem ser adicionados à carga útil de caça em uma versão futura.
Escolher valores quando você não tem um natural
Alguns atributos exigidos descrevem conceitos que podem não existir na arquitetura do seu corretor. 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 zero vai esconder sua corrida de algumas experiências de atendimento ao cliente.
| Pergunta / cenário | Field(s) | O que definir |
|---|---|---|
| Meu agente é um padrão de registro do app Entra (não construído a partir de um projeto ID do agente Entra). | gen_ai.agent.id |
O appId do app 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. |
| 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 blueprint). |
| ↑ mesmo cenário | microsoft.a365.agent.blueprint.id |
A planta é appId. Todas as instâncias cunhadas a partir do mesmo projeto compartilham esse valor. |
| O chamador é um usuário humano, não outro agente. | Todos microsoft.a365.caller.agent.* e gen_ai.caller.agent.* atributos |
Omit. Eles são obrigatórios apenas em cenários de agente para agente. |
| No agente para agente: o agente que chama é um aplicativo padrão do Entra (sem blueprint). | microsoft.a365.caller.agent.blueprint.id |
Reutilize o appID do agente que chama. |
| Meu agente não é um colega de IA – ele não tem conta de usuário própria no tenant. | Todos os microsoft.agent.user.* atributos |
Omit. Eles só são obrigatórios quando o agente tem sua própria conta de usuário ID do agente Entra. |
| Meu agente não tem noção de uma sessão além de uma única execução. | microsoft.session.id |
Opcional - omit. Se quiser que cada execução seja uma sessão própria, defina um GUID para cada execução. |
| Meu agente não tem noção de conversa (one-shot, apátrida). | gen_ai.conversation.id |
Gerar um GUID novo por jogada. O campo é obrigatório; pular isso remove a execução das visualizações de atividade de agentes do Defender e do Centro de administração do Microsoft 365. |
| O chamador não possui IP (por exemplo, um gatilho programado autônomo). | client.address |
Use um marcador estável que você controle (por exemplo, "0.0.0.0"). O campo é obrigatório; um valor vazio remove a execução dos pivôs de investigação baseados em IP. |
| O agente executa o processo em andamento; Não há um "servidor" separado sendo chamado. | server.address / server.port |
Use o nome de host da máquina que rodou o agente (por exemplo, myagent.example.com) e a porta onde seu endpoint escuta. É obrigatório mesmo quando não há serviço separado a jusante. |
Meu chat Span não tem uso de token modelo. |
gen_ai.usage.input_tokens / gen_ai.usage.output_tokens |
Opcional - omit. Se você tiver contagens aproximadas, envie-as como stringValue. |
| Meu span não tem erro para reportar. |
span.Status.Message, span.Status.Code |
Defina o status OTel para OK (código numérico 1) e omita a mensagem. O pipeline só consulta esses campos quando o status é Error. |
| Meu agente usa um sistema de identidade que não é da Entra (o agente não tem registro na Entra). |
microsoft.a365.agent.platform.id e gen_ai.agent.type |
Coloque os dois em cada vão.
platform.id é o ID único do agente no seu sistema de identidade; agent.type é um rótulo curto que identifica qual sistema de identidade é esse. Ambos são texto livre – escolha o que fizer sentido para o seu sistema.
Não use os valores de tipo Microsoft-reservados: CustomBuiltAgentsUsingSDK, CopilotStudio, Foundry, DeclarativeAgent, Custom (esses valores são reservados para superfícies internas Microsoft). O aplicativo de chamadas que você autentica ainda precisa de um registro no Entra para usar essas rotas – o par de id alternativo descreve um agente alvo , não o chamador. |
Qual valor devo colocar microsoft.channel.name? |
microsoft.channel.name |
A superfície onde o agente corre. Defender e admin center filtram a tecla da string literal, então use 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>. Escolha um valor e mantenha-se nele – ferramentas não conseguem conciliar msteams e Microsoft Teams como o mesmo canal. |
Devo ajustar gen_ai.agent.type? |
gen_ai.agent.type |
Só se você também estiver configurando microsoft.a365.agent.platform.id (por exemplo, seu agente não tiver registro no Entra). A dupla informa ao Agente 365 de qual sistema de identidade o agente vem. Escolha um título curto que identifique de forma única seu sistema de identidade.
Não use CustomBuiltAgentsUsingSDK, CopilotStudio, Foundry, DeclarativeAgent ou Custom - esses valores são reservados para uso interno Microsoft. Para agentes registrados na Entra, omita o campo; O Agente 365 preenche o serviço. |
Qual 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), (CONSUMER). 5 O Agente 365 aceita qualquer um desses e não deriva comportamento visível pelo cliente a partir de kind, então 1 (INTERNAL) é um padrão seguro para todo intervalo. Se você quer que o tipo reflita a forma da chamada, INTERNAL para / output_messagesinvoke_agente CLIENT para chat / execute_tool é razoável. |