Depuración de agentes con Agent Inspector en Microsoft Foundry Toolkit

El Inspector de agente de Microsoft Foundry Toolkit para Visual Studio Code le permite enviar solicitudes a un agente local, inspeccionar la actividad del modelo y la herramienta y depurar el código. Úselo para investigar respuestas inesperadas antes de implementar un cambio.

Este flujo de trabajo es útil para los agentes hospedados, que ejecutan el código personalizado en Foundry Agent Service. La inspección local le ayuda a depurar ese código. Antes del uso de producción, pruebe también el agente implementado con su identidad, configuración y acceso de red en tiempo de ejecución.

En este artículo, se conectará a un agente local, investigará una solicitud y guardará los eventos de diagnóstico. La ruta de acceso principal usa el protocolo Responses. Las vistas disponibles dependen del protocolo y los diagnósticos que proporciona el servidor del agente.

Prerequisites

  • Visual Studio Code con la extensión pública actual de Foundry Toolkit. Consulte Instalar Foundry Toolkit.
  • Un proyecto de agente local con sus dependencias, configuración del modelo y credenciales configuradas. Para empezar desde un ejemplo, siga la guía de inicio rápido de Hosted Agent, incluidas las pruebas locales.
  • Depurador requerido por tu proyecto. En el ejemplo de Python se usa la extensión Python y debugpy. Otros lenguajes y ejemplos tienen requisitos diferentes.

Para un proyecto existente, las Foundry Toolkit Copilot tools pueden ayudar a preparar la configuración. Revise los archivos generados y siga las directrices del proyecto README.md. No reemplace los archivos de inicio correspondientes por una configuración genérica.

Importante

Un agente local puede llamar a modelos en la nube y herramientas en tiempo real. Utilice entradas de prueba no confidenciales, compruebe los permisos de la herramienta y tenga en cuenta los cargos de los servicios configurados. Inspector no reemplaza las herramientas con mocks.

Conectar y depurar

Inicie el servidor del agente antes de conectarse a Inspector. Utilice la configuración de inicio generada del proyecto para alinear el servidor, el directorio de trabajo, el intérprete y el depurador.

  1. Inicie el agente con su configuración de depuración documentada. En el ejemplo de Python agente hospedado, seleccione Depurar servidor HTTP del agente local y presione F5.
  2. Si Inspector no está abierto, seleccione Foundry Toolkit en la barra de actividades y, a continuación, Developer Tools>Build>Agent Inspector.
  3. Compruebe el punto de conexión en el encabezado de Inspector. El scaffold actual de Python usa http://localhost:8088. Para un puerto de servidor diferente, seleccione el botón de lápiz situado junto al endpoint, escriba el puerto y seleccione Conectar.
  4. Confirme que el encabezado muestra Conectado. Inspector detecta automáticamente el protocolo de respuestas o invocaciones cuando se puede acceder al punto de conexión.
  5. Establezca un punto de interrupción en el código del agente y envíe un mensaje en el playground. Inspeccione las variables cuando la ejecución se detenga y, a continuación, continúe y revise la respuesta.

Captura de pantalla de la configuración de depuración del agente local y inspector de agente conectado a localhost en el puerto 8088 con una respuesta correcta.

Abrir el Inspector por sí solo no inicia un servidor ni conecta un depurador. La configuración de Python generada usa el puerto 5679 para el depurador y el puerto 8088 para las solicitudes HTTP del agente. Estos puertos son independientes de los puertos de trazado de OTLP.

Conectarse a un endpoint de Responses genérico

Inspector puede conectarse a un punto de conexión de respuestas genérico local sin la interfaz de diagnóstico de desarrollo completa. Puede inspeccionar los eventos de respuestas que envía el servidor, pero el gráfico de flujo de trabajo y su vista de entrada y salida no están disponibles.

Una conexión correcta no significa que el servidor proporcione ubicaciones de origen, uso de tokens o razonamiento.

Envío de una invocación HTTP

Utiliza solicitudes HTTP si tu agente acepta un cuerpo de solicitud personalizado en lugar de un mensaje conversacional. El formato de solicitud del servidor y el protocolo de respuesta determinan cómo Inspector envía y muestra el resultado.

  1. Conéctese al servidor de invocaciones HTTP en ejecución. Inspector detecta automáticamente el protocolo.
  2. Escriba el cuerpo de la solicitud requerido por su agente. Si el servidor expone una especificación openAPI compatible, Inspector puede rellenar un ejemplo. Revíselo antes de enviarlo o siga el formato de solicitud del ejemplo si no hay ningún ejemplo disponible.
  3. Seleccione el engranaje Configuración de solicitud situado junto a la entrada para establecer Content-Type y Accept según lo requiera el servidor. Por ejemplo, use application/json para un cuerpo JSON y text/event-stream cuando el servidor admita una respuesta de streaming.
  4. Seleccione Enviar e inspeccione el estado y el cuerpo de la respuesta.
  5. Cambie entre Vista previa para la salida con formato y Raw para la respuesta subyacente. El panel de detalles también incluye E/S y llamadas de LLM. Los detalles del modelo, la herramienta y el token dependen de eventos de servidor reconocidos, por lo que no todas las respuestas rellenan todas las pestañas.

Inspector controla una respuesta HTTP normal, un flujo de eventos enviados por el servidor o una respuesta asincrónica. Para una respuesta asincrónica 202 Accepted , sondea la invocación hasta la finalización o el error. Al seleccionar un formato de respuesta no se agrega compatibilidad asincrónica ni de streaming al servidor.

Para una respuesta de streaming, Stop desconecta el flujo del cliente. Para una invocación sondeada, Cancel envía una solicitud de cancelación al servidor. Ninguna acción garantiza que el proceso del agente o una operación de herramienta externa se haya detenido.

Esta vista no es un cliente de WebSocket. Los ejemplos del protocolo de actividad usan un playground diferente. Consulte Elegir otro protocolo o muestra para obtener la ruta de acceso de prueba local adecuada.

Usar el Inspector

Comience con una solicitud que ponga a prueba el comportamiento que desea comprender. Por ejemplo, para una herramienta meteorológica, solicite información que requiera esa herramienta, en lugar de una respuesta general que el modelo pueda producir sin ella.

  1. Envíe la solicitud en el playground y revise la respuesta de streaming.
  2. Use las pestañas de detalles para buscar la operación lenta o con errores.
  3. Inspeccione el evento o la llamada a la herramienta pertinentes, cambie el código o la configuración y repita la solicitud.

Presione Intro para enviar o Mayús+Intro para agregar una nueva línea. Para recuperar una solicitud anterior, coloque el cursor al principio de la entrada y presione Flecha arriba. Presione Flecha abajo al final para desplazarse hacia las solicitudes más recientes y volver al borrador sin enviar.

Puede editar una solicitud retirada antes de enviarla. El historial de entrada es una comodidad dentro de Inspector, no un almacén duradero de indicaciones guardadas.

View Úsela para
Overview Siga la cascada de latencia y la cronología de ejecución ordenada. Seleccione todas las ejecuciones o una ejecución para distinguir la actividad del modelo y la herramienta del tiempo entre ejecuciones.
Tokens Revise el uso notificado de tokens de entrada y salida. La ausencia de datos de uso no es un resultado de cero tokens.
Eventos Inspeccione los eventos de Responses analizados, incluidos los errores, las llamadas a funciones y los resultados. Busque por tipo de evento o contenido JSON y filtre por categoría.
Herramientas Inspeccione las llamadas de herramienta agrupadas por ejecución de respuesta, incluido el estado, el identificador de llamada, los argumentos y los resultados.

El pie de página de respuesta muestra información de modelo, duración, uso de tokens y marca de tiempo cuando se proporciona. El texto de razonamiento y los resúmenes de razonamiento aparecen en secciones contraíbles independientes cuando el agente los emite. Inspector no genera el razonamiento que falta ni expone información que el proveedor de modelos no devuelve.

Inspeccionar herramientas y permisos

Usa Herramientas para comprobar si el agente llamó a la herramienta esperada con los argumentos esperados y recibió un resultado. Una respuesta correcta del modelo no demuestra que se ejecutó una herramienta. Si el código usa un mock, el resultado mostrado sigue siendo un resultado de mock.

Captura de pantalla de la pestaña Herramientas con llamadas agrupadas por ejecución y una llamada de herramienta expandida que muestra sus argumentos y el resultado.

Cuando una respuesta se detiene para la aprobación del Protocolo de contexto de modelo (MCP) o el consentimiento de OAuth, las solicitudes pendientes aparecen encima de la entrada del mensaje. Conceda solo el acceso que quiere permitir.

Para una llamada a la herramienta MCP, seleccione Mostrar argumentos, revise las entradas y, a continuación, seleccione Aprobar o Denegar. Aprobar todas y Denegar todas se aplican a las solicitudes pendientes, no a una directiva de aprobación de herramientas permanente.

Para el consentimiento de OAuth, complete la autorización del navegador y la confirmación del inspector:

  1. Seleccione Abrir consentimiento para la solicitud pendiente.
  2. Complete la autorización en el explorador, vuelva a Inspector y seleccione Consentimiento completado. Para rechazar la autorización, seleccione Cancelar en su lugar.
  3. Resuelva las solicitudes de consentimiento restantes. Use All done, cuando esté disponible, solo después de completar la autorización de todas las solicitudes abiertas.

Abrir una página de consentimiento solo no reanuda la solicitud. Inspector espera una decisión sobre cada consentimiento pendiente antes de volver a comprobar el servidor. Las solicitudes pueden volver a aparecer si el servidor todavía necesita autorización.

Compruebe el resultado posterior de la herramienta, no solo la aprobación, para confirmar la finalización. Para la configuración de la conexión y la autenticación, consulte Catálogo de herramientas. No cambie las credenciales de la herramienta ni los permisos únicamente para que desaparezca un error de diagnóstico.

Inspeccionar flujos de trabajo y código fuente

Para los flujos de trabajo de Microsoft Agent Framework admitidos, el servidor de desarrollo puede proporcionar diagnósticos de flujo de trabajo y ubicaciones de origen. Inspector usa esta información para mostrar el gráfico de ejecución y ayudarle a navegar al código.

  1. Seleccione un nodo de flujo de trabajo para inspeccionar las entradas y salidas disponibles.
  2. Haga doble clic en el nodo para abrir su ubicación de código fuente.
  3. Establezca un punto de interrupción y repita la solicitud para inspeccionar la operación en el depurador.

Puede probar los flujos de trabajo de LangGraph en Playground, pero no se admite la visualización del flujo de trabajo para ellos. Un servidor sin metadatos de flujo de trabajo todavía puede devolver eventos de respuesta útiles.

Investigar errores con Copilot

Usa las acciones de error en Eventos para preparar una solicitud centrada para GitHub Copilot en lugar de copiar toda la conversación.

  1. Busque el evento fallido y revise sus detalles en busca de contenido sensible antes de compartirlos.
  2. Seleccione Corregir junto al evento fallido para preparar un mensaje para ese error. En el caso de varios errores, restrinja la lista con filtros de búsqueda y categoría y, a continuación, seleccione Resolver con Copilot. Esta acción incluye los errores visibles.
  3. Revise el mensaje preparado en GitHub Copilot Chat antes de enviarlo. Revise los cambios propuestos y vuelva a ejecutar la solicitud del agente original para confirmar el resultado.

Estas acciones no requieren el collector de OTLP. La preparación de un mensaje de diagnóstico no corrige el agente ni vuelve a ejecutar la operación fallida.

Captura de pantalla de la pestaña Eventos con respuestas con errores, controles de búsqueda y filtro, acciones de exportación y detalles de diagnóstico preparados en Copilot Chat.

Guardar eventos de diagnóstico

Guarde una instantánea de evento para comparar un error con una ejecución posterior o comparta una reproducción específica.

  1. En Eventos, restrinja la lista con el campo de búsqueda y el filtro de categoría.
  2. Seleccione Copiar eventos visibles para copiar los eventos filtrados como JSONL. Como alternativa, seleccione Descargar eventos visibles para abrir el archivo exportado en VS Code.
  3. Para el archivo abierto, use Archivo>Guardar como para guardar una copia en una ubicación que controle antes de cerrar el documento. La exportación abierta es un archivo temporal, no una descarga permanente.

La instantánea contiene los eventos visibles al seleccionar la acción, no los eventos futuros del agente en ejecución. No guarda una versión del agente, ni implementa código ni crea historial de seguimiento en la nube.

Caution

Los eventos pueden incluir instrucciones, respuestas, argumentos de herramienta, resultados y detalles de error. Revise y oculte contenido confidencial antes de guardar o compartir una exportación.

Iniciar una conversación nueva

Seleccione Borrar chat para iniciar una nueva conversación y borrar el estado de Chat, Eventos y Detalles. Exporte los eventos de diagnóstico que necesite en primer lugar. Al actualizar el mismo agente conectado se conserva su estado de inspección, mientras que el cambio de agentes borra el estado obsoleto.

En el caso de las respuestas, Clear Chat está deshabilitado mientras una respuesta se está transmitiendo. Permanece disponible cuando el proceso se detiene para su aprobación o consentimiento. No es un comando general para detener tu agente.

No confíe en el estado del inspector local como un archivo de conversación duradero. El servidor gestiona la persistencia de conversación, que puede diferir entre el desarrollo local y un agente alojado desplegado. Al borrar Inspector no se eliminan los seguimientos ya recopilados localmente ni almacenados en Application Insights.

Diferencias entre Inspector y rastreo

Inspector se comunica con el servidor local a través de HTTP y transmite eventos de respuesta. Un servidor de desarrollo compatible también proporciona un flujo de diagnóstico independiente para los detalles del flujo de trabajo y la navegación de origen. El depurador se adjunta al proceso en ejecución de forma independiente.

Estos diagnósticos en directo no requieren el recopilador de OTLP local. La pestaña Trazas del inspector abre el visor de seguimiento independiente. No convierte los eventos de protocolo en spans de OpenTelemetry almacenados.

Para recopilar spans para el análisis posterior, configure el seguimiento local. En el caso de los agentes desplegados, use seguimientos del agente hospedado.

Después de las pruebas locales, implemente el agente hospedado. Pruébelo por separado porque su identidad, entorno y acceso a la red difieren del proceso local.

Troubleshooting

Problema Elementos que se deben comprobar
Inspector no se puede conectar. Compruebe el terminal del agente para ver si hay errores de inicio. Confirme el intérprete, las dependencias y el puerto HTTP y vuelva a conectarse al puerto que notifica el servidor. Abrir el Inspector no inicia el proceso.
Una solicitud se realiza correctamente, pero los puntos de interrupción no se activan. Confirme que el depurador está asociado al proceso que atiende la solicitud y usa el directorio de origen correcto. Para Python, consulte solución de problemas de depuración.
Falta el gráfico o la navegación del origen. Confirme que el servidor y el flujo de trabajo proporcionan diagnósticos de desarrollo y ubicaciones de origen. La inspección de respuestas genéricas no proporciona estas funcionalidades. Los flujos de trabajo de LangGraph funcionan en el playground sin visualización de flujo de trabajo.
Faltan los resultados de la herramienta. Compruebe Eventos para ver errores y aprobaciones pendientes. Confirme que la solicitud requiere una herramienta y que la herramienta está configurada y accesible.
Faltan detalles de token o razonamiento. Compruebe qué emite el modelo y el servidor. Inspector solo puede mostrar la información que proporcionen.
Las imágenes remotas están bloqueadas. Seleccione Cargar imágenes remotas solo si desea que Inspector las obtenga de hosts remotos. Este permiso de pantalla no es una aprobación de la herramienta. Las direcciones URL o el contenido no admitidos pueden seguir sin cargarse. Que falte una imagen no significa necesariamente que la solicitud del agente haya fallado.
Se interrumpe el flujo de respuesta. Revise la respuesta parcial y los detalles del fallo. Vuelva a conectarse si es necesario y revise las aprobaciones pendientes antes de reintentar. Un reintento puede repetir acciones de herramienta en vivo.
Inspector tiene eventos, pero el visor de seguimiento está vacío. Los eventos de protocolo y los spans de OTLP son diferentes. Configure la instrumentación e inicie el recopilador.

Contenido relacionado

  • Se actualizó por última vez el