Solucionar problemas en las conversaciones de los agentes con Agent Debugger en el kit de agente de Copilot

Agent Debugger es una herramienta de diagnóstico que le permite cargar una conversación grabada y examinar cada decisión tomada por un agente. Para cada turno de conversación, puede revisar la ruta de ejecución, la duración de cada paso, el uso de tokens, las fuentes de conocimiento, los argumentos de cada paso y el razonamiento del orquestador.

Agent Debugger admite dos orígenes de datos:

• Transcripción de conversación (Dataverse): Cuando una conversación se ejecuta en Copilot Studio, la plataforma registra un registro de actividad como una Transcripción de Conversación en Dataverse. Agent Debugger consulta directamente esos registros, por lo que cualquier agente publicado con datos de transcripciones está disponible de inmediato.
• Instantánea de Copilot Studio (ZIP): El panel de pruebas de Copilot Studio incluye una opción de Descarga de instantánea que exporta la conversación de prueba actual como un archivo ZIP. Al cargar ese archivo en Agent Debugger, podrá tener acceso a la vista de análisis completa sin necesidad de una conexión a Dataverse. Este método resulta útil para depurar conversaciones de preproducción, reproducir problemas sin conexión o compartir una sesión que falla con un compañero.

Ambos orígenes de datos alimentan la misma interfaz de análisis. Los paneles, los detalles de los pasos y las visualizaciones son los mismos, independientemente de cómo se carguen los datos.

Requisitos previos

Para usar Agent Debugger, asegúrese de que se cumplen los siguientes requisitos previos:

• El agente está presente en el Inventario de agentes y tiene al menos una transcripción de conversación registrada en su contra. Para verificar esta condición, abra la vista de lista Inventario de agentes, seleccione el agente y seleccione Mostrar más para expandir los campos adicionales. El campo Está disponible para transcripción debe estar configurado en Sí. La sincronización del Inventario de agentes rellena automáticamente este campo cuando existe al menos una transcripción de conversación del agente en Dataverse.
• El usuario que ha iniciado sesión tiene el rol de seguridad CSK - Administrador o Administrador del sistema en el entorno del kit.
• El usuario que ha iniciado sesión tiene acceso de tipo Lectura en las tablas conversationtranscripts, bot y botcomponents en el entorno de destino.

Seleccionar una conversación

Al abrir Agent Debugger, la barra de filtrado le ofrece los controles necesarios para localizar una conversación que desee analizar.

Después de seleccionar un Id. de conversación, Analizar queda disponible. Selecciónelo para abrir la vista de análisis.

Cargar una instantánea desde Copilot Studio

La pestaña Cargar instantánea ofrece un punto de entrada alternativo que no requiere acceso a Dataverse. En lugar de seleccionar una conversación en directo de los menús desplegables, debe cargar un archivo ZIP con una instantánea descargado del panel de pruebas de Copilot Studio.

Para descargar una instantánea desde Copilot Studio:

1. Abra su agente principal en Copilot Studio y vaya al panel Probar el agente.
2. Ejecute o revise una conversación.
3. Seleccione Descargar instantánea en la barra de herramientas del panel de pruebas.

Copilot Studio descarga un archivo .zip que contiene:

• dialog.json: Todas las actividades del Bot Framework para la conversación (obligatorias).
• botContent.yml: Las definiciones completas de componentes y flujos del agente, utilizadas para resolver nombres de pasos (opcionales; si no existen, se muestran los nombres de los esquemas en bruto).

Para cargar una instantánea a Agent Debugger:

1. Cambie a la pestaña Cargar instantánea en el encabezado de Agent Debugger.
2. Arrastre y suelte el archivo .zip en la zona de colocación, o seleccione para buscarlo.

Agent Debugger valida el ZIP, extrae los archivos y abre la vista de análisis. No se requiere selección de entorno, agente o conversación. Todas las métricas de información general se derivan del archivo cargado.

Utilice el modo de carga de instantánea cuando necesite:

• Depurar una conversación que ocurrió en el panel de prueba antes de que se publicara el agente.
• Analizar una conversación desde un entorno en el que no pueda autenticarse.
• Reproducir los problemas fuera de línea o compartir una sesión que falla con un compañero sin conceder acceso a Dataverse.
• Validar el comportamiento de los agentes en un entorno de desarrollo local.

Analizar una conversación

La vista de análisis se abre después de seleccionar Analizar o cargar una instantánea. Contiene la fila de resumen Información general en la parte superior, una sección de análisis que se puede contraer con cuatro paneles s (Ruta de ejecución, Escala de tiempo de rendimiento, Detalles del agente y Recomendaciones), así como un diseño de dos paneles que muestra la Vista previa de conversación junto al panel Información de depuración.

Información general

La fila de información general muestra mosaicos con métricas resumidas de la conversación.

Cuando se carga un agente activo, aparece el enlace Abrir agente en el encabezado de información general. El enlace abre la página de configuración del agente en Copilot Studio.

Ruta de ejecución

La ruta de ejecución representa el orden completo de ejecución a lo largo de todos los turnos de la conversación en forma de diagrama de flujo dirigido. Los pasos se siguen de izquierda a derecha, en el orden de ejecución. Las líneas verticales discontinuas marcan los límites de los giros, y cada mensaje de usuario da inicio a una nueva sección. Las etiquetas de sección aparecen en la parte superior de cada sección. Al seleccionar una etiqueta de turno, se desplaza la Vista previa de la conversación a ese mensaje.

Cada tipo de paso utiliza un color distinto, y una leyenda situada en la parte inferior del diagrama asocia los colores a las categorías de los pasos, tales como Tema, Conocimiento, Herramienta, Conector, Flujo, Código, MCP y Agente conectado. Cada nodo muestra el nombre del paso y la duración de su ejecución. Los pasos fallidos están resaltados en rojo. Los agentes conectados aparecen como recuadros que agrupan los pasos secundarios que han ejecutado.

Escala de tiempo de rendimiento

La escala de tiempo de rendimiento muestra un gráfico en cascada con los tiempos de ejecución de los pasos, agrupados por turno de conversación. Las barras de pasos se ajustan a la duración total del turno para que se pueda apreciar los tiempos relativos. La codificación por colores se corresponde con la leyenda de la ruta de ejecución, y los pasos fallidos aparecen en rojo.

El panel cuenta con las siguientes características:

• Los botones Expandir/Contraer todo alternan todas las secciones de turnos a la vez. Cada sección de turno también se puede contraer de forma individual.
• Las estadísticas por turno muestran el recuento de pasos, el nombre y la duración del paso más lento, así como el recuento de fallos.
• En la parte superior se muestra un resumen global con el número total de pasos, el tiempo total transcurrido, el paso más lento de toda la conversación y el recuento total de errores.
• Los pasos que duran más de 10 segundos se señalan con un indicador de advertencia.

Detalles del agente

El panel de detalles del agente muestra la configuración completa del agente tal y como era en el momento en que se analizó la conversación. La información está organizada en seis pestañas.

Recomendaciones

El panel de recomendaciones detecta automáticamente los problemas en la conversación y los muestra como cartas accionables con calificaciones de gravedad.

Se detectan los siguientes tipos de problemas:

Cada tarjeta de recomendación muestra el icono y el color que indican el nivel de gravedad, una insignia de categoría, el título y la descripción del problema detectado, una sugerencia sobre cómo investigarlo o resolverlo, y un botón Ir al turo que desplaza la Vista previa de la conversación hasta el mensaje del usuario correspondiente. Cuando no se detectan problemas, el panel muestra un mensaje de estado vacío.

Vista previa de la conversación

El panel de vista previa de la conversación muestra el intercambio completo de la conversación tal y como lo vio el usuario, incluyendo los globos de diálogo del bot y del usuario, las Tarjetas adaptables representadas en línea, las fichas de acciones sugeridas y las indicaciones de comentarios.

Al seleccionar un globo de mensaje de usuario, se cargan los pasos de ese turno en el panel Información de depuración. El mensaje seleccionado aparece resaltado para que pueda saber qué turno está activo. El panel se puede desplazar de forma independiente. La selección de Ver JSON en el encabezado de la vista previa de la conversación abre el cuadro de diálogo JSON de transcripción completa.

Información de depuración

El panel de información de depuración muestra detalles paso a paso del turno de mensaje de usuario seleccionado. El panel incluye una lista de pasos a la izquierda y una vista detallada de cada paso que se abre al seleccionar uno de ellos.

La lista de pasos muestra todos los pasos del orquestador ejecutados durante el turno seleccionado, con un icono y un color que indican el tipo de paso, el nombre del paso (que, siempre que sea posible, se muestra como un nombre descriptivo), la duración de la ejecución y un indicador de éxito o fallo. Los pasos que pertenecen a un agente conectado se agrupan dentro de una tarjeta contenedor plegable que muestra el nombre del agente y el tiempo total de ejecución. El botón Cargar detalles del agente conectado en el contenedor carga la transcripción completa del agente secundario a demanda.

Se admiten los tipos de pasos siguientes:

Al seleccionar un paso, se abre un panel de detalles con las siguientes secciones, que se muestran cuando los datos figuran en la transcripción:

• Proceso de pensamiento: El texto de razonamiento del orquestador grabado antes de que se invocara el paso. Muestra cómo el modelo decidió denominar este paso y qué esperaba de él.
• Tipo de paso: Etiqueta clasificada para el paso.
• Argumentos: Una vista en árbol JSON contraíble de los parámetros de entrada pasados al paso. Incluye una opción de copia para capturar el JSON de los tickets de asistencia.
• Observación: El valor de salida o retorno del paso. También se muestra como un árbol JSON contraíble compatible con la copia.
• Vista previa del código: Para los pasos de código en Python, el código fuente se muestra con resaltado de sintaxis.
• Uso de tokens: Recuento de tokens de la solicitud, recuento de tokens de finalización y total del paso, junto con el nombre del modelo utilizado.
• Fuentes de conocimiento: Fuentes consultadas, resultados obtenidos (salida) y fuentes citadas efectivamente en la respuesta final. Cada entrada muestra el nombre de la fuente, el tipo, la URL (cuando esté disponible) y un enlace para abrir la fuente.
• Información del servidor MCP: En el caso de los pasos de MCP, muestra la versión del protocolo del servidor, las capacidades declaradas y la lista de herramientas que el servidor proporcionó durante la inicialización.
• Información de error: Cuando falla un paso, se muestran el código de error, el mensaje de error y (en el caso de los bloques de IA responsable) la categoría de seguridad de contenido que ha activado el filtro.
• Tarjetas adaptables: Cuando el paso genera una respuesta de Tarjeta adaptable, la tarjeta se muestra en línea en el panel de detalles tal y como la habría visto el usuario.

JSON de la transcripción

Al seleccionar Ver JSON en el encabezado de la vista previa de la conversación, se abre un cuadro de diálogo que muestra el registro completo sin procesar de las actividades, con resaltado de sintaxis, búsqueda de texto completo dentro del árbol JSON y una opción para copiar al portapapeles todo el contenido.

Use esta vista cuando:

• Necesita inspeccionar un tipo de evento que no aparezca en el panel Información de depuración.
• Quiere copiar campos específicos para un vale de soporte.
• Está investigando comportamientos inesperados en las vistas analizadas.

Solución de problemas

En los apartados siguientes se describen los problemas más habituales y cómo resolverlos.

El Agente no aparece en el menú desplegable Entorno ni en el menú desplegable Agente

El agente no está sincronizado con el Inventario de agentes, o no tiene ninguna transcripción de conversaciones.

Para solucionar este problema:

1. Realice una sincronización manual del inventario de agentes para el entorno.
2. Compruebe que el registro del agente exista en la tabla Detalles del agente de Dataverse.
3. Compruebe que la columna Hay transcripción disponible esté ajustada en Sí en el registro. La sincronización rellena este campo cuando existe al menos una transcripción.

Para más información, consulte Supervisar los agentes usando el Inventario de agentes en el Kit de Copilot Studio.

El Id. de conversación no aparece en el menú desplegable

Para optimizar el rendimiento, el menú desplegable solo precarga las 50 conversaciones más recientes dentro del intervalo de tiempo activo. Las transcripciones antiguas aún existen en Dataverse pero no aparecen de manera predeterminada. Por otra parte, es posible que la transcripción aún no se haya redactado si la conversación acaba de terminar.

Para solucionar este problema:

1. Escriba el Id. de conversación directamente en el campo Id. de conversación. Al escribir, se inicia una búsqueda completa en todas las transcripciones de ese agente, sin tener en cuenta el intervalo de tiempo.
2. Si el intervalo de tiempo es limitado (por ejemplo, Últimos 30 minutos), amplíelo o cambie a un intervalo personalizado que cubra la fecha de la conversación.
3. Si la conversación acaba de finalizar, espere entre 35 y 40 minutos a que la transcripción se guarde en Dataverse y, a continuación, actualice la página.

Se analizan las cargas, pero no aparece ningún paso en el panel de información de depuración

La transcripción existe, pero solo contiene actividades de tipo mensaje, sin eventos de seguimiento de diagnóstico. Este problema suele producirse cuando la conversación procede de un canal que no envía datos de seguimiento, como ciertos canales personalizados o versiones antiguas del esquema.

Para solucionar este problema:

1. Seleccione Ver JSON en el encabezado de la vista previa de la conversación para confirmar si hay actividades presentes.
2. Busque entradas type: "trace" o type: "event". Si no existen, el canal puede no emitir datos de seguimiento.

Acceso denegado o página en blanco al cargar

Faltan roles o permisos en uno o ambos entornos.

Para solucionar este problema:

1. En el entorno del kit, asegúrese de que el usuario tenga el rol de CSK - Administrador o Administrador del sistema.
2. En el entorno de destino, asegúrese de que el usuario que haya iniciado sesión disponga de acceso de lectura a las tablas conversationtranscripts, bot y botcomponents.

Las transcripciones parecen estar incompletas (faltan los primeros mensajes)

Las conversaciones largas se dividen en varios registros de Dataverse (límite de 1 MB por registro). Si la directiva de retención elimina algunos registros, el expediente fusionado presenta lagunas.

Para solucionar este problema:

1. De manera predeterminada, Dataverse elimina los historiales de conversación con más de 30 días de antigüedad. Si el problema es la retención, actualice la programación de la tarea de eliminación masiva en Power Apps>Configuración>Configuración avanzada>Administración de datos>Eliminación de registros en masa.
2. Si la retención no es la causa, compruebe que todos los registros de transcripciones de la conversación figuren en la tabla conversationtranscripts de Dataverse.

Los pasos muestran nombres de esquemas en bruto en lugar de nombres de temas legibles

La consulta botcomponents en la tabla ha fallado, o el registro del componente se ha eliminado.

Para solucionar este problema:

1. Compruebe que el usuario que ha iniciado sesión tenga acceso de lectura a la tabla botcomponents en el entorno de destino.
2. Si el componente se ha eliminado de Copilot Studio, no existe ningún registro que coincida y Agent Debugger recurre al nombre del esquema sin formato, como cr123_mytopic. Este comportamiento es el esperado en el caso de los temas o acciones eliminados.

El panel de detalles del agente no muestra datos

Se ha producido un error al recuperar la configuración del agente, o bien la conexión del usuario que ha iniciado sesión no dispone de acceso de lectura a las tablas bot y botcomponents en el entorno de destino.

Para solucionar este problema:

1. Compruebe que la referencia de conexión utilizada por la aplicación dispone de acceso de lectura a las tablas bot y botcomponents.
2. Si el agente se ha eliminado o se ha retirado de la publicación después de que se grabara la conversación, es posible que sus registros de configuración ya no existan. En este caso, el panel Detalles del agente permanece vacío, pero los paneles de transcripción y depuración siguen funcionando plenamente.

El panel de recomendaciones no muestra ningún problema, pero la conversación ha fallado

Las recomendaciones se basan en los patrones observados en los eventos de seguimiento de la transcripción. Si en la transcripción faltan datos de seguimiento, o si el fallo se produce fuera de la conversación (por ejemplo, un tiempo de espera de red silencioso que la transcripción no registra), el sistema no genera ninguna recomendación.

Para solucionar este problema:

1. Abra el archivo JSON de la transcripción para buscar los datos de error sin procesar que no se muestren como recomendación.
2. Compruebe si hay algún paso marcado en rojo en la ruta de ejecución. Estos pasos indican fallos que no se ajustan a ningún patrón de recomendación conocido.

Información relacionada

• Supervisar los agentes usando el Inventario de agentes en el Kit de Agente de Copilot
• Configurar agentes en el Kit de Agente de Copilot
• Introducción al Kit de Agente de Copilot