Riferimento all'attributo di osservabilità Agent 365

Questo articolo è la specifica canonica attributo per attributo utilizzata dalla pipeline di ingestione dell'Agente 365. Ogni span ingerito dall'Agent 365 - sia emesso dalla distro Microsoft OpenTelemetry, dall'obsoleto Agent 365 Observability SDK, sia inviato direttamente via OTel - deve conformarsi. 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. La sezione Picking values si applica solo quando devi sovrascrivere un valore predefinito. Se usi il percorso OTel diretto, emetti manualmente ogni attributo. Per sapere 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*1: obbligatorio solo per gli agenti incarnati (l'agente ha un proprio account utente Entra Agent ID).
  • M*2: obbligatorio solo per le chiamate da agente a agente.
  • M*3: obbligatorio solo per le campate non radici. La radice invoke_agent non ha un genitore.
  • O*4: opzionale, significativa solo quando lo stato di espansione è 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 non è esposto oggi CloudAppEvents . Dovresti comunque emetterlo (secondo la colonna Richiesto) perché l'Agent 365 lo usa per l'ingestione, la risoluzione dei genitori e le viste dell'attività dell'agente di Microsoft Defender. Tuttavia, oggi non puoi più consultarlo direttamente da Microsoft Defender advanced hunting.

Note

L'Agente 365 popola automaticamente i campi dei record statici (Id, RecordType, Workload, UserType, Version) e gli ID di richiesta e 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 valore e non è d'accordo, la richiesta viene respinta (403).
gen_ai.agent.id All M TargetAgentId (IA); 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 e il centro amministrativo 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 classifica automaticamente. 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 piccolo gettone minuscolo. I valori canonici usati oggi dai filtri di Defender e dal centro amministrativo sono msteams e outlook. Le stringhe personalizzate (ad esempio web, <your-product-name>) sono accettate ma non ruotano nei filtri di canale integrati. Usa lo 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 o 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 o 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 provider (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 reasons.
microsoft.a365.caller.agent.id IA M*2 AgentId (IA) Chiamo l'agente appId. Richiesto per agente-agente.
microsoft.a365.caller.agent.name IA M*2 AgentName (IA) Chiamando il nome visualizzato dell'agente.
microsoft.a365.caller.agent.blueprint.id IA M*2 AgentBlueprintId Chiamo l'appId-de-blueprint dell'agente. Richiesto per l'A2A incorporato.
microsoft.a365.caller.agent.user.id IA M*2 -- Chiamando l'ID utente dell'agente.
microsoft.a365.caller.agent.user.email IA M*2 -- 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*1 TargetAgentUserKey (IA); UserKey (ET, CH) Microsoft Entra object ID dell'account utente dell'agente. Richiesto per compagni di squadra IA e agenti incarnati.
microsoft.agent.user.email IA, ET, CH O*1 UserId (ET, CH) UPN dell'account utente dell'agente.
span.SpanId All M OpId L'OTel SDK emette questo.
span.ParentSpanId All M*3 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*4 ErrorMessage (IA, ET); CopilotEventData.ErrorMessage (CH) La causa principale delle run fallite è vuota se mancante.
span.Status.Code All O*4 ErrorType (IA); CopilotEventData.ErrorType (CH) Categoria di errore vuota se mancante.

Note

Agent 365 accetta diversi attributi che emetti, come argomenti e risultati degli strumenti, parametri del modello e collegamenti profondi di canale. Le viste Microsoft Defender a valle utilizzano queste caratteristiche, ma Agent 365 non le mostra ancora come CloudAppEvents.RawEventData chiave JSON. Impostali secondo la colonna Richiesto. Potrebbero essere aggiunti al carico utile di caccia in una futura versione.

Important

Nei record (IA), i campi AgentId, AgentName, e AgentBlueprintId descrivono invoke_agent l'agente chiamante, non l'agente invocato. L'Agente 365 li popola dagli microsoft.a365.caller.agent.* attributi. Quando un umano invoca il tuo agente, ometti quegli attributi, così AgentId e AgentBlueprintId appare come un GUID tutto a zero (00000000-0000-0000-0000-000000000000) e AgentName rimane vuoto nei record di audit e in Microsoft Purview. Il valore di zero è atteso per le run iniziate dagli umani. Per identificare l'agente invocato, si usano TargetAgentId, TargetAgentName, e TargetAgentBlueprintID.

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 è disponibile, imposta invece i seguenti valori. Non lasciare un campo obbligatorio vuoto. Anche un GUID tutto a zero nasconde la tua corsa da alcune esperienze rivolte al cliente. Questa regola si applica solo agli attributi obbligatori. Non si applica agli attributi caller-agent nelle run iniziate da un uomo, dove si prevede un totale di zero AgentId sui invoke_agent record.

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. Nei record, il chiamante mostra invoke_agentAgentIdAgentBlueprintId un GUID tutto zero. Usalo TargetAgentId per identificare il tuo 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 unico dell'agente nel tuo sistema di identità; agent.type è un'etichetta breve che identifica quale sistema di identità 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 perinvoke_agent / output_messagese CLIENT per chat / execute_tool è ragionevole.

Related content

  • Ultimo aggiornamento: