Inicio rápido: Uso de la CLI de evaluaciones de agentes

La CLI de evaluaciones de agentes de Microsoft 365 Copilot (@microsoft/m365-copilot-eval) le ayuda a probar, medir y mejorar la calidad de sus agentes a través de la evaluación rápida automatizada y la puntuación basada en IA. Este inicio rápido le guía a través de la instalación de la herramienta Evaluaciones de agentes, la configuración del entorno, la creación del primer conjunto de datos y la ejecución de una evaluación.

Importante

Para los agentes declarativos implementados, comience con Work IQ Dev Tools (versión preliminar) para obtener un flujo de trabajo guiado. Work IQ Dev Tools administra la versión de la CLI de evaluaciones de agentes compatible, por lo que no es necesario realizar la instalación @microsoft/m365-copilot-eval global. Siga este inicio rápido cuando necesite control de comandos de nivel inferior o mantenga un flujo de trabajo existente runevals .

Requisitos previos

Antes de comenzar, asegúrate de que tienes:

• Un agente de Microsoft 365 Copilot implementado en el inquilino.
• Node.js 24.12.0 o posterior (use node --version para comprobarlo).
• Créditos de Copilot disponibles en su espacio empresarial. La CLI de evaluaciones de agentes consume créditos de Copilot cuando envía indicaciones de prueba al agente. El administrador de inquilinos activa la facturación basada en el uso (de uso medido) en el Centro de administración de Microsoft 365 yendo al nodoAdministración de costos de Copilot>. Para obtener más información, consulte Administrar créditos de Copilot.
• Un proyecto de Microsoft Foundry con un modelo GPT-5 implementado para puntuar las respuestas. Para obtener más información, consulte Obtener valores para las variables de entorno.
• Consentimiento de administrador de Microsoft Entra concedido para Work IQ en el inquilino. Si no es un administrador de espacio empresarial, pida a su administrador que conceda consentimiento antes de ejecutar runevals por primera vez. Para obtener más información, consulte Conceder consentimiento del administrador.
• Su id. de inquilino y el punto de conexión del proyecto de Microsoft Foundry. Si no tiene estos valores, consulte Obtener valores para las variables de entorno.

Nota:

En este inicio rápido se supone que está usando un entorno de desarrollo de Windows. La autenticación es compatible con otros sistemas operativos próximamente.

Paso 1: Instalación de la CLI

Instalar la CLI de evaluaciones de agente globalmente mediante npm:

npm install -g @microsoft/m365-copilot-eval

Compruebe la instalación:

runevals --version

Después de la instalación, el comando está disponible globalmente en el runevals sistema.

Paso 2: Configurar la estructura del proyecto

Ejecute la herramienta de evaluación desde el directorio del proyecto del agente de Microsoft 365 (donde reside el código del agente), no desde el repositorio de la herramienta de evaluaciones.

cd /path/to/your-agent-project

El proyecto de agente debe incluir los siguientes archivos y carpetas:

my-agent/
├── .env.local              # Agent configuration (Agents Toolkit projects)
├── .env.local.user         # Secrets — never committed
├── evals/
│   └── evals.json          # Your test dataset (auto-discovered)
└── .evals/
    └── <generated reports> # Results written here (YYYY-MM-DD_HH-MM-SS.html)

Cree el conjunto de datos en el evals/evals.json Paso 4. La .evals/ carpeta del informe se crea automáticamente en la primera ejecución.

Paso 3: Configurar variables de entorno

Elija la opción que coincida con su tipo de proyecto.

Sugerencia

Si ha creado su agente mediante el Kit de herramientas de agentes de Microsoft 365, ya lo ha hecho .env.local con la configuración del agente. Cree .env.local.user secretos en la raíz del proyecto.

Proyectos del Kit de herramientas de agentes de Microsoft 365

No se establece M365_AGENT_ID directamente: la CLI lo detecta automáticamente desde M365_TITLE_ID en ..env.local Para obtener más información, consulte Obtener la identificación de agente.

Añadir secretos a .env.local.user:

# .env.local.user (NOT checked in — secrets go here)
TENANT_ID="your-tenant-id-here"
AZURE_AI_PROJECT_ENDPOINT="https://<account>.services.ai.azure.com/api/projects/<project>"
AZURE_AI_MODEL_NAME="gpt-5-mini" # default

La CLI de evaluaciones de agentes puntúa las respuestas mediante la evaluación en la nube de Microsoft Foundry, que se autentica con Microsoft Entra. Inicie sesión con la CLI de Azure (az login) antes de ejecutar runevals. Para obtener más información sobre estos valores, consulte Obtener valores para las variables de entorno.

Añadir .env.local.user a su .gitignore:

# User-specific secrets — never commit
.env.local.user
env/.env.local.user

Paso 4: Crear el primer conjunto de datos

Cree evals/evals.json con un pequeño conjunto de indicaciones y respuestas esperadas. En este ejemplo se usa el esquema válido más sencillo para las evaluaciones de un solo turno.

{
  "schemaVersion": "1.0.0",
  "items": [
    {
      "prompt": "What is Microsoft 365?",
      "expected_response": "Microsoft 365 is a cloud-based productivity suite that includes Office apps, cloud services, and device management."
    },
    {
      "prompt": "How do I share a file in Microsoft Teams?",
      "expected_response": "To share a file in Teams, you can upload it to a channel or chat, or share it from OneDrive with specific permissions."
    }
  ]
}

Sugerencia

Si omite este paso, la herramienta ofrece generar un archivo de inicio con mensajes de ejemplo la primera vez que ejecute runevals.

Para conocer el esquema completo del conjunto de datos, las categorías y los patrones avanzados, consulte Creación de conjuntos de pruebas de evaluación.

Paso 5: Realice la primera evaluación

Para proyectos de Agents Toolkit (usa .env.local y .env.local.user):

runevals

Para proyectos de kit de herramientas para no agentes:

runevals --env dev

Paso 6: Confirmar la instalación correcta

Una ejecución correcta produce:

• Un mensaje de finalización en el terminal similar al mensaje siguiente.

  M365 Copilot Agent Evaluations CLI
  
  Loading environment: dev
  Agent ID: T_my-agent.declarativeAgent
  Using prompts file: ./evals/evals.json
  
  Running evaluations...
  
  Evals completed successfully!
  Results saved to: ./.evals/2026-04-22_14-30-45.html
  

• Un informe HTML guardado que se ./.evals/YYYY-MM-DD_HH-MM-SS.html abre automáticamente en tu navegador.

El informe incluye puntuaciones para cada consulta.

Evaluador	Tipo	Escalar	Umbral predeterminado	Predeterminado
Relevancia	Basado en LLM	1-5	3	Sí
Coherencia	Basado en LLM	1-5	3	Sí
Conexión a tierra	Basado en LLM	1-5	3	No
Similitud	Basado en LLM	1-5	3	No
Citas	Basado en recuentos	>= 0	1	No
Coincidencia exacta	Coincidencia de cadena	booleano	N/D	No
Coincidencia parcial	Coincidencia de cadena	0.0-1.0	0.5	No

Si no ve estos resultados, consulte Solución de problemas.

Contenido relacionado

• Información general de la CLI de evaluaciones de agentes
• Esquema de conjunto de datos y diseño de pruebas
• Referencia de CLI
• Solución de problemas y soporte técnico