Telemetría a nivel de entorno con Application Insights (vista previa)

[Este artículo es documentación preliminar y está sujeto a cambios.]

Utiliza Aplicación de Azure Insights para monitorizar las trazas de agentes de Copilot Studio exportadas desde un entorno gestionado. Después de configurar la exportación, utiliza Azure Monitor y Application Insights para validar las ejecuciones de agentes, monitorizar la ejecución de nodos y herramientas, crear alertas y crear consultas y paneles personalizados para análisis operativo.

Este artículo explica cómo configurar la exportación a nivel de entorno de los trazos de agentes de Copilot Studio a Aplicación de Azure Insights a través del centro de administración de Power Platform.

Prerequisites

Antes de configurar la conexión de exportación de datos, completa los requisitos previos de Exportar datos a Application Insights.

Qué es lo que se exporta

Al habilitar la exportación, la telemetría de trazas de los agentes de Copilot Studio se envía a Application Insights en un formato de observabilidad orientado a trazas y alineado con OpenTelemetry que admite la investigación, los paneles y las alertas.

Los eventos del agente de Copilot Studio se escriben en la tabla dependencies como intervalos. Cada evento exportado (InvokeAgent, ExecuteTool y OutputMessages) corresponde a una sola fila de span (itemType = dependency).

Cómo los spans forman una traza

La telemetría sigue el modelo de trazas y spans de OpenTelemetry y se reconstruye a través de las columnas operation_Id y operation_ParentId:

• Cada turno del agente es su propia traza, identificada por un operation_Id compartido que permite a Application Insights agrupar el turno y mostrarlo en la vista de transacciones de extremo a extremo.
• El InvokeAgent tramo es la raíz de la traza de su giro. Su ExecuteTool y los OutputMessages conectados se anidan debajo de él, cada uno con operation_ParentId = InvokeAgent del intervalo id.
• Una conversación se desarrolla a lo largo de varios turnos, cada uno registrado como una traza independiente. Agrupa o filtra por gen_ai.conversation.id para volver a unir las intervenciones de una misma conversación.
• OutputMessages Los spans no siempre emiten una InvokeAgent raíz, lo que significa que pueden (por diseño) llegar sin un padre coincidente y aparecer como una traza independiente de un solo nodo.

Crear un paquete de exportación

Crea un paquete de exportación con el tipo de exportación configurado en Copilot Studio siguiendo las instrucciones en Crear un paquete de exportación de la documentación del centro de administración de Power Platform.

Validación de la configuración

Después de guardar la configuración de exportación, ejecuta una conversación de prueba con el agente y confirma que la telemetría llega a Application Insights. La entrega de telemetría puede tardar hasta 24 horas en nuevas configuraciones. Valide que:

• Los spans de agente aparecen en la tabla dependencies.
• Los segmentos InvokeAgent, ExecuteTool y OutputMessages de cada turno comparten un operation_Id.

Campos de Application Insights

La siguiente tabla muestra los campos de la dependencies tabla y qué campos se rellenan para cada uno de los tres eventos de agente exportados: InvokeAgent, ExecuteTool, y OutputMessages. La semántica de agentes y operaciones está en customDimensions (las gen_ai.* claves, como gen_ai.operation.name), no en las columnas nativas.

Propiedades de las dimensiones personalizadas

Cada tramo incluye el customDimensions JSON. La siguiente tabla muestra las claves comunes que aparecen en cada tramo:

Claves específicas para eventos

La siguiente tabla muestra las claves específicas de cada evento:

Descubre el esquema actual

El esquema documentado en este artículo podría evolucionar con el tiempo. En lugar de basarte únicamente en las tablas mencionadas anteriormente, utiliza las siguientes consultas para inspeccionar el esquema más reciente en vivo en tu propio entorno.

Lista de columnas nativas de la tabla

La siguiente consulta devuelve el esquema a nivel de columna de la dependencies tabla. Úsalo para confirmar columnas nativas disponibles al crear consultas, paneles de control o alertas.

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

Descubre claves de dimensiones personalizadas (propiedades dinámicas)

La siguiente consulta lista todas las claves dentro del customDimensions JSON en la dependencies tabla: el nombre de la propiedad, en qué eventos del agente aparece (InvokeAgent, ExecuteTool, OutputMessages), y un valor de muestra. A diferencia del esquema de columnas nativo, estas propiedades son dinámicas, por lo que esta consulta se mantiene precisa a medida que el SDK añade nuevas gen_ai.* u otras claves. Úsalo como fuente viva de verdad para los atributos disponibles.

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

Supervisar la telemetría exportada

Usa los registros de Logs de Application Insights para consultar la actividad del agente e investigar la ejecución del agente o de herramientas. Toda la telemetría exportada se almacena en la tabla dependencies en forma de spans:

• Cada turno del agente es una traza, agrupada por un operation_Id compartido.
• El InvokeAgent span es la raíz de la traza; ExecuteTool y OutputMessages spans se anidan bajo él mediante operation_ParentId.
• Agrupa por gen_ai.conversation.id para agrupar en un hilo varios turnos de la misma conversación, y divide ese ID en _ para incluir trazas de subagentes.

Paneles de Agentes en versión preliminar

Además de los Logs, Application Insights ofrece vistas integradas de Agentes (vista previa) que visualizan la telemetría GenAI exportada sin necesidad de escribir consultas Kusto. A medida que Copilot Studio escribe sus intervalos en la tabla dependencies, estos paneles leen esos datos directamente:

• Ejecuciones de agentes: Enumera las invocaciones de agentes creadas a partir de los InvokeAgent tramos, con su duración, éxito y la conversación a la que pertenece cada ejecución. Existen algunas limitaciones; Aprende más en Limitaciones y consideraciones conocidas.
• Herramientas: Agrega los ExecuteTool spans para mostrar qué herramientas llaman los agentes, con qué frecuencia y cómo actúan.
• Modelos: Resume el uso del modelo a lo largo de las ejecuciones, mostrando los modelos invocados y sus patrones de llamada.

Analizar la telemetría de agentes con Application Insights

Después de conectar tu entorno a Application Insights, este registra los datos de telemetría del agente cuando los usuarios interactúan con el agente, incluyendo durante las pruebas dentro de Copilot Studio. Para ver los datos de telemetría registrados, ve a la sección de Logs de tu recurso Application Insights en Azure. Aquí, puedes usar consultas Kusto para consultar y analizar tus datos. Aprende más en Consultas de ejemplo.

Consultas de ejemplo

Los siguientes ejemplos de consultas de Kusto reconstruyen las conversaciones de los agentes de Copilot Studio a partir de la dependencies tabla en Application Insights. Como cada span comparte una traza operation_Id en cada turno, las consultas ordenan los spans empezando por la raíz (el span InvokeAgent antes que sus spans hijos) dentro de cada traza.

Consulta 1: Devuelve un trazo completo para un ID de conversación específico

Esta consulta devuelve todos los spans de una conversación conocida, ordenados cronológicamente, con cada span raíz situado antes que sus spans hijo. Reemplaza el marcador ID de conversación por el ID de conversación de tu agente. Puedes encontrarlo introduciendo el siguiente comando mientras pruebas tu 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: Obtener la conversación más reciente de un agente específico

Esta consulta encuentra la conversación más reciente de un agente nombrado dentro del periodo especificado. Devuelve cada tramo de esa conversación en el mismo orden cronológico, raíz primero. Sustituye el marcador de posición nombre del agente por el nombre de tu 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: Desglosar las propiedades conocidas de OpenTelemetry para genAI en columnas

Esta consulta devuelve la misma traza que la consulta 2, pero también analiza cada clave conocida de convención semántica de OpenTelemetry en su propia columna nombrada. El resultado es una tabla plana y definida explícitamente donde puedes ordenar, filtrar y escanear los campos de IA generativa como nombre de herramienta, modelo, prompt de usuario, respuesta del agente e ID de conversación directamente. Sustituye el marcador de posición nombre del agente por el nombre de tu 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 dinámicamente todas las propiedades de OpenTelemetry de GenAI

Esta consulta devuelve los mismos intervalos que la consulta 3, pero cada clave gen_ai.* se desempaqueta dinámicamente de customDimensions en su propia columna con prefijo ga_. Como la proyección es dinámica, cualquier nuevo gen_ai.* atributo que el SDK emita posteriormente aparece automáticamente sin cambiar la consulta. Sustituye el marcador de posición nombre del agente por el nombre de tu 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 la última conversación para un agente raíz con todos sus hijos, incluidos los subagentes

Esta consulta devuelve la conversación más reciente para un agente nombrado. Devuelve cada intervalo de esa conversación y de todos los subagentes de primer nivel que invocó. Cuando un agente llama a otro agente usándolo como herramienta, el subagente hereda el ID de conversación del padre con el sufijo _<subConversationId>. Todo el árbol se reconstruye haciendo coincidencia en el ID de nivel superior. Sustituye el marcador de posición nombre del agente por el nombre de tu 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

Limitaciones y consideraciones conocidas

• El valor duration no está disponible para las trazas de agentes clásicas.
• Actualmente, los errores en la ejecución de agentes y herramientas no se reflejan correctamente en los estados de las trazas.
• Según tus requisitos de residencia de datos, quizá quieras utilizar recursos dedicados a Application Insights para cada región del entorno.
• Los spans de subagente actualmente tienen como span padre el InvokeAgent que invocó al agente, en lugar del InvokeAgent dentro de su propia traza.
• Actualmente, los IDs de traza y de span se emiten como GUID (con prefijo cuando es necesario) en lugar de como IDs de traza de 32 caracteres hexadecimales e IDs de span de 16 caracteres hexadecimales, totalmente conformes con el estándar OpenTelemetry.
• Asegúrate de que la autenticación local esté activada en el recurso objetivo de Application Insights.
• La exportación de telemetría no es transaccional. Durante eventos de servicio transitorios, pueden producirse pequeñas pérdidas de datos.
• Pueden producirse inconsistencias en los datos a medida que se implementan actualizaciones de ingestión relacionadas con el esquema.
• Eventos relacionados con temas como TopicStart, TopicAction, y TopicEnd no se capturan con telemetría a nivel de entorno.
• Para simplificar la elaboración de informes y la resolución de problemas, evita enviar tanto telemetría a nivel de agente como de entorno a la misma instancia de Application Insights.
• La telemetría emitida para los agentes creados en los agentes impulsados por GitHub Copilot puede diferir de la de los agentes construidos en los agentes con experiencia de creación de arnés estándar.

Información relacionada

• Visión general de Telemetría con Application Insights
• Telemetría a nivel de agente con Application Insights
• Exportar datos a Application Insights
• Aplicación de Azure Insights