Telemetria a livello ambiente con Application Insights (anteprima)

[Questo articolo è documentazione in versione non definitiva ed è soggetto a modifiche.]

Usa applicazione Azure Insights per monitorare le tracce degli agenti di Copilot Studio esportate da un ambiente gestito. Dopo aver configurato l'esportazione, usa Monitoraggio di Azure e Application Insights per validare le esecuzioni degli agenti, monitorare l'esecuzione di nodi e strumenti, creare avvisi e creare query e dashboard personalizzati per l'analisi operativa.

Note

La telemetria a livello di ambiente è disponibile per gli agenti alimentati sia dal cablaggio standard che dal cablaggio GitHub Copilot.
Dopo l'anteprima privata, le invocazioni degli agenti radice (invoke_agent) vengono ora emesse come dependencies, anziché requests. Di conseguenza, le tracce di invocazione dell'agente principale meno recenti potrebbero ancora apparire nella tabella requests.
Per valutare questa funzione di anteprima utilizzando la strategia e le capacità di telemetria più recenti, puoi testare in un ambiente non produttivo con il ciclo di rilascio anticipato abilitato.
Questa funzione è disponibile solo per ambienti gestiti.
Solo i log degli agenti costruiti in Copilot Studio, esclusi gli agenti dichiarativi, sono disponibili in Application Insights.
Per adottare solo una strategia Application Insights a livello di ambiente per la telemetria degli agenti di Copilot Studio, le organizzazioni possono scegliere di disabilitare la telemetria Application Insights a livello di agente.

Questo articolo spiega come configurare l'esportazione a livello di ambiente delle tracce degli agenti di Copilot Studio verso applicazione Azure Insights tramite il centro di amministrazione Power Platform.

Important

Questo articolo contiene la documentazione sull'anteprima di Microsoft Copilot Studio ed è pertanto soggetto a modifiche.

Le funzionalità di anteprima non sono destinate all'uso in produzione e possono avere funzionalità limitate. Queste funzionalità sono disponibili prima di una versione ufficiale in modo che sia possibile ottenere l'accesso iniziale e inviare commenti.

Se stai creando un agente destinato alla produzione, vedi Panoramica di Microsoft Copilot Studio.

Prerequisites

Prima di configurare la connessione di esportazione dati, completa i prerequisiti di Esporta dati in Application Insights.

Elementi esportati

Quando abiliti l'esportazione, la telemetria di tracce dell'agente di Copilot Studio viene scritta su Application Insights in un formato di osservabilità orientato alle tracce e allineato a OpenTelemetry, che supporta indagini, dashboard e allarme.

Gli eventi degli agenti di Copilot Studio vengono scritti nella tabella dependencies come intervalli. Ogni evento esportato (InvokeAgent, ExecuteTool, e OutputMessages) è una singola riga di campata (itemType = dependency).

In che modo gli span formano un'analisi

La telemetria segue il modello di trace e span di OpenTelemetry, ricostruito attraverso le colonne operation_Id e operation_ParentId:

Ogni turno dell'agente è una propria traccia, identificata da un operation_Id condiviso che consente ad Application Insights di raggruppare il turno e visualizzarlo nella vista end-to-end della transazione.
L'InvokeAgent intervallo è la radice della traccia del suo turno. L' ExecuteTool e gli span collegati OutputMessages si annidano sotto, ciascuno con operation_ParentId = id dello span di InvokeAgent.
Una conversazione si estende su più turni, ciascuno emesso come traccia separata. Raggruppa o filtra per gen_ai.conversation.id per ricollegare i turni di una stessa conversazione.
OutputMessages Gli span non sempre emettono una radice InvokeAgent, il che significa che possono (per impostazione predefinita) arrivare senza un genitore corrispondente e venire visualizzati come un'analisi autonoma a singolo nodo.

Creare un pacchetto di esportazione

Crea un pacchetto di esportazione con il tipo di esportazione impostato su Copilot Studio seguendo le istruzioni in Crea un pacchetto di esportazione della documentazione del centro di amministrazione Power Platform.

Convalidare la configurazione

Dopo aver salvato la configurazione di esportazione, avvia una conversazione di test con l'agente e conferma che la telemetria arriva in Application Insights. La consegna della telemetria può richiedere fino a 24 ore con nuove configurazioni. Verificare che:

Gli span degli agenti vengono visualizzati nella tabella dependencies.
Gli intervalli InvokeAgent, ExecuteTool e OutputMessages di ogni turno condividono un operation_Id.

Campi di Application Insights

La tabella seguente mostra i campi nella dependencies tabella e quali campi sono popolati per ciascuno dei tre eventi dell'agente esportato: InvokeAgent, ExecuteTool, e OutputMessages. La semantica di agente e operazione è in customDimensions (le gen_ai.* chiavi, come gen_ai.operation.name), non nelle colonne native.

Campi nella `dependencies` tabella	InvokeAgent	ExecuteTool	Messaggi di output	Valore di esempio
`timestamp [UTC]`	✔️	✔️	✔️	`6/11/2026, 5:02:13.501 AM`
`id`	✔️	✔️	✔️	`1111aaa1-aa11-11aa-11a1-a1aaa1111aa1`
`name`	✔️	✔️	✔️	`InvokeAgent` / `ExecuteTool` / `OutputMessages`
`resultCode`	✔️	✔️	✔️	`OK`, `ERROR`
`type`	✔️	✔️	✔️	`GenAI`
`target`	✔️	✔️	✔️	`GenAI`
`data`	✔️	✔️	✔️	`invoke_agent` / `execute_tool` / `output_messages`
`success`	✔️	✔️	✔️	`True`
`duration`	✔️	✔️	✔️	`0`
`performanceBucket`	✔️	✔️	✔️	`<250ms`
`itemType`	✔️	✔️	✔️	`dependency`
`customDimensions`	✔️	✔️	✔️	Scopri di più nelle proprietà di customDimension
`operation_Id`	✔️	✔️	✔️	`trace-1111aaa1-aa11-11aa-11a1-a1aaa1111aa1` (condiviso da ogni span del turno)
`operation_ParentId`	✔️	✔️	✔️	`InvokeAgent` `id` del turno per gli span figli; la radice dell'analisi per lo span `InvokeAgent`
`client_Type`	✔️	✔️	✔️	`PC`
`client_IP`	✔️	✔️	✔️	`0.0.0.0`
`client_City`	✔️	✔️	✔️	`San Jose`
`client_StateOrProvince`	✔️	✔️	✔️	`California`
`client_CountryOrRegion`	✔️	✔️	✔️	`United States`
`appId`	✔️	✔️	✔️	`11111a1a-1111-1111-a111-1a1a1a11111a`
`appName`	✔️	✔️	✔️	-
`iKey`	✔️	✔️	✔️	`aa111a1a-a1aa-111a-111a-a111a111111a`
`sdkVersion`	✔️	✔️	✔️	`dotnetc:2.23.0-29`
`itemId`	✔️	✔️	✔️	`a1a1111a-1111-11a1-1111-111111aa1a1a`
`itemCount`	✔️	✔️	✔️	`1`
`_ResourceId`	✔️	✔️	✔️	-

Proprietà di customDimensions

Ogni intervallo include il JSON customDimensions. La tabella seguente mostra le chiavi comuni presenti in ogni intervallo:

Key	Valore di esempio
`SpanId`	`1111aaa1-aa11-11aa-11a1-a1aaa1111aa1`
`error.type`	`404`
`Status.code`	`1`, `2`
`Status.message`	`Descriptive failure message`
`gen_ai.agent.id`	`1aa11a11-1a1a-1a11-1a1a-1111aa1111aa`
`gen_ai.agent.name`	`MCS Agent`
`gen_ai.conversation.id`	`aaaaa111-1a1a-1111-1aa1-a111111a11a1`
`gen_ai.request.model`	`Sonnet46`
`gen_ai.operation.name`	`invoke_agent` / `execute_tool` / `output_messages`
`env.id`	`111a1aa1-a1aa-aaa1-a11a-11a111111111`
`microsoft.tenant.id`	`11aaa111-1a11-1a1a-a111-aa1a111a111a`
`microsoft.a365.agent.blueprint.id`	`1111111a-aa11-1a11-a1a1-a11a1111a1a1`
`microsoft.a365.agent.platform.id`	`111a1aa1-…_1a11111a-…`
`microsoft.channel.name`	`Copilot Studio Test Pane`
`resource.provider`	`copilot studio`
`signal.category`	`default`
`a365.enabled`	`True`
`appinsights.enabled`	`True`
`user.id`	-
`user.email`	`My.User@mytenant.onmicrosoft.com`
`user.name`	`My User`
`client.address`	`::ffff:00.00.00.00`
`telemetry.sdk.name`	`A365ObservabilitySDK`
`telemetry.sdk.language`	`dotnet`
`telemetry.sdk.version`	`1.1.9.43597`

Chiavi specifiche per evento

La tabella seguente mostra le chiavi specifiche per evento:

Key	InvokeAgent	ExecuteTool	Messaggi di output	Descrizione
`gen_ai.input.messages`	✔️	-	-	matrice JSON di `{role, parts:[{content, type}]}`: il prompt dell'utente
`gen_ai.output.messages`	-	-	✔️	JSON array — la risposta dell'agente
`gen_ai.tool.name`	-	✔️	-	Ad esempio, `workiqsharepoint:mcp_SharePointRemoteServer`
`gen_ai.tool.type`	-	✔️	-	Ad esempio, `MCP - Power Platform Connector`
`gen_ai.tool.call.id`	-	✔️	-	Identificatore di invocazione dello strumento
`gen_ai.tool.call.arguments`	-	✔️	-	Carico utile JSON inviato allo strumento
`gen_ai.tool.call.result`	-	✔️	-	Carico utile JSON restituito dallo strumento

Scopri lo schema attuale

Lo schema documentato in questo articolo potrebbe evolversi nel tempo. Invece di affidarti solo alle tabelle menzionate in precedenza, usa le seguenti domande per esaminare lo schema più recente in tempo reale nel tuo ambiente.

Elenca le colonne native delle tabelle

La query seguente restituisce lo schema a livello di colonna della dependencies tabella. Usalo per confermare le colonne native disponibili quando crei query, dashboard o avvisi.

dependencies
| getschema
| project ColumnName, ColumnType
| order by ColumnName asc

Scopri chiavi personalizzate Dimensions (proprietà dinamiche)

La seguente query elenca tutte le chiavi all'interno del customDimensions JSON nella dependencies tabella: il nome della proprietà, su quali eventi dell'agente appare (InvokeAgent, ExecuteTool, OutputMessages), e un valore di esempio. A differenza dello schema a colonne nativo, queste proprietà sono dinamiche, quindi questa query rimane accurata mentre l'SDK aggiunge nuove gen_ai.* o altre chiavi. Usalo come fonte viva di verità per gli attributi disponibili.

dependencies
| where timestamp > ago(7d)
| mv-expand Key = bag_keys(customDimensions) to typeof(string)
| summarize Events = make_set(name), SampleValue = take_any(tostring(customDimensions[Key])) by Key
| order by Key asc

Monitorare la telemetria esportata

Usa i Log di Application Insights per interrogare l'attività degli agenti e indagare sull'esecuzione di agenti o strumenti. La telemetria esportata confluisce nella tabella dependencies come span:

Ogni turno dell'agente è una traccia, raggruppata tramite un operation_Id condiviso.
Lo span InvokeAgent è lo span radice dell'analisi; gli span ExecuteTool e OutputMessages sono annidati al di sotto di esso tramite operation_ParentId.
Raggruppa per gen_ai.conversation.id i turni multipli della stessa conversazione e suddividi tale ID in corrispondenza di _ per includere le tracce degli agenti secondari.

Pannelli degli agenti (anteprima)

Oltre a Logs, Application Insights fornisce viste Agents (preview) predefinite che visualizzano la telemetria GenAI esportata senza dover scrivere query Kusto. Quando Copilot Studio scrive i propri span nella tabella dependencies, questi pannelli leggono direttamente da tali dati:

Esecuzioni dell'agente: Elenca le invocazioni dell'agente generate dagli intervalli InvokeAgent, con la relativa durata, l'esito e la conversazione a cui appartiene ogni esecuzione. Si applicano alcune limitazioni; scopri di più in Limitazioni e considerazioni note.
Strumenti: Aggrega gli ExecuteTool intervalli per mostrare quali strumenti chiamano gli agenti, con quale frequenza e come si comportano.
Modelli: Riassume l'uso dei modelli tra le run, evidenziando i modelli invocati e i loro modelli di chiamata.

Analizza la telemetria degli agenti con Application Insights

Dopo aver collegato il tuo ambiente ad Application Insights, registra i dati di telemetria degli agenti quando gli utenti interagiscono con l'agente, anche durante i test all'interno di Copilot Studio. Per visualizzare i dati di telemetria registrati, vai alla sezione Log della tua risorsa Application Insights in Azure. Qui puoi usare le query Kusto per interrogare e analizzare i tuoi dati. Scopri di più in Query di esempio.

Interrogazioni di esempio

I seguenti esempi di query Kusto ricostruiscono le conversazioni degli agenti di Copilot Studio dalla tabella dependencies in Application Insights. Poiché a ogni turno tutti gli span condividono una traccia operation_Id, le query ordinano gli span partendo dalla radice (lo span InvokeAgent prima dei relativi span figlio) all'interno di ogni traccia.

Query 1: Restituisci una traccia completa per un ID di conversazione specifico

Questa query restituisce tutti gli span di una conversazione nota, ordinati cronologicamente, con ogni span radice elencato prima dei relativi span figli. Sostituisci il segnaposto Conversation ID con l'ID conversazione del tuo agente. Puoi trovarlo inserendo il seguente comando mentre testi il tuo agente custom: /debug conversationid.

let LatestConvo = "<Conversation ID>"; 
dependencies
| where tostring(customDimensions["gen_ai.conversation.id"]) == LatestConvo
| order by operation_Id asc, iff(name == "InvokeAgent", 0, 1) asc, timestamp asc
| project timestamp, name, id, operation_Id,
          operation_ParentId, duration, target, type, cloud_RoleName,
          resultCode, customDimensions

Domanda 2: Restituisci l'ultima conversazione per un agente specifico

Questa query trova la conversazione più recente per un agente nominato entro la finestra temporale specificata. Restituisce ogni intervallo di quella conversazione nello stesso ordine cronologico, radice prima. Sostituisci il nome dell'agente provvisorio con quello del tuo agente.

let Window = 7d;
let AgentName = "<Agent name>";
let LatestConvo = toscalar(
    dependencies
    | where timestamp > ago(Window)
    | where tostring(customDimensions["gen_ai.agent.name"]) == AgentName
    | where isnotempty(tostring(customDimensions["gen_ai.conversation.id"]))
    | top 1 by timestamp desc
    | project tostring(customDimensions["gen_ai.conversation.id"])
);
dependencies
| where timestamp > ago(Window)
| where tostring(customDimensions["gen_ai.conversation.id"]) == LatestConvo
| order by operation_Id asc, iff(name == "InvokeAgent", 0, 1) asc, timestamp asc
| project timestamp, name, id, operation_Id,
          operation_ParentId, duration, target, type, cloud_RoleName,
          resultCode, customDimensions

Query 3: Espandere le proprietà note di OpenTelemetry di GenAI in colonne

Questa query restituisce la stessa traccia della query 2, ma suddivide anche ogni chiave nota delle convenzioni semantiche di OpenTelemetry in una colonna dedicata con nome proprio. Il risultato è una tabella piatta ed esplicitamente definita dove puoi ordinare, filtrare e scansionare direttamente i campi dell'IA generativa come nome dello strumento, modello, prompt utente, risposta dell'agente e ID conversazione. Sostituisci il nome dell'agente provvisorio con quello del tuo agente.

let Window = 7d;
let AgentName = "<Agent name>";
let LatestConvo =
    toscalar(
        dependencies
        | where timestamp > ago(Window)
        | extend
            AgentName_ = tostring(customDimensions["gen_ai.agent.name"]),
            ConversationId_ = tostring(customDimensions["gen_ai.conversation.id"])
        | where AgentName_ == AgentName
        | where isnotempty(ConversationId_)
        | summarize arg_max(timestamp, ConversationId_)
        | project ConversationId_
    );
dependencies
| where timestamp > ago(Window)
| extend
    ConversationId = tostring(customDimensions["gen_ai.conversation.id"])
| where ConversationId == LatestConvo
| extend
    OperationName    = tostring(customDimensions["gen_ai.operation.name"]),
    AgentId          = tostring(customDimensions["gen_ai.agent.id"]),
    AgentName        = tostring(customDimensions["gen_ai.agent.name"]),
    Model            = tostring(customDimensions["gen_ai.request.model"]),
    ToolName         = tostring(customDimensions["gen_ai.tool.name"]),
    ToolType         = tostring(customDimensions["gen_ai.tool.type"]),
    ToolCallId       = tostring(customDimensions["gen_ai.tool.call.id"]),
    ToolArguments    = tostring(customDimensions["gen_ai.tool.call.arguments"]),
    ToolResult       = tostring(customDimensions["gen_ai.tool.call.result"]),
    EnvironmentId    = tostring(customDimensions["env.id"]),
    TenantId         = tostring(customDimensions["microsoft.tenant.id"]),
    ChannelName      = tostring(customDimensions["microsoft.channel.name"]),
    BlueprintId      = tostring(customDimensions["microsoft.a365.agent.blueprint.id"]),
    PlatformId       = tostring(customDimensions["microsoft.a365.agent.platform.id"]),
    ResourceProvider = tostring(customDimensions["resource.provider"]),
    SignalCategory   = tostring(customDimensions["signal.category"]),
    UserId           = tostring(customDimensions["user.id"]),
    UserName         = tostring(customDimensions["user.name"]),
    UserEmail        = tostring(customDimensions["user.email"])
| extend
    InputMessages  = parse_json(tostring(customDimensions["gen_ai.input.messages"])),
    OutputMessages = parse_json(tostring(customDimensions["gen_ai.output.messages"]))
| extend
    UserInput   = tostring(InputMessages[0].parts[0].content),
    AgentOutput = tostring(OutputMessages[0].parts[0].content)
| order by
    operation_Id asc,
    iff(name == "InvokeAgent", 0, 1) asc,
    timestamp asc
| project
    timestamp, name, id, operation_Id, operation_ParentId, OperationName, ConversationId,
    AgentId, AgentName, Model, ToolName, ToolType, ToolCallId, ToolArguments, ToolResult,
    UserInput, AgentOutput, EnvironmentId, TenantId, ChannelName, BlueprintId, PlatformId,
    ResourceProvider, SignalCategory, UserId, UserName, UserEmail, duration, target, type,
    cloud_RoleName, resultCode, customDimensions

Query 4: Espandi dinamicamente tutte le proprietà di OpenTelemetry di genAI

Questa query restituisce gli stessi intervalli della query 3, ma ogni chiave gen_ai.* viene estratta dinamicamente da customDimensions in una propria colonna con prefisso ga_. Poiché la proiezione è dinamica, qualsiasi nuovo gen_ai.* attributo emettato dall'SDK appare automaticamente senza modificare la query. Sostituisci il nome dell'agente provvisorio con quello del tuo agente.

let Window = 7d;
let AgentName = "<Agent name>";
let LatestConvo = toscalar(
    dependencies
    | where timestamp > ago(Window)
    | where tostring(customDimensions["gen_ai.agent.name"]) == AgentName
    | where isnotempty(tostring(customDimensions["gen_ai.conversation.id"]))
    | top 1 by timestamp desc
    | project tostring(customDimensions["gen_ai.conversation.id"])
);
dependencies
| where timestamp > ago(Window)
| where tostring(customDimensions["gen_ai.conversation.id"]) == LatestConvo
| order by operation_Id asc, iff(name == "InvokeAgent", 0, 1) asc, timestamp asc
| mv-apply Key = bag_keys(customDimensions) on (
    where Key startswith "gen_ai."
    | summarize OTelGenAI = make_bag(bag_pack(tostring(Key), customDimensions[tostring(Key)]))
  )
| project timestamp, name, id, operation_Id, operation_ParentId,
          duration, target, type, cloud_RoleName, resultCode,
          OTelGenAI, customDimensions
| evaluate bag_unpack(OTelGenAI, 'ga_')

Limitazioni e considerazioni note

Questa funzionalità non supporta scenari non autenticati o di configurazione multi-tenant dell'agente. Pertanto, Application Insights non li registra.
Questa funzione è attualmente disponibile solo negli ambienti cloud pubblici Microsoft.
In alcuni scenari con agenti connessi, la relazione padre-figlio tra le tracce non viene mappata correttamente.
Il valore duration non è disponibile per tracce di agenti alimentati dall'harness standard.
Assicurati di attivare la proprietà di autenticazione locale nella risorsa target Application Insights.
L'esportazione della telemetria non è transazionale. Durante eventi di servizio transitorio, possono verificarsi piccole perdite di dati.
Potrebbero verificarsi incoerenze nei dati con l'arrivo degli aggiornamenti di ingestione relativi allo schema.
Questa funzione non cattura eventi legati all'argomento come TopicStart, TopicAction, e TopicEnd.
Gli ID di traccia e di span utilizzano attualmente una rappresentazione basata su GUID anziché i formati esadecimali standard di OpenTelemetry: trace ID di 32 caratteri e span ID di 16 caratteri.
Per semplificare la reportistica e la risoluzione dei problemi, evita di inviare sia telemetria a livello di agente che a livello di ambiente alla stessa istanza di Application Insights.
La telemetria potrebbe variare tra agenti alimentati dal GitHub Copilot harness e agenti alimentati dallo standard harness.
Assicurati che la configurazione di Application Insights a livello di ambiente soddisfi i requisiti di residenza dei dati, privacy e controllo degli accessi basati sul ruolo (RBAC).
Grandi contenuti di log, inclusi i feedback degli agenti e gli argomenti degli strumenti, potrebbero essere troncati.

Commenti e suggerimenti

Questa pagina è stata utile?

Ultimo aggiornamento: 2026-09-18