Evaluador de agentes de M365

Utiliza esta habilidad para ayudar a los usuarios a evaluar los agentes declarativos de Microsoft 365 Copilot con @microsoft/m365-copilot-eval. La habilidad diseña conjuntos de datos de evaluación compatibles con el esquema, ejecuta la CLI de la versión preliminar pública, analiza los resultados y recomienda soluciones específicas.

Por defecto, se utiliza el kit de herramientas de agentes de Microsoft 365 (ATK) cuando se detecta, pero no se detiene de forma forzada únicamente porque el directorio actual no sea ATK. La CLI también puede evaluar agentes desplegados con un M365_AGENT_ID explícito o mediante --m365-agent-id.

Utiliza siempre esta invocación de la CLI

npx -y --package @microsoft/m365-copilot-eval@latest runevals

No se recomienda el antiguo instalador privado aka.ms, las instalaciones globales, el comando «runevals» sin parámetros, «npx runevals» sin parámetros, «--input» ni «--html».

Flujo de trabajo de activación

1. Identifica el objetivo del usuario: configuración, creación de conjuntos de datos, ejecución de evaluaciones, análisis de resultados o actualización de un conjunto de evaluaciones existente.
2. Carga solo la referencia necesaria para el objetivo actual:
   • references/workflow.md para el flujo de trabajo completo del operador y los comandos de la CLI.
   • references/azure-setup.md para los requisitos previos, los archivos de entorno y la gestión de secretos.
   • references/eval-templates.md al crear o editar conjuntos de datos de evaluación.
   • references/pra-framework.md a la hora de decidir qué escenarios generar.
   • references/result-analysis.md una vez que existan resultados en formato JSON, CSV o HTML.
   • references/guardrails.md antes de escribir archivos, gestionar secretos, borrar la caché, cerrar sesión o solucionar problemas.
3. Detectar la estructura del proyecto:
   • ATK: .env.local, .env.local.user, env\.env.local.user, m365agents.yml o appPackage\declarativeAgent.json.
   • No ATK: un conjunto de datos de evaluación más M365_AGENT_ID, --m365-agent-id o un archivo de entorno con nombre, como env\.env.dev.
4. Verificar los requisitos previos sin revelar valores:
   • Node.js 24.12.0 o posterior.
   • Licencia de Microsoft 365 Copilot y un agente de M365 Copilot implementado.
   • Consentimiento del administrador del inquilino para la aplicación WorkIQ Client.
   • TENANT_ID, el punto de conexión y la clave de Azure OpenAI en Foundry Models, y la implementación recomendada o predeterminada de gpt-4o-mini.
5. Elige el flujo de trabajo:
   • Sin conjunto de datos: crea evals\evals.json.
   • Conjunto de datos existente: ejecutar, analizar resultados anteriores o proponer cambios.
   • Comprobación rápida: utiliza indicaciones en línea.
   • Exploración: utiliza el modo interactivo.

Contrato del conjunto de datos actual

Genera documentos del esquema versión 1.2.0 con una matriz de elementos raíz. No generes el antiguo formato PromptsObject ni el de indicaciones raíz.

Estructura mínima:

{
  "schemaVersion": "1.2.0",
  "metadata": {
    "name": "Conjunto de evaluación de agentes",
    "tags": ["starter"]
  },
  "default_evaluators": {
    "Relevance": {},
    "Coherence": {}
  },
  "items": [
    {
      "prompt": "¿En qué me puede ayudar este agente?",
      "expected_response": "El agente explica el alcance de sus funciones sin inventar capacidades que no ofrece."
    }
  ]
}

Utiliza references\prompts-schema.json como fuente del esquema local y references\eval-templates.md para obtener ejemplos copiables de interacciones de un solo turno, de varios turnos, de evaluadores y de umbrales.

Nombres públicos de evaluadores

Los nombres de los evaluadores distinguen entre mayúsculas y minúsculas. Utiliza únicamente los nombres de evaluadores configurables públicos, a menos que una fuente fidedigna más reciente demuestre lo contrario.

Tratar ToolCallAccuracy como heredado/privado para la creación de contenido. No añadirlo a los conjuntos de datos generados a menos que la documentación pública actual de la CLI o del esquema lo reintroduzca explícitamente.

Comandos comunes

# Comprobaciones de versión/ayuda
npx -y --package @microsoft/m365-copilot-eval@latest runevals --version
npx -y --package @microsoft/m365-copilot-eval@latest runevals --help

# Configuración inicial / EULA
npx -y --package @microsoft/m365-copilot-eval@latest runevals accept-eula
npx -y --package @microsoft/m365-copilot-eval@latest runevals --init-only

# Ejecución por lotes con salida JSON explícita
npx -y --package @microsoft/m365-copilot-eval@latest runevals --prompts-file evals\evals.json --output .evals\results.json

# HTML para revisión humana o CSV compatible con hojas de cálculo
npx -y --package @microsoft/m365-copilot-eval@latest runevals --prompts-file evals\evals.json --output .evals\results.html
npx -y --package @microsoft/m365-copilot-eval@latest runevals --prompts-file evals\evals.json --output .evals\results.csv

# Comprobaciones rápidas
npx -y --package @microsoft/m365-copilot-eval@latest runevals --prompts «¿En qué me puedes ayudar?» --expected «El agente describe el ámbito en el que presta apoyo.»

# Entorno que no sea ATK o con nombre
npx -y --package @microsoft/m365-copilot-eval@latest runevals --prompts-file evals\evals.json --m365-agent-id  --env dev

Utiliza --concurrency solo con valores entre 1 y 5. Empieza con 1 para la depuración y aumenta el valor solo cuando la configuración sea estable.

Seguridad de la versión y de la ruta PATH

Antes de diagnosticar el comportamiento del agente, comprueba qué ejecutable se está ejecutando:

Get-Command runevals -All
npm list -g @microsoft/m365-copilot-eval --depth=0
npm view @microsoft/m365-copilot-eval version
npx -y --package @microsoft/m365-copilot-eval@latest runevals --version
npx -y --package @microsoft/m365-copilot-eval@latest donde runevals

Si al ejecutar «runevals» sin más parámetros aparece el mensaje «Esta versión de la CLI de M365 Evals ha dejado de funcionar y debe actualizarse», considéralo una instalación obsoleta en la ruta de acceso global (PATH) o global. Vuelve a ejecutarlo con el comando npx --package ...@latest anterior y, a continuación, confirma antes de eliminar los shims globales con npm uninstall -g @microsoft/m365-copilot-eval.

Convenciones de archivos

Nunca se deben mostrar ni enviar a control de versiones secretos, mensajes de solicitud que contengan datos confidenciales, contenido recuperado, registros de depuración ni archivos de resultados sin procesar, a menos que el usuario lo solicite explícitamente y confirme que los datos pueden compartirse de forma segura.

Orientaciones para la generación

Utilizar PRA como marco de diseño de escenarios:

• Percepción: recuperación, fundamentación y cobertura de fuentes.
• Razonar: cumplimiento de instrucciones, síntesis, gestión de ambigüedades y comportamiento ante el rechazo.
• Actuación: capacidad declarada/comportamiento de acción. Puntúa con evaluadores públicos como Relevance, Coherence, Similarity, ExactMatch o PartialMatch; no utilices el antiguo ToolCallAccuracy.

Pregunta antes de sobrescribir un conjunto de datos existente. Al escribir las evaluaciones generadas, guárdalas primero en un archivo temporal y cámbiale el nombre si la operación se realiza con éxito.

Orientaciones para el análisis de resultados

Analiza únicamente las claves de los evaluadores que estén presentes. La ausencia de claves de puntuación suele significar que el evaluador no estaba configurado para ese elemento, no que haya fallado.

Utilice las claves de puntuación actuales cuando estén presentes: relevancia, coherencia, fundamentación, similitud, citas, coincidencia exacta y coincidencia parcial. Agrupe los fallos según sus posibles causas principales: problema con las instrucciones, problema de fundamentación, problema con las citas, discrepancia con la respuesta esperada, falta de capacidad, problema de autenticación o entorno, o problema de calidad de la evaluación.

No ejecute evaluaciones reales dependientes del inquilino a menos que el usuario haya proporcionado o aprobado la configuración necesaria del inquilino, el agente y Azure OpenAI.