Telemetria em nível ambiental com Application Insights (prévia)

[Este artigo é uma documentação de pré-lançamento e está sujeito a alterações.]

Use o Aplicativo Azure Insights para monitorar os rastros de agentes do Copilot Studio exportados de um ambiente gerenciado. Depois de configurar a exportação, use o Azure Monitor e o Application Insights para validar execuções de agentes, monitorar a execução de nós e ferramentas, criar alertas e criar consultas e dashboards personalizados para análise operacional.

Note

  • A telemetria no nível do ambiente está disponível para agentes baseados tanto no harness padrão quanto no harness do GitHub Copilot.
  • Após a pré-visualização privada, as invocações do agente raiz (invoke_agent) agora são emitidas como dependencies (junto com todos os outros espaços), em vez de requests. Como resultado, os rastreamentos de invocação na raiz do agente ainda podem aparecer na tabela requests até que a implantação global seja concluída.
  • Para avaliar esse recurso de pré-visualização usando a estratégia e capacidades de telemetria mais recentes, você pode testar em um ambiente não de produção com o ciclo de lançamento antecipado ativado.
  • Esse recurso está sendo implementado globalmente e pode ainda não estar totalmente disponível em seus ambientes.
  • Esse recurso está disponível apenas para ambientes gerenciados.
  • Somente logs de agentes criados no Copilot Studio, excluindo agentes declarativos, estão disponíveis no Application Insights.
  • Para adotar apenas uma estratégia Application Insights em nível ambiente para a telemetria de agentes do Copilot Studio, as organizações podem optar por desativar a telemetria Application Insights em nível de agente.

Este artigo explica como configurar a exportação em nível ambiente dos rastros de agentes do Copilot Studio para o Aplicativo Azure Insights por meio do centro de administração do Power Platform.

Importante

Este artigo contém a documentação da versão preliminar do Microsoft Copilot Studio e está sujeito a alterações.

As funcionalidades de pré-visualização não se destinam à utilização de produção e podem ter funcionalidades restritas. Esses recursos estão disponíveis antes de um lançamento oficial para que você possa obter acesso antecipado e fornecer comentários.

Se você estiver criando um agente pronto para produção, confira a visão geral do Microsoft Copilot Studio.

Pré-requisitos

Antes de configurar a conexão de exportação de dados, complete os pré-requisitos de Exportar dados para o Application Insights.

O que é exportado

Quando você habilita a exportação, a telemetria de rastreamento do agente do Copilot Studio é escrita para o Application Insights em um formato de observabilidade orientado a traços e alinhado ao OpenTelemetry, que suporta investigação, dashboards e alertas.

Os eventos de agente do Copilot Studio são gravados na tabela dependencies na forma de spans. Cada evento exportado (InvokeAgent, ExecuteTool e OutputMessages) é uma única linha de span (itemType = dependency).

Como os vãos formam um traço

A telemetria segue o modelo de rastros e spans do OpenTelemetry, e é reconstruída por meio das colunas operation_Id e operation_ParentId:

  • Cada turno do agente constitui um rastreamento próprio, identificado por um operation_Id compartilhado, o que permite ao Application Insights agrupar o turno e exibi-lo na visão da transação de ponta a ponta.
  • O InvokeAgent vão é a raiz do traço de sua curva. Seus ExecuteTool intervalos e os OutputMessages conectados ficam aninhados abaixo dele, cada um carregando operation_ParentId = o InvokeAgent do intervalo id.
  • Uma conversa se estende por vários turnos, cada um emitido como um rastreio separado. Agrupe ou filtre por gen_ai.conversation.id para reunir novamente as interações de uma conversa.
  • OutputMessages spans nem sempre emitem uma raiz InvokeAgent, o que significa que podem (por design) chegar sem um pai correspondente e aparecer como um trace independente, composto por um único nó.

Criar um pacote de exportação

Crie um pacote de exportação com o tipo de exportação definido para Copilot Studio seguindo as instruções em Criar um pacote de exportação da documentação do centro de administração do Power Platform.

Validar a configuração

Depois de salvar a configuração de exportação, execute uma conversa de teste com o agente e confirme que a telemetria chegou ao Application Insights. A entrega de telemetria pode levar até 24 horas em novas configurações. Valide isso:

  • Os spans de agente aparecem na tabela dependencies.
  • Os intervalos InvokeAgent, ExecuteTool e OutputMessages de cada turno compartilham um operation_Id.

Campos do Application Insights

A tabela a seguir mostra os campos na dependencies tabela e quais campos são preenchidos para cada um dos três eventos do agente exportado: InvokeAgent, ExecuteTool, e OutputMessages. A semântica do agente e da operação está em customDimensions (nas chaves gen_ai.*, como gen_ai.operation.name), não nas colunas nativas.

Campos na dependencies tabela InvokeAgent ExecuteTool Mensagens de saída Valor de amostra
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 ✔️ ✔️ ✔️ Saiba mais em propriedades de customDimension
operation_Id ✔️ ✔️ ✔️ trace-1111aaa1-aa11-11aa-11a1-a1aaa1111aa1 (compartilhada por cada trecho da curva)
operation_ParentId ✔️ ✔️ ✔️ As curvas InvokeAgentid são para os trechos filhos; a raiz traço para o InvokeAgent vão
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 ✔️ ✔️ ✔️ -

propriedades de customDimensions

Cada span inclui o JSON customDimensions. A tabela a seguir mostra as chaves comuns que aparecem em cada span:

Key Valor de amostra
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

Chaves específicas de eventos

A tabela a seguir mostra as chaves específicas de cada evento:

Key InvokeAgent ExecuteTool Mensagens de saída Descrição
gen_ai.input.messages ✔️ - - Matriz JSON de {role, parts:[{content, type}]}—a solicitação do usuário
gen_ai.output.messages - - ✔️ Matriz JSON — a resposta do agente
gen_ai.tool.name - ✔️ - Por exemplo, workiqsharepoint:mcp_SharePointRemoteServer
gen_ai.tool.type - ✔️ - Por exemplo, MCP - Power Platform Connector
gen_ai.tool.call.id - ✔️ - Identificador de invocação de ferramenta
gen_ai.tool.call.arguments - ✔️ - Carga útil JSON enviada para a ferramenta
gen_ai.tool.call.result - ✔️ - Carga útil JSON retornada pela ferramenta

Descubra o esquema atual

O esquema documentado neste artigo pode evoluir ao longo do tempo. Em vez de depender apenas das tabelas mencionadas anteriormente, use as seguintes consultas para inspecionar o esquema mais recente ao vivo no seu próprio ambiente.

Listar colunas nativas de tabela

A consulta seguinte retorna o esquema em nível de coluna da dependencies tabela. Use-o para confirmar colunas nativas disponíveis ao criar consultas, dashboards ou alertas.

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

Conheça os campos customDimensions (propriedades dinâmicas)

A consulta a seguir lista todas as chaves dentro do customDimensions JSON na dependencies tabela: o nome da propriedade, em quais eventos de agente ele aparece (InvokeAgent, ExecuteTool, OutputMessages), e um valor de exemplo. Ao contrário do esquema nativo de colunas, essas propriedades são dinâmicas, então essa consulta permanece precisa à medida que o SDK adiciona novas gen_ai.* ou outras chaves. Use-o como fonte viva de verdade para atributos disponíveis.

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

Monitorar a telemetria exportada

Use os Logs do Application Insights para consultar a atividade do agente e investigar a execução do agente ou da ferramenta. Toda a telemetria exportada aparece na dependencies tabela como abrangências:

  • Cada turno do agente é um rastreamento, agrupado por um operation_Id compartilhado.
  • O InvokeAgent span é a raiz do rastreamento; os spans ExecuteTool e OutputMessages ficam aninhados abaixo dele por meio de operation_ParentId.
  • Agrupe por gen_ai.conversation.id para encadear várias interações da mesma conversa e divida esse ID em _ para incluir rastros de subagentes.

Lâminas de agentes (prévia)

Além dos Logs, o Application Insights oferece visualizações integradas de Agentes (prévia) que visualizam a telemetria GenAI exportada sem precisar escrever consultas Kusto. À medida que o Copilot Studio escreve seus intervalos na dependencies tabela, essas pás leem diretamente desses dados:

  • Execuções do agente: Lista as invocações do agente geradas a partir dos spans InvokeAgent, com sua duração, êxito e a conversa à qual cada execução pertence. Algumas limitações se aplicam; saiba mais em Limitações e considerações conhecidas.
  • Ferramentas: Agrega os ExecuteTool intervalos para mostrar quais ferramentas os agentes chamam, com que frequência e como eles atuam.
  • Modelos: Resume o uso dos modelos entre execuções, destacando os modelos invocados e seus padrões de chamada.

Captura de tela das lâminas do Agente de Insights da Aplicação.

Analise a telemetria de agentes com o Application Insights

Depois que você conecta seu ambiente ao Application Insights, ele registra os dados de telemetria do agente quando os usuários interagem com o agente, inclusive durante os testes dentro do Copilot Studio. Para visualizar os dados de telemetria registrados, acesse a seção Logs do seu recurso Application Insights no Azure. Aqui, você pode usar consultas Kusto para consultar e analisar seus dados. Saiba mais em Exemplos de consultas.

Consultas de exemplo

Os exemplos de consultas Kusto a seguir reconstituem as conversas dos agentes do Copilot Studio a partir da tabela dependencies no Application Insights. Como cada span compartilha um rastreamento operation_Id em cada turno, as consultas ordenam os spans da raiz para os filhos (o span InvokeAgent antes dos spans filhos) dentro de cada rastreamento.

Consulta 1: Retorne um rastreamento completo de um ID de conversa específico

Esta consulta retorna todos os spans de uma conversa específica conhecida, ordenados cronologicamente, com cada span raiz listado antes de seus spans filhos. Substitua o marcador ID da conversa pelo ID da conversa do seu agente. Você pode encontrá-lo digitando o seguinte comando enquanto testa seu agente personalizado: /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

Consulta 2: Devolver a última conversa de um agente específico

Essa consulta encontra a conversa mais recente para um agente nomeado dentro do intervalo de tempo especificado. Ele retorna todos os intervalos dessa conversa na mesma ordem cronológica, raíz primeiro. Substitua o nome do agente provisório pelo nome do seu 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

Consulta 3: Expandir propriedades conhecidas do OpenTelemetry genAI para colunas

Essa consulta retorna o mesmo rastreio que a consulta 2, mas também analisa cada chave conhecida da convenção semântica do OpenTelemetry em sua própria coluna nomeada. O resultado é uma tabela plana e explicitamente definida, onde você pode ordenar, filtrar e escanear os campos de IA generativa, como nome da ferramenta, modelo, prompt do usuário, resposta do agente e ID de conversa diretamente. Substitua o nome do agente provisório pelo nome do seu 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

Consulta 4: Expandir dinamicamente todas as propriedades do OpenTelemetry genAI

Esta consulta retorna as mesmas abrangências que a consulta 3, mas cada chave gen_ai.* é desempacotada dinamicamente de customDimensions em sua própria coluna com prefixo ga_. Como a projeção é dinâmica, qualquer novo gen_ai.* atributo que o SDK emite depois aparece automaticamente sem alterar a consulta. Substitua o nome do agente provisório pelo nome do seu 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_')

Consulta 5: Devolver a conversa mais recente de um agente raiz com todos os seus filhos, incluindo subagentes

Esta consulta retorna a conversa mais recente de um agente específico. Retorna todos os spans dessa conversa e de todos os subagentes de primeiro nível que ela invocou. Quando um agente chama outro agente como uma ferramenta, o subagente herda o ID de conversa do pai com um _<subConversationId> sufixo. Toda a árvore é reconstruída com base na correspondência do ID de nível superior. Substitua o nome do agente provisório pelo nome do seu agente.

let Window = 7d;
let AgentName = "<Agent name>";
let LatestRoot =
    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)
        | where ConversationId !has "_"
        | summarize arg_max(timestamp, ConversationId)
        | project ConversationId
    );
dependencies
| where timestamp > ago(Window)
| extend
    ConversationId = tostring(customDimensions["gen_ai.conversation.id"]),
    AgentName_ = tostring(customDimensions["gen_ai.agent.name"]),
    ToolName = tostring(customDimensions["gen_ai.tool.name"]),
    ToolResult = tostring(customDimensions["gen_ai.tool.callresult"])
| where isnotempty(ConversationId)
| where ConversationId == LatestRoot
    or ConversationId startswith strcat(LatestRoot, "_")
| extend
    Depth = countof(ConversationId, "_"),
    AgentRole = iff(ConversationId == LatestRoot, "root", "sub-agent")
| 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 timestamp asc
| project
    timestamp, name, AgentRole, Depth, AgentName, ToolName, ToolResult, UserInput,
    AgentOutput, id, operation_Id, operation_ParentId, ConversationId, duration,
    target, type, cloud_RoleName, resultCode, customDimensions

Limitações e considerações conhecidas

  • O duration valor não está disponível para vestígios de agentes alimentados pelo chicote padrão.
  • Atualmente, os erros na execução de agentes e ferramentas não são refletidos corretamente nos status de rastreamento.
  • Com base nos requisitos de residência de dados, talvez você queira usar recursos dedicados de Application Insights para cada região do ambiente.
  • Os spans de subagentes atualmente têm como pai o span InvokeAgent que invocou o agente, em vez do span InvokeAgent dentro do seu próprio trace.
  • Os IDs de rastreamento e de span atualmente são emitidos como GUIDs (com prefixo quando necessário), em vez de usar o formato totalmente alinhado ao padrão OpenTelemetry, com ID de rastreamento de 32 caracteres hexadecimais e ID de span de 16 caracteres hexadecimais.
  • Certifique-se de que a autenticação local esteja ativada no recurso alvo Application Insights.
  • A exportação de telemetria não é transacional. Durante eventos de serviço transitório, pequenas quantidades de perda de dados podem ocorrer.
  • Podem ocorrer inconsistências nos dados à medida que atualizações de ingestão relacionadas ao esquema são implementadas.
  • Eventos relacionados a tópicos como TopicStart, TopicAction, e TopicEnd não são capturados com telemetria em nível ambiental.
  • Para simplificar relatórios e solução de problemas, evite enviar telemetria tanto em nível de agente quanto em nível de ambiente para a mesma instância do Application Insights.
  • A telemetria emitida para agentes criados na experiência de criação de agentes com tecnologia do harness do GitHub Copilot pode diferir da telemetria dos agentes criados na experiência de criação de agentes com tecnologia do harness padrão.
  • Last updated on