Visión general del seguimiento de agentes

Importante

Los elementos marcados (versión preliminar) de este artículo se encuentran actualmente en versión preliminar pública. Esta versión preliminar se proporciona sin un contrato de nivel de servicio y no se recomienda para cargas de trabajo de producción. Es posible que algunas características no se admitan o que tengan funcionalidades restringidas. Para obtener más información, vea Supplemental Terms of Use for Microsoft Azure Previews.

Nota

La trazabilidad está disponible de forma general para los agentes de prompt y los agentes hospedados. El flujo de trabajo y los agentes externos están en versión preliminar.

Microsoft Foundry proporciona una plataforma de observabilidad para la supervisión y el seguimiento de agentes de inteligencia artificial. Captura los detalles clave durante una ejecución del agente, como entradas, salidas, uso de herramientas, reintentos, latencias y costos. Reconocimiento del razonamiento detrás de las ejecuciones del agente es importante para solucionar problemas y depurar. Sin embargo, comprender los agentes complejos presenta desafíos por varias razones:

  • Puede haber un gran número de pasos implicados en la generación de una respuesta, por lo que es difícil realizar un seguimiento de todos ellos.
  • La secuencia de pasos puede variar en función de la entrada del usuario.
  • Las entradas y salidas en cada fase pueden ser extensas y merecen una inspección más detallada.
  • Cada paso del entorno de ejecución de un agente también puede implicar anidamiento. Por ejemplo, un agente podría invocar una herramienta, que usa otro proceso, que luego invoca otra herramienta. Si observa una salida extraña o incorrecta de una ejecución de agente de nivel superior, puede ser difícil determinar exactamente dónde se introdujo el problema en la ejecución.

Los seguimientos abordan estos desafíos al permitirle ver las entradas y salidas de cada primitivo implicado en una ejecución de agente determinada, que se muestran en el orden en que se invocaron, lo que facilita la comprensión y depuración del comportamiento del agente de IA.

Requisitos previos

Para usar el seguimiento de un extremo a otro, es necesario que:

Nota

El seguimiento almacena datos de telemetría en Azure Monitor Application Insights, lo que podría incurrir en costos en función de la configuración de retención y volumen de datos. Para más información sobre los precios, consulte Precios de Application Insights.

OpenTelemetry en Foundry

OpenTelemetry (OTel) proporciona protocolos estandarizados para recopilar y enrutar datos de telemetría. Foundry usa convenciones semánticas de OpenTelemetry, por lo que los seguimientos son coherentes en las herramientas e integraciones admitidas.

Rastrear conceptos clave

Los siguientes conceptos clave se aplican a lo largo de este artículo:

Conceptos clave Descripción
Seguimientos Los seguimientos capturan el recorrido de una solicitud o flujo de trabajo a través de la aplicación mediante la grabación de eventos y cambios de estado (llamadas de función, valores, eventos del sistema). Consulte Seguimientos de OpenTelemetry.
Intervalos Los intervalos son los bloques de creación de seguimientos, que representan operaciones únicas dentro de un seguimiento. Cada traza captura la hora de inicio y de finalización, los atributos, y puede anidarse para mostrar relaciones jerárquicas, lo que permite ver la pila de llamadas completa y la secuencia de operaciones.
Atributos Los atributos son pares clave-valor asociados a seguimientos e intervalos que proporcionan metadatos contextuales como parámetros de función, valores devueltos o anotaciones personalizadas. Estos enriquecen los datos de seguimiento, lo que hace que sea más informativo y útil para el análisis.
Convenciones semánticas OpenTelemetry define convenciones semánticas para estandarizar nombres y formatos para atributos de datos de seguimiento, lo que facilita la interpretación y el análisis entre herramientas y plataformas. Para más información, consulte las convenciones semánticas de GenAI de OpenTelemetry.
Exportadores de seguimiento Los exportadores de seguimiento envían datos de seguimiento a los sistemas back-end para el almacenamiento y el análisis. En Foundry, los seguimientos se almacenan en Azure Monitor Application Insights. Para obtener información sobre cómo habilitar y ver seguimientos, consulte Cómo configurar el seguimiento en Microsoft Foundry.

Cómo funciona el seguimiento en Foundry

El seguimiento le ayuda a responder a preguntas como "¿De dónde procede esta respuesta?" y "¿Qué paso introdujo un pico de error o latencia?"

A nivel general, el seguimiento captura:

  • Entradas de usuario y salidas del agente.
  • Uso de herramientas, incluidas las llamadas a herramientas y los resultados.
  • Consumo de tokens.
  • Señales de tiempo como la duración y la latencia.

Al habilitar el seguimiento del proyecto, puede inspeccionar los seguimientos en el portal de Foundry y en Azure Monitor Application Insights. Para ver las opciones de configuración y visualización paso a paso, consulte Cómo configurar el seguimiento en Microsoft Foundry.

Ampliación de OpenTelemetry con observabilidad multiagente

Microsoft, en colaboración con Cisco Outshift, contribuye a convenciones semánticas para sistemas multiagente. Estas convenciones se basan en el agente y marco de OpenTelemetry GenAI y elcontexto de seguimiento de W3C. Normalizan la telemetría de los flujos de trabajo de varios agentes, incluidas las invocaciones del agente, la orquestación del flujo de trabajo, la planeación, las llamadas de modelo y la ejecución de herramientas.

Importante

Las convenciones semánticas de OpenTelemetry GenAI tienen el estado desarrollo y pueden cambiar en futuras versiones.

Estas mejoras se integran en:

  • Fábrica
  • Framework del Agente de Microsoft
  • LangChain
  • LangGraph
  • SDK de agentes de OpenAI

Para más información, consulte Integraciones de seguimiento.

En la tabla siguiente se describen las convenciones comunes de OpenTelemetry GenAI para la observabilidad multiagente. Los intervalos capturan operaciones, los intervalos secundarios muestran trabajo anidado y los atributos proporcionan metadatos. Los intervalos primarios mostrados son ejemplos comunes; El anidamiento real depende del agente instrumentado o del marco.

Tipo Contexto/Intervalo principal Nombre/Atributo/Evento Propósito
Intervalo — invoke_agent Invoca un agente a través de un servicio remoto o dentro del mismo proceso.
Intervalo secundario invoke_agent invoke_agent Rastrea una invocación de otro agente a través de una relación de span padre-hijo.
span hijo invoke_agent plan Registra una fase de planificación del agente o de descomposición de tareas.
Intervalo — invoke_workflow Invoca un flujo de trabajo coordinado que contiene agentes u otras operaciones de IA generativas.
span hijo invoke_agent o invoke_workflow execute_tool Registra una ejecución de herramientas.
span hijo invoke_agent o invoke_workflow create_memory, search_memory, update_memory, upsert_memory o delete_memory Registra una operación de memoria.
Atributo invoke_agent gen_ai.tool.definitions Registra las definiciones de herramientas disponibles para un agente o modelo.
Atributo execute_tool gen_ai.tool.call.arguments Registra los argumentos proporcionados en una llamada a una herramienta.
Atributo execute_tool gen_ai.tool.call.result Registra el resultado devuelto por una invocación correcta de una herramienta.

Procedimientos recomendados

  • Usar atributos de intervalo coherentes: aplique los mismos nombres y formatos de atributo en todos los agentes y herramientas para simplificar la consulta y el análisis.
  • Correlacionar identificadores de ejecución de evaluación: vincule los datos de seguimiento con ejecuciones de evaluación para analizar la calidad y el rendimiento en una vista unificada.
  • Ocultar contenido confidencial: elimine o enmascare los datos personales, los secretos y las credenciales de las solicitudes, los argumentos de la herramienta y los atributos de extensión, antes de que lleguen a la telemetría.

Seguridad y privacidad

El seguimiento puede capturar información confidencial, como entradas de usuario, salidas del modelo y argumentos y resultados de la herramienta. Use estas prácticas para reducir el riesgo:

  • No almacena secretos, credenciales ni tokens en solicitudes, argumentos de herramienta ni atributos de intervalo.
  • Redacte o minimice los datos personales y otro contenido confidencial antes de que aparezca en la telemetría.
  • Trate los datos de seguimiento como telemetría de producción y aplique los mismos controles de acceso y directivas de retención que use para los registros y las métricas.

Para obtener información sobre los pasos para enrutar el contenido confidencial a la tabla dedicada y restringir el acceso a él, consulte Restringir el acceso a contenido confidencial.

Solución de problemas

Si las trazas no aparecen en el portal Foundry o en Application Insights:

  • Compruebe que el proyecto foundry está conectado a un recurso de Application Insights.
  • Compruebe que la cuenta tiene los permisos necesarios para consultar la telemetría.
  • Asegúrese de que el código del agente incluye la instrumentación necesaria. Para la configuración específica del marco, consulte Integraciones de seguimiento.

Sugerencia

El seguimiento está disponible en todas las regiones donde Foundry es compatible. La retención y el muestreo de datos de seguimiento siguen la configuración de Application Insights. Para obtener más información, consulte Data retention and archive in Azure Monitor Logs.

Contenido relacionado

  • Last updated on