Usar el modo de desarrollador para probar y depurar agentes en Microsoft 365 Agents Toolkit

Recomendación

Recomendado: Comience con las herramientas de desarrollo de Work IQ para escenarios de complemento y agente declarativo de código profesional compatibles. Consulte el inicio rápido de WIQD. Las instrucciones basadas en el kit de herramientas siguen estando disponibles para los proyectos existentes y los flujos de trabajo que las requieren. Compruebe la compatibilidad con la capacidad y la experiencia de destino antes de elegir una herramienta: WIQD no se dirige a agentes de motor personalizados.

Las pruebas son una parte importante del proceso de desarrollo de agentes declarativos para Microsoft 365 Copilot Chat. Puede usar el modo de desarrollador mientras prueba el agente para verificar si Copilot Orchestrator selecciona los orígenes de conocimiento para usarlos en respuesta a indicaciones determinadas.

Además, puede usar la característica Vista previa de la aplicación (F5) en el Kit de herramientas de agentes de Microsoft 365 para probar los agentes en un entorno de desarrollo local. Esta característica proporciona una manera interactiva de validar el comportamiento y solucionar problemas directamente desde la interfaz de desarrollo.

Usar el modo de desarrollador en Copilot Chat y Agents Toolkit

Puede probar el agente desde el Kit de herramientas de agentes en Visual Studio Code seleccionando Vista previa de la aplicación (F5) en el panel Kit de herramientas de agentes. Esto inicia al agente en una experiencia de Copilot Chat basada en explorador, lo que le permite validar rápidamente cómo se comporta en respuesta a las indicaciones.

Captura de pantalla de Visual Studio Code que muestra la característica

Una vez que seleccione su agente en Microsoft 365 Copilot Chat, habilite el modo de desarrollador escribiendo -developer on. Para deshabilitar el modo de desarrollador, escriba -developer off.

Captura de pantalla de la sesión de Copilot Chat en la que el usuario escribió

Mientras el modo de desarrollador está habilitado, se devuelve una tarjeta con información de depuración cada vez que el orquestador busca en su empresa conocimientos (datos), capacidades o habilidades (acciones o complementos) dentro de su agente. En el kit de herramientas del agente, esta información de depuración aparece en el panel Depurar e incluye los siguientes campos:

  • Metadatos del agente: identificadores para el agente y la conversación
  • Capabilities: una lista de funcionalidades configuradas para el agente, junto con su estado de ejecución y estadísticas de respuesta (si se ejecutan)
  • Acciones: una lista de acciones configuradas para el agente
    • Funciones coincidentes: estado de las funciones coinciden en la búsqueda de índice de la aplicación en tiempo de ejecución
    • Funciones seleccionadas para la ejecución: estado de las funciones seleccionadas para la invocación en función del razonamiento del orquestador

Sección de metadatos del agente

Los metadatos del agente proporcionan detalles clave sobre el agente y la sesión de depuración actual, entre los que se incluyen:

  • Resumen : una descripción general de alto nivel de las fuentes de conocimiento configuradas y sus estadísticas de uso.
  • Id. de agente : un identificador único para el agente, que incluye el id. de título y el id. de manifiesto
  • Versión del agente : número de versión del agente que está actualmente en uso
  • Id. de conversación : identificador de la conversación o sesión de chat activa
  • Id. de solicitud : identificador de la indicación específica dentro de la conversación

Captura de pantalla de la sesión de Kit de herramientas de agentes en la que Copilot ha devuelto una tarjeta con información de depuración que muestra los metadatos del agente

Funcionalidades del agente

La sección de capacidades del agente muestra las capacidades configuradas para el agente, definiendo el alcance de sus fuentes de conocimiento accesibles. Se proporcionan los siguientes detalles para cada funcionalidad utilizada por el aviso.

  • Estado de ejecución : indica si la funcionalidad se usó durante la orquestación
  • Archivo de registro de diagnóstico : archivo de .txt descargable que contiene resultados de ejecución detallados, incluidos mensajes de éxito o error, que puede ayudar con la solución de problemas y la validación

Captura de pantalla de la sesión de Kit de herramientas del agente en la que Copilot ha devuelto una tarjeta con información de depuración que muestra las capacidades configuradas del agente

Acciones de agente

La sección Acciones del agente proporciona información detallada sobre cómo se procesan las acciones del agente (funciones o complementos) durante la orquestación. Esta información se divide en tres áreas clave: metadatos de acción, coincidencia y selección de funciones y detalles de ejecución.

Captura de pantalla de la sesión de Kit de herramientas del agente en la que Copilot ha devuelto una tarjeta con información de depuración que muestra las acciones del agente configuradas

Metadatos de acción

Esta sección muestra información general sobre las acciones registradas para el agente. Esta información incluye el id . de acción (el identificador único de la acción) y el número de versión (la versión de la definición de acción en uso).

Coincidencia y selección de funciones

En esta parte se muestra cómo interpretó el orquestador la indicación del usuario y si alguna función se consideró relevante para la ejecución:

  • Funciones coincidentes : funciones que coinciden semánticamente con la indicación del usuario durante la búsqueda de índice de la aplicación en tiempo de ejecución. Si no se devolvieron funciones coincidentes para la solicitud especificada, es probable que la indicación no mencionara explícitamente el nombre de la acción.

  • Funciones seleccionadas para la ejecución : funciones elegidas para la invocación en función del razonamiento del orquestador y la relevancia para la indicación. Si no se habilitó ninguna acción, la sección acciones indica que no hay ninguna acción habilitada.

Detalles de la ejecución

Los detalles de ejecución de la acción incluyen la función y su estado, junto con la latencia, la información de solicitud (punto de conexión de solicitud, método HTTP, encabezados de solicitud) y la respuesta.

Solucionar problemas de errores

A continuación se muestran los errores comunes que puede encontrar al depurar el agente y las posibles causas de los errores.

Sin información de depuración

Después de iniciar el agente, compruebe que la conexión con el explorador está marcada como correcta en el panel de depuración. Si no es así, intente ejecutar F5 de nuevo en Visual Studio Code para iniciar una nueva sesión.

Captura de pantalla de la sesión de Agent Toolkit en la que la conexión con el explorador web es correcta

Si la conexión se realiza correctamente, pero no ve la información de depuración, es posible que se deba a que el orquestador no requiere que los datos o aptitudes de Microsoft 365 respondan. En este caso, no se devuelve ninguna tarjeta de información de depuración.

La información de depuración tampoco se devuelve en casos de limitación de capacidad, en los que normalmente se ve un mensaje de error en el que puede volver a intentarlo más tarde.

Depurar información sin ninguna función seleccionada para la ejecución

Si ninguna función de acción coincide con la intención de búsqueda del mensaje, la tarjeta de información de depuración notifica que no hay ninguna función seleccionada para la ejecución. Es probable que la causa sea que la descripción del comando en el manifiesto no esté relacionada semánticamente con la intención de búsqueda del mensaje especificado.

Si Copilot hubiera coincidido previamente y ejecutado sus funciones correctamente, es posible que se limiten las solicitudes.

Información de depuración con información vacía o con error Sin detalles de ejecución de la función

Para los complementos de API, si hay detalles de ejecución de funciones fallidos o no hay detalles, indica una falla durante el intento de su agente de asignar parámetros a la función seleccionada de su complemento. Si el error es coherente, lo más probable es que se deba a descripciones de parámetros o acciones poco claras, direcciones URL de host no válidas u otros problemas con la definición de Open API.

Para los complementos de extensión de mensajes, la mejor práctica es optimizar las respuestas en menos de nueve segundos. Para obtener más información, revisa los requisitos técnicos de los complementos de extensión de mensaje.

Actualmente, el límite de tiempo de espera para la ejecución de una API de complemento por parte de Copilot está establecido en 10 segundos.

Informar de un problema

Informe de cualquier comentario o problema con su agente mediante el botón de pulgar hacia arriba o hacia abajo. Incluye la etiqueta en tu #extensibility informe.

Captura de pantalla de las opciones de comentarios con los pulgares hacia arriba o hacia abajo de Copilot Chat