Riferimento all'attributo di osservabilità Agent 365

Questa è la specifica canonica attributo per attributo utilizzata dalla pipeline di ingestione dell'Agente 365. Ogni span ingerito dall'Agent 365 - sia emesso dalla Microsoft OpenTelemetry Distro/c0>, dal SDK Agent 365, sia inviato direct OTel - deve essere conforme ad esso. Ogni voce elenca i tipi di operazioni a cui si applica l'attributo, se è obbligatorio, il nome del campo che compare il tuo valore per le query avanzate di ricerca (dove esiste), e l'impatto se lo salti.

Se usi l'SDK o la distribuzione, l'SDK emette questi attributi per te e la sezione Scelta dei valori si applica solo quando devi sovrascrivere un valore predefinito. Se sei sul percorso OTel diretto, emetti manualmente ogni attributo; per come assemblarli in una richiesta, consulta la guida all'Integrazione.

Attribute table

Tutti i valori vengono inviati come stringValue - i conteggi dei token devono essere "42" (not 42); le porte devono essere "443" (not 443).

Operazione leggenda.IA = invoke_agent, ET, = execute_toolCH, = chatOM, = output_messagesAll = si applica a ogni operazione.

Required legend.

  • M: mandatory.
  • M*¹: obbligatorio solo per gli agenti incarnati (l'agente ha un proprio account utente Entra Agent ID).
  • M*²: obbligatorio solo per le chiamate da agente a agente.
  • M*³: obbligatorio solo per campate non radicanti. La radice invoke_agent non ha un genitore.
  • O*⁴: opzionale, significativa solo quando lo stato di span è Errore.
  • O: optional.
  • N/A: non emettere. L'Agente 365 si auto-popola.

La colonna "RawEventData field" nomina una chiave JSON all'interno CloudAppEvents.RawEventData della quale la query canonica advanced-hunting in Checking ingestion analizza. Una cella vuota significa che l'attributo è not esposto in CloudAppEvents oggi—dovresti comunque emetterlo (secondo la colonna Required) perché l'Agente 365 lo usa per l'ingestione, la risoluzione dei genitori e le viste agent-attività di Microsoft Defender, ma oggi non è direttamente interrogabile da Microsoft Defender advanced hunt.

Note

L'Agente 365 popola automaticamente i campi di record statici (Id, RecordType, Workload, UserType, Version) e gli ID richieste/risposta generati.

Attribute Applies to Required RawEventData field Note / impatto se manca
gen_ai.operation.name All M Operation Uno di invoke_agent, execute_tool, chat, output_messages. Span eliminato se mancante o non riconosciuto.
microsoft.tenant.id All M OrganizationId L'URL {tenantId} è autorevole. Se imposti questo e non è d'accordo, la richiesta viene respinta (403).
gen_ai.agent.id All M TargetAgentId (IA, anch'essa AgentIddi alto livello); AgentId (ET, CH) L'app di chiamata è appId. Deve corrispondere all'URL {agentId} e all'app autenticata. La discrepanza restituisce 403.
gen_ai.agent.name All M TargetAgentName (IA); AgentName (ET, CH) Defender / admin center mostrano il GUID grezzo invece di un nome se manca.
microsoft.a365.agent.blueprint.id All M TargetAgentBlueprintID (IA); AgentBlueprintId (ET, CH) Il progetto è appId. Per le app standard di Entra senza blueprint, riutilizza l'appID dell'agente. Altrimenti i roll-up dei blueprint nel centro amministrativo si rompono.
gen_ai.agent.description All O -- La vista dettagliata nel centro amministrativo è vuota per l'agente.
gen_ai.agent.type All O PlatformTargetAgentType (IA); PlatformAgentType (ET); CopilotEventData.PlatformAgentType (CH) Un'etichetta per il tuo sistema di identità, abbinata a microsoft.a365.agent.platform.id quando l'agente non ha una registrazione Entra. testo libero; Scegli un valore che identifichi in modo unico il tuo sistema di identità. Ometti quando l'agente ha una registrazione Entra: l'Agente 365 si auto-classifica. Non usare i valori riservati Microsoft (vedi Picking values).
microsoft.a365.agent.platform.id All O PlatformTargetAgentId (IA, anch'essa AlternateIddi alto livello); PlatformAgentId (ET, CH) L'ID unico dell'agente nel tuo sistema di identità non-Entra. Free-form text. Impostate insieme a gen_ai.agent.type. Ometti quando l'agente ha una registrazione Entra. Vedi Valori di picking.
gen_ai.conversation.id All M ConversationId (IA, ET); CopilotEventData.ConversationId / CopilotEventData.ThreadId (CH) La chiave principale di join per una run. Senza di esso, la run non appare nelle visualizzazioni di attività degli agenti di Defender o nel centro amministratore.
microsoft.channel.name All M ChannelName (IA, ET) La superficie su cui corre l'agente. Usa un gettone minuscolo corto; I valori canonici usati oggi dai filtri Defender / admin center sono msteams e outlook. Le stringhe personalizzate (ad esempio web, <your-product-name>) sono accettate ma non si spostano nei filtri di canale integrati. Stesso valore su ogni campata. Vedi Valori di picking.
microsoft.channel.link All O -- Channel deep-link.
microsoft.session.id All O SessionIdentity La sessione ruota vuota se manca.
microsoft.session.description All O -- Session description.
microsoft.conversation.item.link All O -- Link profondo al messaggio.
correlation.id All O -- Cross-service tracing. Non è più ricomparso nella caccia avanzata oggi.
operation.source All O InvokeSource (IA) Identificatore per l'SDK / servizio che emette la telemetria. Potrebbe essere un attributo Risorsa.
client.address IA, ET, CH M ClientIP (IA, ET) Caller IP. Indagine basata su IP bloccata se vuota.
server.address IA, ET, CH M ServerAddress (IA, ET) Endpoint che il tuo servizio sta chiamando.
server.port IA, ET, CH M ServerPort (IA) Codificato in stringhe (ad esempio "443").
user.id IA M UserKey Microsoft Entra ID oggetto del chiamante umano. "Chi ha gestito questo agente" è vuoto senza di esso.
user.email IA O UserId UPN del chiamante.
user.name IA O -- Mostra il nome del chiamante.
gen_ai.input.messages IA, CH M -- Payload richiesta (stringa JSON). Catturato per analisi a valle ma non ancora ricomparso in una caccia avanzata.
gen_ai.output.messages IA, CH, OM M -- Payload di risposta (stringa JSON).
gen_ai.execution.type IA O -- Uno di HumanToAgent, Agent2Agent, EventToAgent.
microsoft.a365.agent.thought.process IA, CH O -- Ragionamento a testo libero / catena di pensiero.
gen_ai.author.app.id OM O -- ID dell'app Microsoft Entra dell'applicazione che ha creato o creato l'agente.
gen_ai.tool.name ET M ToolName Tool name. Le viste di utilizzo degli strumenti Defender sono vuote se mancano.
gen_ai.tool.type ET M ToolType Uno di function, Power Platform Connector, MCP Server, API, Knowledge Source, bing_grounding, code_interpreter, , . file_search
gen_ai.tool.call.id ET M ToolId Identificatore per questa chiamata di strumento.
gen_ai.tool.call.arguments ET M -- Argomenti degli strumenti (stringa JSON). Catturato ma non ancora emerso in una caccia avanzata.
gen_ai.tool.call.result ET M -- Risultato dello strumento (stringa JSON).
gen_ai.tool.description ET O ToolDescription Tool description.
gen_ai.tool.server.name ET O -- Nome host del server degli strumenti. Imposta questo attributo per gli strumenti MCP.
gen_ai.request.model CH M -- Nome del modello (ad esempio, gpt-4o). Catturato ma non ancora emerso in una caccia avanzata.
gen_ai.provider.name CH M -- Nome del fornitore (ad esempio, openai).
gen_ai.usage.input_tokens CH O -- Conteggio dei token di input, codificato per stringhe.
gen_ai.usage.output_tokens CH O -- Conteggio dei token di uscita, codificato per stringhe.
gen_ai.response.finish_reasons CH O -- Finish reason(s).
microsoft.a365.caller.agent.id IA M*² -- Chiamo l'agente appId. Richiesto per agente-agente.
microsoft.a365.caller.agent.name IA M*² -- Chiamando il nome visualizzato dell'agente.
microsoft.a365.caller.agent.blueprint.id IA M*² AgentBlueprintId Chiamo l'appId-de-blueprint dell'agente. Richiesto per l'A2A incorporato.
microsoft.a365.caller.agent.user.id IA M*² -- Chiamando l'ID utente dell'agente.
microsoft.a365.caller.agent.user.email IA M*² -- Chiamo l'agente UPN.
microsoft.a365.caller.agent.platform.id IA N/A -- Riservato a ID alternativi non appartenenti a Entra.
gen_ai.caller.agent.type IA N/A -- L'Agente 365 si classifica automaticamente.
microsoft.agent.user.id IA, ET, CH M*¹ TargetAgentUserKey (IA); UserKey (ET, CH) Microsoft Entra object ID dell'account utente dell'agente. Richiesto per i compagni di squadra IA / agenti incarnati.
microsoft.agent.user.email IA, ET, CH O*¹ UserId (ET, CH) UPN dell'account utente dell'agente.
span.SpanId All M OpId L'OTel SDK emette questo.
span.ParentSpanId All M*³ ParentId Richiesto solo per campate non radicanti; La radice invoke_agent non ne ha nessuna.
span.StartTimeUnixNano All M Livello TimeGenerated superiore (sempre CreationTime in RawEventData) Unix epoch nanos come stringa.
span.EndTimeUnixNano All M CompletionTime (IA, ET); CopilotEventData.CompletionTime (CH) La durata non può essere calcolata se manca.
span.Status.Message All O*⁴ ErrorMessage (IA, ET); CopilotEventData.ErrorMessage (CH) La causa principale delle run fallite è vuota se mancante.
span.Status.Code All O*⁴ ErrorType (IA); CopilotEventData.ErrorType (CH) Categoria di errore vuota se mancante.

Note

Diversi attributi che emetti (come argomenti / risultati degli strumenti, parametri del modello e deep link di canale) sono accettati dall'Agent 365 e utilizzati dalle Microsoft Defender view a valle, ma non sono ancora esposti come chiave JSON CloudAppEvents.RawEventData. Impostali comunque secondo la colonna Required: potrebbero essere aggiunti al payload di caccia in una futura versione.

Scegliere valori quando non hai uno naturale

Alcuni attributi richiesti descrivono concetti che potrebbero non esistere nell'architettura del tuo agente. Se il valore naturale non c'è, ecco cosa impostare invece. Non lasciare un campo obbligatorio vuoto: anche un GUID tutto a zero nasconderà la tua corsa da esperienze a contatto con i clienti.

Domanda / scenario Field(s) Cosa impostare
Il mio agente è una registrazione standard dell'app Entra (non costruita su un progetto Entra Agent ID). gen_ai.agent.id L'app Entra è appId.
↑ stesso scenario microsoft.a365.agent.blueprint.id Riutilizza lo stesso valore di gen_ai.agent.id (appId dell'agente). Lo schema richiede un valore non vuoto; riutilizzare l'app ID dell'agente è il valore sicuro di default quando non c'è un blueprint.
Il mio agente è costruito da un progetto Entra Agent ID - una o molte identità di agente create dallo stesso progetto. gen_ai.agent.id L'appId dell'identità dell'agente (l'appId dell'istanza, non quello del blueprint).
↑ stesso scenario microsoft.a365.agent.blueprint.id Il progetto è appId. Tutte le istanze coniate dallo stesso progetto condividono questo valore.
Il chiamante è un utilizzatore umano, non un altro agente. Tutti microsoft.a365.caller.agent.* e gen_ai.caller.agent.* attributi Omit. Sono obbligatori solo in situazioni da agente-agente.
In agent-to-agent: l'agente chiamante è una standard app Entra (senza blueprint). microsoft.a365.caller.agent.blueprint.id Riutilizza l'appID dell'agente che chiama.
Il mio agente non è un compagno di squadra IA - non ha un proprio account utente nel tenant. Tutti microsoft.agent.user.* gli attributi Omit. Sono obbligatori solo quando l'agente ha un proprio account utente Entra Agent ID.
Il mio agente non ha idea di una sessione oltre una singola prova. microsoft.session.id Opzionale - omette. Se vuoi che ogni run sia una sessione a sé stante, imposta un GUID per ogni run.
Il mio agente non ha alcun concetto di conversazione (one-shot, apolida). gen_ai.conversation.id Genera un nuovo GUID per ogni partita. Il campo è obbligatorio; saltandolo si rimuove l'esecuzione dalle viste di attività agente di Defender e dal interfaccia di amministrazione di Microsoft 365.
Il chiamante non ha IP (ad esempio, un trigger programmato autonomo). client.address Usa un segnaposto stabile che controlli tu (ad esempio, "0.0.0.0"). Il campo è obbligatorio; un valore vuoto rimuove la run dai pivot di indagine basati su IP.
L'agente viene eseguito in corso; Non viene chiamato un "server" separato. server.address / server.port Usa il nome host della macchina che ha eseguito l'agente (ad esempio, myagent.example.com) e la porta su cui il tuo endpoint ascolta. È richiesto anche quando non c'è un servizio separato a valle.
Il mio chat span non ha alcun utilizzo di token modello. gen_ai.usage.input_tokens / gen_ai.usage.output_tokens Opzionale - omette. Se hai conteggi approssimativi, inviali come stringValue.
Il mio span non ha errori da segnalare. span.Status.Message, span.Status.Code Imposta lo stato OTel su OK (codice numerico 1) e ometti il messaggio. La pipeline consulta questi campi solo quando lo stato è Error.
Il mio agente utilizza un sistema di identità non Entra (l'agente non ha registrazione Entra). microsoft.a365.agent.platform.id e gen_ai.agent.type Imposta entrambi, su ogni campata. platform.id è l'ID univoco dell'agente nel tuo sistema di identità; agent.type è un'etichetta breve che identifica quale sistema identitario si tratta. Entrambi sono testo libero: scegli quello che ha senso per il tuo sistema. Non usare i valori di tipo riservati Microsoft: CustomBuiltAgentsUsingSDK, CopilotStudio, Foundry, DeclarativeAgent, Custom (questi valori sono riservati alle superfici Microsoft interne). L'app di chiamata che autentichi richiede comunque una registrazione Entra per utilizzare queste rotte - la coppia di ID alternativo descrive un agente target , non il chiamante.
Quale valore dovrei attribuire microsoft.channel.name? microsoft.channel.name La superficie su cui corre l'agente. Defender e admin center filtrano i tasti dalla stringa letterale, quindi usa un token corto, stabile e minuscolo. Oggi i valori canonici sono msteams e outlook; le superfici comuni rivolte al cliente usano webanch'esse , office, sharepoint, o <your-product-name>. Scegli un valore e attenti'l - gli strumenti non riescono a conciliare msteams e Microsoft Teams come lo stesso canale.
Devo impostare gen_ai.agent.type? gen_ai.agent.type Solo se stai impostando microsoft.a365.agent.platform.id anche tu (ad esempio, il tuo agente non ha registrazione Entra). La coppia dice all'Agente 365 da quale sistema di identità proviene l'agente. Scegli un'etichetta breve che identifichi in modo unico il tuo sistema identitario. Non usare CustomBuiltAgentsUsingSDK, CopilotStudio, Foundry, DeclarativeAgent o Custom - questi valori sono riservati all'uso interno Microsoft. Per gli agenti registrati Entra, ometti il campo; L'agente 365 lo riempie.
Quale OTLP kind dovrei impostare sulle mie span? span.kind Usa il valore intero di enum, non la stringa proto enum - 1 (INTERNAL), 2 (SERVER), 3 (CLIENT), 4 (PRODUCER), (), 5 (CONSUMER). Agent 365 accetta uno qualsiasi di questi e non deriva il comportamento visibile dal cliente da kind, quindi 1 (INTERNAL) è un valore predefinito sicuro per ogni span. Se vuoi che il tipo rifletta la forma della chiamata, INTERNAL per / output_messagesinvoke_agente CLIENT per chat / execute_tool è ragionevole.

Related content

  • Last updated on