Telemetria ao nível do ambiente com Application Insights (pré-visualização)

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

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

Este artigo explica como configurar a exportação ao nível do ambiente dos rastros do agente Copilot Studio para o Aplicação Azure Insights através do centro de administração do Power Platform.

Pré-requisitos

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

O que é exportado

Quando ativas a exportação, a telemetria de rastreamento do agente do Copilot Studio é escrita para o Application Insights num formato de observabilidade orientado para traços e alinhado com o OpenTelemetry, que suporta investigação, dashboards e alertas.

Os eventos do agente do Copilot Studio são registados na tabela dependencies como intervalos. 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 trace-and-span do OpenTelemetry, reconstruída a partir das colunas operation_Id e operation_ParentId:

• Cada turno do agente é o seu próprio rastreio, identificado por um operation_Id partilhado, o que permite ao Application Insights agrupar o turno e mostrá-lo na vista de transação ponta a ponta.
• O InvokeAgent vão é a raiz do traço do seu turno. Os seus ExecuteTool e os intervalos conectados OutputMessages ficam aninhados por baixo dele, cada um transportando operation_ParentId = o InvokeAgent do intervalo id.
• Uma conversa abrange vários turnos, cada um emitido como um traço separado. Agrupe ou filtre por gen_ai.conversation.id para voltar a reunir as intervenções de uma conversa.
• OutputMessages Os spans nem sempre emitem uma InvokeAgent raiz, o que significa que podem (por design) chegar sem um pai correspondente e aparecer como um traço independente, de nó único.

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 guardar a configuração de exportação, execute uma conversa de teste com o agente e confirme que a telemetria chega ao Application Insights. A entrega de telemetria pode demorar até 24 horas em novas configurações. Valide isso:

• Os intervalos de agentes aparecem na dependencies tabela.
• Os intervalos InvokeAgent, ExecuteTool e OutputMessages de cada turno partilham um operation_Id.

Campos do Application Insights

A tabela seguinte mostra os campos na dependencies tabela e quais os campos 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.

propriedades de customDimensions

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

Chaves específicas de eventos

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

Descubra o esquema atual

O esquema documentado neste artigo poderá evoluir ao longo do tempo. Em vez de confiar apenas nas tabelas mencionadas anteriormente, utilize as seguintes consultas para inspecionar o esquema mais recente disponível no seu próprio ambiente.

Listar colunas de tabela nativas

A consulta seguinte devolve o esquema ao nível da 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

Descobre chaves customDimensions (propriedades dinâmicas)

A consulta seguinte lista todas as chaves dentro do customDimensions JSON na dependencies tabela: o nome da propriedade, em que eventos do agente aparece (InvokeAgent, ExecuteTool, OutputMessages), e um valor de exemplo. Ao contrário do esquema de colunas nativo, estas propriedades são dinâmicas, pelo que esta consulta mantém-se precisa à medida que o SDK adiciona novas gen_ai.* ou outras chaves. Usa-o como fonte viva de verdade para os 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

Monitorizar telemetria exportada

Utilize os Logs do Application Insights para consultar a atividade do agente e investigar a execução de agentes ou ferramentas. Toda a telemetria exportada fica na dependencies tabela como abrangências:

• Cada interação do agente é um rasto, agrupado por um operation_Id partilhado.
• O InvokeAgent intervalo é a raiz do rastreio; ExecuteTool e OutputMessages estão aninhados sob ele através de operation_ParentId.
• Agrupe por gen_ai.conversation.id para agrupar várias interações da mesma conversa e divida esse ID em _ para incluir rastreios de subagentes.

Lâminas de agentes (pré-visualização)

Para além dos Logs, o Application Insights fornece vistas incorporadas de Agentes (pré-visualização) que visualizam a telemetria GenAI exportada sem escrever consultas Kusto. À medida que o Copilot Studio escreve os seus intervalos na dependencies tabela, estas pás leem diretamente desses dados:

• Execuções do agente: Lista as invocações do agente criadas a partir dos segmentos InvokeAgent, com a respetiva duração, êxito e a conversa à qual cada execução pertence. Aplicam-se algumas limitações; Saiba mais em Limitações e considerações conhecidas.
• Ferramentas: Agrega os ExecuteTool intervalos para mostrar quais as ferramentas que os agentes utilizam, com que frequência e qual o seu desempenho.
• Modelos: Resume a utilização dos modelos ao longo das execuções, destacando os modelos invocados e os seus padrões de chamada.

Analise a telemetria dos agentes com o Application Insights

Depois de ligar o seu ambiente ao Application Insights, ele regista os dados de telemetria do agente quando os utilizadores interagem com o agente, incluindo durante os testes dentro do Copilot Studio. Para visualizar os dados de telemetria registados, aceda à secção Logs do seu recurso Application Insights no Azure. Aqui, pode usar consultas Kusto para consultar e analisar os seus dados. Saiba mais em Exemplos de consultas.

Exemplos de consultas

Os exemplos seguintes de consultas Kusto reconstituem as conversas de agente do Copilot Studio a partir da tabela dependencies no Application Insights. Como cada intervalo partilha um rastreio operation_Id em cada turno, as consultas ordenam os intervalos pela raiz primeiro (o intervalo InvokeAgent antes dos seus intervalos filhos) dentro de cada rastreio.

Consulta 1: Devolver um rastreio completo para um ID de conversa específico

Esta consulta devolve todos os spans de uma determinada conversa, ordenados cronologicamente, com cada span raiz apresentado antes dos seus spans filhos. Substitua o marcador de posição ID da conversa pelo ID da conversa do seu agente. Pode encontrá-lo introduzindo o seguinte comando enquanto testa o 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

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

Esta consulta encontra a conversa mais recente de um agente nomeado dentro da janela de tempo especificada. Devolve todos os spans dessa conversa pela mesma ordem cronológica, começando pela raiz. 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 as propriedades genAI conhecidas do OpenTelemetry para colunas

Esta consulta devolve o mesmo rasto que a consulta 2, mas também processa cada chave conhecida da convenção semântica do OpenTelemetry numa coluna com nome próprio. O resultado é uma tabela plana e explicitamente definida onde pode ordenar, filtrar e analisar diretamente os campos de IA generativa, como nome da ferramenta, modelo, prompt do utilizador, resposta do agente e ID de conversa. 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 devolve os mesmos intervalos que a consulta 3, mas cada chave gen_ai.* é descompactada dinamicamente de customDimensions para a sua própria coluna com o prefixo ga_. Como a projeção é dinâmica, qualquer novo gen_ai.* atributo que o SDK emita posteriormente 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 para um agente raiz com todos os seus filhos, incluindo subagentes

Esta consulta retorna a conversa mais recente de um agente com nome especificado. Retorna todos os spans dessa conversa e de todos os subagentes de primeiro nível que foram invocados. Quando um agente chama outro agente como ferramenta, o subagente herda o ID da conversa do agente principal com o sufixo _<subConversationId>. Toda a árvore é reconstruída pela correspondência com base no 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 os Classic Agent Traces.
• Os erros de execução de agentes e ferramentas não são atualmente refletidos corretamente nos estados dos rastreios.
• Com base nas suas necessidades de residência de dados, poderá querer usar recursos dedicados de Application Insights para cada região do ambiente.
• Os spans do subagente atualmente são parentes do intervalo InvokeAgent que invocou o agente, em vez do InvokeAgent intervalo dentro do seu próprio traço.
• Os trace IDs e span IDs são atualmente emitidos como GUIDs (com prefixo, quando necessário), em vez de seguirem integralmente o padrão OpenTelemetry de trace ID com 32 caracteres hexadecimais e span ID com 16 caracteres hexadecimais.
• Certifique-se de que a autenticação local está ativada no recurso alvo Application Insights.
• A exportação de telemetria não é transacional. Durante eventos de serviço transitório, podem ocorrer pequenas quantidades de perda de dados.
• Podem ocorrer inconsistências nos dados à medida que as atualizações de ingestão relacionadas com o esquema são implementadas.
• Eventos relacionados com tópicos como TopicStart, TopicAction, e TopicEnd não são captados com telemetria ao nível do ambiente.
• Para simplificar a reporte e a resolução de problemas, evite enviar telemetria tanto ao nível do agente como ao nível do ambiente para a mesma instância do Application Insights.
• A telemetria emitida para agentes criados nos agentes alimentados pelo GitHub Copilot pode diferir dos agentes construídos nos agentes alimentados pela experiência padrão de autoria de harness.

Informações relacionadas

• Descrição geral da telemetria com Application Insights
• Telemetria ao nível do agente com Application Insights
• Exportar dados para o Application Insights
• Aplicação Azure Insights