Configuración del seguimiento en Microsoft Foundry

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.

Use el seguimiento para depurar los agentes de IA y supervisar su comportamiento en producción. El seguimiento captura datos de telemetría detallados, incluida la latencia, las excepciones, el contenido de la solicitud y las operaciones de recuperación, para que pueda identificar y corregir problemas más rápido.

El punto de partida recomendado es seguimiento del lado servidor. Foundry lo habilita automáticamente después de conectar un recurso de Application Insights al proyecto. No se requieren cambios de código y los seguimientos están disponibles en cuestión de minutos después de habilitarlo. El seguimiento del lado servidor funciona para cualquier agente hospedado en Foundry. Cuando necesite visibilidad en su propio código de aplicación (por ejemplo, para realizar un seguimiento de la lógica personalizada que rodea a una llamada de agente), puede agregar instrumentación del lado cliente como segundo paso.

La Microsoft Foundry Skill puede ayudar a elegir entre el trazado del lado del servidor o del lado del cliente, y a solucionar problemas de falta de telemetría.

Requisitos previos

Conexión de Application Insights al proyecto de Foundry

Foundry almacena seguimientos en Application Insights mediante convenciones semánticas de OpenTelemetry.

  1. Inicie sesión en Microsoft Foundry. Asegúrese de que el interruptor New Foundry esté activado. Estos pasos hacen referencia a Foundry (new).

  2. Abre el proyecto Foundry.

  3. En el panel de navegación izquierdo, seleccione Agentes.

  4. En la parte superior, seleccione Trazas.

  5. A la derecha, seleccione Conectar para crear o conectar un recurso de Application Insights.

    Captura de pantalla de la pestaña Agentes en la que se muestran seguimientos y el botón Conectar.

  • Para conectar un recurso existente, seleccione el recurso y, a continuación, seleccione Conectar.
  • Para crear un nuevo recurso, seleccione Crear nuevo y a continuación complete el asistente.

Aparece un mensaje de confirmación cuando la conexión se realiza correctamente.

Usar la ruta de conexión de los detalles del proyecto

Si no ve la barra de mensajes o el botón Conectar, use esta manera alternativa de habilitar Azure Monitor Application Insights.

  1. Seleccione Administrar en la navegación superior derecha y, a continuación, seleccione Detalles del proyecto. Captura de pantalla de la sección Administrar con la opción Detalles del proyecto resaltada.
  2. Seleccione la pestaña Recursos conectados y, a continuación, seleccione Agregar conexión. Captura de pantalla de los detalles del proyecto con la pestaña Recursos conectados seleccionada y el botón Agregar una conexión resaltado.
  3. En Elegir una conexión, seleccione Application Insights. Captura de pantalla de Elegir una conexión con Application Insights resaltada.

Para la ingesta de trazas autenticada con Entra, consulte Configurar la autenticación de Microsoft Entra para la ingesta de trazas del agente de Foundry (versión preliminar).

Después de conectar el recurso, el proyecto está listo para usar el seguimiento.

Importante

Asegúrese de que tiene los permisos necesarios para consultar la telemetría.

Instrumentar agentes de IA

Elija el enfoque que coincida con cómo construye y ejecuta su agente.

Seguimientos del lado servidor en el portal de Foundry

Comience con seguimientos del lado servidor. Foundry registra trazas para escenarios comunes de agentes y flujos de trabajo sin cambiar tu código.

  • Foundry registra automáticamente las trazas del lado del servidor para los agentes de Prompt, los agentes anfitrión y los flujos de trabajo en el portal de Foundry. Después de habilitar el seguimiento en el proyecto foundry, tiene acceso a seguimientos predefinidos durante los últimos 90 días.
  • Foundry también admite una integración sencilla con los principales marcos de agente.

Seguimientos del lado cliente con el SDK de Microsoft Foundry (Python)

Instale OpenTelemetry y el complemento de seguimiento de SDK de Azure mediante los pasos siguientes:

pip install azure-ai-projects azure-identity opentelemetry-sdk azure-core-tracing-opentelemetry

Referencia: azure-ai-projects, azure-core-tracing-opentelemetry

Importante

Para usar el punto de conexión de un proyecto en la aplicación, debe configurar Microsoft Entra ID. Si no establece Microsoft Entra ID, use la cadena de conexión de Application Insights.

Después de ejecutar tu agente, puedes ver y analizar trazas en el portal Foundry.

Para obtener instrucciones detalladas y ejemplos de código específicos del SDK, consulte Tracing with azure-ai-projects (Python SDK) y Telemetry samples for agents.

Realice un seguimiento local con la extensión Microsoft Foundry Toolkit para Visual Studio Code

La extensión Microsoft Foundry Toolkit for Visual Studio Code permite realizar un seguimiento local en VS Code mediante un recopilador compatible con OTLP local. Este enfoque es ideal para el desarrollo y la depuración.

El kit de herramientas admite marcos de inteligencia artificial como Foundry Agent Service, OpenAI, Anthropic y LangChain a través de OpenTelemetry. Puede ver seguimientos al instante en VS Code sin necesidad de acceso a la nube.

Para obtener instrucciones de configuración detalladas y ejemplos de código específicos del SDK, consulte Seguimiento en Foundry Toolkit.

Visualización y análisis de trazas

Ver rastros en el portal de Foundry

En el proyecto Foundry, vaya a la pestaña Seguimientos de los agentes o flujos de trabajo. Puede buscar, filtrar o ordenar trazas ingeridas de los últimos 90 días.

Seleccione un seguimiento para recorrer cada intervalo, identificar problemas y observar cómo responde la aplicación. Este proceso le ayuda a depurar e identificar problemas en la aplicación.

Visualizar trazas en Azure Monitor

Sus rastros se envían a Azure Monitor Application Insights, y puede verlos allí.

Para obtener más información sobre cómo enviar trazas a Azure Monitor y crear un recurso de Azure Monitor, consulte la documentación de Azure Monitor OpenTelemetry.

Visualización de los resultados de la conversación

Una conversación es el contexto persistente de un historial de diálogos de un extremo a otro entre un usuario y un agente. En el portal Foundry, puedes ver los resultados de Conversación para tu agente listo para usar junto con trazas en la página Trazas.

Busque por ID de respuesta o por un ID de rastreo asociado a esta conversación. A continuación, seleccione un identificador de conversación para revisar:

  • Detalles del historial de conversaciones
  • Información de respuesta y tokens en una ejecución
  • Acciones ordenadas, pasos de ejecución y llamadas a herramientas
  • Entradas y salidas entre un usuario y un agente

Captura de pantalla del panel Detalles de la conversación en Foundry que muestra un identificador de conversación con una escala de tiempo de seguimiento y detalles del paso de ejecución.

Comprobación de que el seguimiento funciona

  1. Confirme que el proyecto está conectado a Application Insights. Si es necesario, siga los pasos descritos en Conectar Application Insights a su proyecto Foundry.

  2. Ejecute el agente o el flujo de trabajo al menos una vez (por ejemplo, mediante el portal o la aplicación).

  3. En el proyecto Foundry, abra la vista Seguimientos y confirme que aparece un nuevo seguimiento.

    Cuando el seguimiento funciona correctamente, verá una lista de seguimientos recientes con marcas de tiempo, duraciones e indicadores de estado. Seleccione una traza para ver los detalles de su extensión.

Si no ve nuevos seguimientos, espere unos minutos y actualice y, a continuación, consulte Solución de problemas.

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 más instrucciones, consulte Seguridad y privacidad.

Retención y costo de datos

Foundry almacena seguimientos en el recurso de Application Insights conectado al proyecto. La retención y la facturación de datos siguen la configuración de Application Insights y Log Analytics.

Solución de problemas

Problema Causa Resolución
No ve ningún rastro en el portal de Foundry El seguimiento no está conectado, no hay tráfico reciente, o el procesamiento está retrasado. Confirme la conexión de Application Insights, genere el nuevo tráfico del agente y actualice después de unos minutos.
Verá errores de autorización al consultar o ver la telemetría. Faltan permisos de RBAC en Application Insights o Log Analytics Confirme el acceso en Control de acceso (IAM) para los recursos conectados. Para las consultas de registro, asigne el rol de lector de Log Analytics. Si las tablas están protegidas, asigne también lector de datos de supervisión con privilegios.
Los rastros del lado del cliente no aparecen La instrumentación no está instalada ni configurada Vuelva a comprobar la instalación del paquete y siga las instrucciones del SDK vinculadas en Seguimientos del lado cliente con el SDK de Microsoft Foundry (Python).
Aparece contenido confidencial en registros Las indicaciones, los argumentos de la herramienta o las salidas contienen datos confidenciales Redacte datos confidenciales antes de que entre en telemetría y siga las instrucciones de Seguridad y privacidad.

Contenido relacionado

Ahora que configuró el seguimiento, explore estos recursos para profundizar en la comprensión y ampliar las funcionalidades de observabilidad:

  • Last updated on