Evaluaciones de Microsoft 365 Copilot Referencia de CLI

Este artículo proporciona una referencia completa de la línea de comandos para el runevals comando, que forma parte del @microsoft/m365-copilot-eval paquete.

Sinopsis

runevals [options]
runevals cache-info
runevals cache-clear
runevals cache-dir

Descripción

El runevals comando evalúa los agentes de Microsoft 365 Copilot mediante el envío de indicaciones de prueba y la puntuación de las respuestas mediante la evaluación en la nube y las métricas integradas de Microsoft Foundry. La herramienta admite la evaluación por lotes a partir de archivos JSON, mensajes en línea y pruebas interactivas.

CLI v1 usa la etiqueta npm latest . CLI v2 usa preview y también evalúa respuestas de Copilot que usan complementos. En v2, una ejecución sin un identificador de agente configurado evalúa el chat de Microsoft 365 Copilot. Para obtener ejemplos de configuración de vista previa y esquema v2, consulte Evaluadores de llamada a herramientas.

Opciones

-V, --version

Salida del número de versión de la herramienta CLI.

Ejemplo:

runevals --version

Salida:

1.15.0

--log-level [level]

Establezca el nivel de detalle del registro. Niveles disponibles: debug, info, warning, error.

  • Valor predeterminado: Cuando usa la marca sin un valor, el valor predeterminado es info.
  • debug: información detallada de depuración, incluidas las cargas de API.
  • información: Información general sobre el progreso de la evaluación.
  • advertencia: Solo mensajes de advertencia.
  • error: Solo mensajes de error.

Ejemplos:

# Info level (default when flag is present)
runevals --log-level

# Debug level
runevals --log-level debug

# Error level only
runevals --log-level error

Advertencia

El debug nivel puede incluir cargas de API sin procesar y datos de respuesta en la salida de la consola. La redacción se basa en patrones y es posible que no detecte toda la información de identificación personal o credenciales. No comparta públicamente el resultado de la depuración sin una revisión manual.

--prompts <prompts...>

Especifique una o varias solicitudes directamente en la línea de comandos para realizar pruebas rápidas sin crear un archivo.

Ejemplos:

# Single prompt
runevals --prompts "What is Microsoft 365?"

# Multiple prompts
runevals --prompts "What is Teams?" "What is SharePoint?" "What is OneDrive?"

--expected <responses...>

Proporcione las respuestas esperadas para acompañar los mensajes especificados con --prompts. El número de respuestas debe coincidir con el número de consultas.

Ejemplo:

runevals --prompts "What is Microsoft Graph?" \
  --expected "Microsoft Graph is the API gateway to Microsoft 365 data and intelligence."

Varias consultas y respuestas:

runevals --prompts "What is Teams?" "What is SharePoint?" \
  --expected "Teams is a collaboration platform" "SharePoint is a content management system"

--prompts-file <file>

Especifique un archivo JSON personalizado que contenga indicaciones de prueba. Este archivo invalida la detección automática.

Ejemplo:

runevals --prompts-file ./tests/my-custom-tests.json

Formato del archivo:

[
  {
    "prompt": "Test question",
    "expected_response": "Expected answer"
  }
]

Para obtener el esquema completo del conjunto de datos, consulte Esquema de conjunto de datos y diseño de prueba.

-o, --output <file>

Especifique la ruta y el formato del archivo de salida. El formato viene determinado por la extensión del archivo.

Formatos admitidos:

  • .html - Informe HTML (predeterminado, se abre automáticamente en el navegador)
  • .json - Resultados JSON
  • .csv - Hoja de cálculo CSV

Ejemplos:

# HTML output
runevals --output ./reports/results.html

# JSON output
runevals --output ./results/eval-results.json

# CSV output
runevals --output ./data/scores.csv

Comportamiento predeterminado:

Sin --output, el comando guarda los resultados en ./.evals/YYYY-MM-DD_HH-MM-SS.html.

-i, --interactive

Ingrese al modo interactivo para la entrada y prueba manual de indicaciones.

Ejemplo:

runevals --interactive

En el modo interactivo, se le pedirá que escriba las indicaciones de una en una, para que pueda realizar pruebas exploratorias.

--m365-agent-id <id>

Invalide el identificador de agente para evaluar un agente específico. Este parámetro es útil cuando se prueban varios agentes o cuando el ID del agente no se puede detectar automáticamente.

Ejemplo:

runevals --m365-agent-id "U_0dc4a8a2-b95f-edac-91c8-d802023ec2d4"

Formatos de identificación de agente:

  • Ámbito de usuario: U_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  • Ámbito del espacio empresarial: T_agent-name.declarativeAgent

Para escenarios de complemento de versión preliminar v2, omita esta opción y elimine M365_AGENT_ID un heredado AGENT_ID de su shell y archivos de entorno cargados.

--list-tools <agent-id> (V2 versión preliminar)

Enumerar identificadores de consentimiento e identidades de evaluador listas para copiar para las acciones de un agente declarativo. Esta opción no es compatible con complementos independientes. Es posible que las herramientas descubiertas dinámicamente no aparezcan; confirmar sus identidades después diagnostics.tool_calls de una evaluación.

npx -y --package @microsoft/m365-copilot-eval@preview runevals --list-tools "<your-agent-id>"

Para obtener nombres de consentimiento de complementos independientes y la identidad del evaluador de tres partes, consulte Buscar nombres de llamada a herramientas.

--evaluate-only <file>

Vuelva a puntuar las respuestas guardadas y los diagnósticos disponibles sin ejecutar avisos. Cada artículo o turno debe incluir un response. Configure un juez si selecciona evaluadores basados en LLM; La autenticación de ejecución de Microsoft 365 no es necesaria.

runevals --evaluate-only results\captured-responses.json --output results\rescored.html

La nueva puntuación de la llamada a herramientas requiere la vista previa de CLI v2 y evidencia de llamada de herramienta retenida. Para obtener más información, consulte Diagnósticos y evaluación de respuesta guardada.

--env <environment>

Especifique la configuración del entorno que se va a cargar. Este parámetro carga archivos env/.env.<environment>

Predeterminado: dev (cargas env/.env.dev)

Ejemplos:

# Load env/.env.dev (default)
runevals --env dev

# Load env/.env.prod
runevals --env prod

# Load env/.env.staging
runevals --env staging

Prioridad del archivo de entorno:

  1. .env.local (detectado automáticamente para proyectos de Agents Toolkit)
  2. .env.local.user (secretos, cargados automáticamente si hay)
  3. env/.env.<environment> (especificado por --env)
  4. Variables de entorno del sistema

--init-only

Inicializa el entorno de Python y descarga dependencias sin ejecutar evaluaciones. Esta opción es útil para:

  • Precalentamiento de la caché en canalizaciones de CI/CD
  • Solución de problemas de instalación
  • Comprobar la configuración antes de ejecutar pruebas

Ejemplo:

runevals --init-only

Para solucionar problemas, combine esta opción con --log-level debug:

runevals --init-only --log-level debug

-h, --help

Muestra información de ayuda sobre los comandos y opciones disponibles.

Ejemplo:

runevals --help

Comandos de caché

La herramienta de evaluación usa una caché local para el tiempo de ejecución y las dependencias de Python. Estos comandos le ayudan a administrar la memoria caché.

cache-info

Muestra estadísticas sobre el entorno de Python almacenado en caché, incluido el tamaño, la ubicación y los paquetes instalados.

Ejemplo:

runevals cache-info

Salida:

Cache Information

Location: C:\Users\YourName\.m365-copilot-eval\cache
Size: 245 MB
Python Version: 3.11.5
Packages: 42 installed

Last updated: 2026-04-10 14:23:15

cache-clear

Quita el entorno de Python almacenado en caché y todas las dependencias descargadas. Use este comando cuando solucione problemas de instalación o libere espacio en disco.

Ejemplo:

runevals cache-clear

Seguimiento:

Después de borrar la memoria caché, reinicialice:

runevals --init-only

cache-dir

Imprime la ruta de acceso absoluta al directorio de la memoria caché. Esta característica es útil para scripts o inspección manual.

Ejemplo:

runevals cache-dir

Salida:

C:\Users\YourName\.m365-copilot-eval\cache

Uso en scripts:

# Check cache directory permissions (Unix/macOS)
chmod -R u+w $(runevals cache-dir)

# View cache contents
ls -lah $(runevals cache-dir)

Variables de entorno

La herramienta lee la configuración de los archivos de entorno y las variables del sistema. Para obtener instrucciones paso a paso sobre cómo obtener estos valores, consulte Variables de entorno necesarias.

Variables requeridas

Variable Descripción Ejemplo
TENANT_ID Id. de inquilino de Microsoft Entra xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
AZURE_AI_PROJECT_ENDPOINT Punto de conexión del proyecto de Microsoft Foundry para la puntuación basada en LLM. No es necesario para la evaluación solo determinista. https://<account>.services.ai.azure.com/api/projects/<project>

Variables opcionales

Variable Descripción Valor predeterminado
M365_AGENT_ID Id. de agente para valorar Detectado automáticamente desde M365_TITLE_ID
M365_TITLE_ID Id. de título del agente (Kit de herramientas de agentes) Ninguno
AZURE_AI_MODEL_NAME Modelo para evaluaciones gpt-5-mini
EVALS_SUPPRESS_DIAGNOSTICS Establézcalo en true omitir diagnósticos retenidos. No redacta indicaciones, respuestas, opciones de evaluador ni mensajes de validación nativos. Las pruebas suprimidas no se pueden reproducir. Sin establecer

Ejemplos

Uso básico

Evalúe mediante el archivo de conjunto de datos detectado automáticamente:

cd /path/to/your-agent-project
runevals

Especificar el entorno

Usar configuración del entorno de producción:

runevals --env prod

Archivo de conjunto de datos personalizado

Utilice un archivo de prueba específico:

runevals --prompts-file ./tests/regression-tests.json

Pruebas en línea

Prueba rápida con indicaciones insertadas:

runevals --prompts "What is Microsoft 365?" \
  --expected "Microsoft 365 is a cloud-based productivity suite"

Modo interactivo

Escriba las indicaciones manualmente:

runevals --interactive

Formato de salida personalizado

Generar resultados JSON:

runevals --output ./results/eval-$(date +%Y%m%d).json

Modo de depuración

Ejecutar con registro detallado:

runevals --log-level debug --output ./debug-results.json

Solo instalación

Entorno de Python de caché previo sin ejecutar pruebas:

runevals --init-only --log-level info

Invalidar id. de agente

Pruebe un agente específico:

runevals --m365-agent-id "U_0dc4a8a2-b95f-edac-91c8-d802023ec2d4"

Opciones combinadas

Evaluación completa con configuraciones personalizadas:

runevals \
  --env staging \
  --prompts-file ./evals/full-suite.json \
  --output ./reports/staging-eval-$(date +%Y%m%d).html \
  --log-level info \
  --m365-agent-id "T_my-agent.declarativeAgent"

Códigos de salida

Código Significado
0 Correcto
1 Error general
2 Argumentos no válidos
3 Error de configuración del entorno
4 Agente no encontrado
5 Error de autenticación
10 Error de configuración del entorno de Python

Solución de problemas

Para conocer los problemas comunes de instalación, autenticación, errores en tiempo de ejecución, problemas de caché y configuración de proxy, consulte el artículo Solución de problemas .