Referencia de CLI de evaluaciones de agentes

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.

Opciones

`-V, --version`

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

Ejemplo:

runevals --version

Resultado:

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

`--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:

.env.local (detectado automáticamente para proyectos de Agents Toolkit)
.env.local.user (secretos, cargados automáticamente si hay)
env/.env.<environment> (especificado por --env)
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	`https://<account>.services.ai.azure.com/api/projects/<project>`

Variables opcionales

Variable	Descripción	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`

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 .

Comentarios

¿Le ha resultado útil esta página?

Se actualizó por última vez el 2026-08-13

Referencia de CLI de evaluaciones de agentes

Sinopsis

Descripción

Opciones

-V, --version

--log-level [level]

--prompts <prompts...>

--expected <responses...>

--prompts-file <file>

-o, --output <file>

-i, --interactive

--m365-agent-id <id>

--env <environment>

--init-only

-h, --help

Comandos de caché

cache-info

cache-clear

cache-dir

Variables de entorno

Variables requeridas

Variables opcionales

Ejemplos

Uso básico

Especificar el entorno

Archivo de conjunto de datos personalizado

Pruebas en línea

Modo interactivo

Formato de salida personalizado

Modo de depuración

Solo instalación

Invalidar id. de agente

Opciones combinadas

Códigos de salida

Solución de problemas

Contenido relacionado

Comentarios

Recursos adicionales

`-V, --version`

`--log-level [level]`

`--prompts <prompts...>`

`--expected <responses...>`

`--prompts-file <file>`

`-o, --output <file>`

`-i, --interactive`

`--m365-agent-id <id>`

`--env <environment>`

`--init-only`

`-h, --help`

`cache-info`

`cache-clear`

`cache-dir`