Guida introduttiva: Usare l'interfaccia della riga di comando delle valutazioni di Microsoft 365 Copilot

L'interfaccia della riga di comando di Microsoft 365 Copilot Evaluations (@microsoft/m365-copilot-eval) consente di testare, misurare e migliorare la qualità degli agenti tramite la valutazione automatica delle richieste e il punteggio basato sull'intelligenza artificiale. Questa guida introduttiva illustra l'installazione dell'interfaccia della riga di comando, la configurazione dell'ambiente, la creazione del primo set di dati e l'esecuzione di una valutazione.

Nota

Questa guida introduttiva usa l'interfaccia della riga di comando v1 (latest) per valutare un agente distribuito. Per l'anteprima dell'interfaccia della riga di comando v2, gli scenari di plug-in e i nuovi analizzatori ToolCallSelection e ToolCallExecution, vedere Analizzatori di chiamate di strumenti.

Importante

Per gli agenti dichiarativi distribuiti, iniziare con Work IQ Dev Tools per un flusso di lavoro guidato. Work IQ Dev Tools gestisce la versione compatibile dell'interfaccia della riga di comando di Microsoft 365 Copilot Evaluations, quindi non devi installarla @microsoft/m365-copilot-eval a livello globale. Segui questa guida introduttiva quando hai bisogno del controllo dei comandi di livello inferiore o della gestione di un flusso di lavoro esistente runevals .

Prerequisiti

Prima di iniziare, assicurarsi di avere:

  • Un agente di Microsoft 365 Copilot distribuito nel tenant.
  • Node.js 24.12.0 o versione successiva (usare node --version per verificare).
  • Crediti Copilot disponibili nel tenant. L'interfaccia della riga di comando di Microsoft 365 Copilot Evaluations consuma crediti Copilot quando invia richieste di test all'agente. L'amministratore del tenant attiva la fatturazione basata sull'utilizzo (a consumo) nell'interfaccia di amministrazione di Microsoft 365 accedendo al nodoGestione costiCopilot>. Per altre informazioni, consulta Gestire i crediti Copilot.
  • Progetto di Microsoft Foundry con un modello GPT-5 distribuito per assegnare un punteggio alle risposte. Per altre informazioni, vedere Recuperare valori per le variabili di ambiente.
  • Consenso amministratore Microsoft Entra concesso per Work IQ nel tenant. Se non si è un amministratore tenant, chiedere all'amministratore di concedere il consenso prima di eseguire runevals la prima esecuzione. Per altre informazioni, vedere Concedere il consenso dell'amministratore.
  • L'ID tenant e l'endpoint del progetto Microsoft Foundry. Se non sono presenti questi valori, vedere Ottenere valori per le variabili di ambiente.

Nota

Questa guida introduttiva presuppone l'uso di un ambiente di sviluppo Windows. Il supporto per l'autenticazione per altri sistemi operativi sarà disponibile a breve.

Passaggio 1: Installare l'interfaccia della riga di comando

Installa l'interfaccia della riga di comando v1 di Microsoft 365 Copilot Evaluations v1 globalmente usando npm:

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

Verifica l'installazione:

runevals --version

Dopo l'installazione, il runevals comando è disponibile a livello globale sul sistema.

Passaggio 2: Configurare la struttura del progetto

Eseguire lo strumento di valutazione dalla directory del progetto agente di Microsoft 365 (in cui si trova il codice agente), non dal repository dello strumento di valutazione.

cd /path/to/your-agent-project

Il progetto agente deve includere i file e le cartelle seguenti:

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)

Il set di dati viene creato evals/evals.json nel passaggio 4. La cartella dei .evals/ report viene creata automaticamente alla prima esecuzione.

Passaggio 3: configurare le variabili di ambiente

Scegliere l'opzione corrispondente al tipo di progetto.

Suggerimento

Se l'agente è stato creato utilizzando Microsoft 365 Agents Toolkit, la configurazione dell'agente è già disponibile .env.local . Creare .env.local.user una ricerca segreta nel progetto.

Progetti del Toolkit agenti di Microsoft 365

Non si imposta M365_AGENT_ID direttamente: la CLI lo rileva automaticamente da M365_TITLE_ID in .env.local. Per informazioni dettagliate, vedi Ottenere l'ID agente.

Aggiungi segreti 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

L'interfaccia della riga di comando delle valutazioni di Microsoft 365 Copilot assegna punteggi alle risposte usando la valutazione cloud di Microsoft Foundry, che esegue l'autenticazione con Microsoft Entra. Accedere con l'interfaccia della riga di comando di Azure (az login) prima di eseguire runevals. Per informazioni dettagliate su questi valori, vedere Ottenere valori per le variabili di ambiente.

Aggiungi .env.local.user al tuo .gitignore:

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

Passaggio 4: Creare il primo set di dati

Crea evals/evals.json con un piccolo set di prompt e risposte previste. In questo esempio viene utilizzato lo schema valido più semplice per le valutazioni a turno singolo.

{
  "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."
    }
  ]
}

Suggerimento

Se salti questo passaggio, lo strumento offre la possibilità di generare un file iniziale con richieste di esempio la prima volta che esegui runevals.

Per lo schema completo del set di dati, le categorie e i modelli avanzati, vedere Creare suite di test di valutazione.

Passaggio 5: Eseguire la prima valutazione

Per i progetti Agents Toolkit (utilizza .env.local.env.local.usere e automaticamente):

runevals

Per i progetti che non fanno parte del Toolkit agenti:

runevals --env dev

Passaggio 6: conferma la riuscita della configurazione

Una corsa di successo produce:

  • Messaggio di completamento nel terminale simile al seguente.

    Microsoft 365 Copilot 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 report HTML salvato in ./.evals/YYYY-MM-DD_HH-MM-SS.html che si apre automaticamente nel tuo browser.

Il report include punteggi per ogni prompt.

Valutatore Type Scale Soglia predefinita Predefinito
Rilevanza Basato su LLM 1-5 3 Sì
Coerenza Basato su LLM 1-5 3 Sì
Radicamento Basato su LLM 1-5 3 No
Somiglianza Basato su LLM 1-5 3 No
Citazioni In base al conteggio >= 0 1 No
ExactMatch Corrispondenza stringa Valore booleano N/D No
PartialMatch Corrispondenza stringa 0.0-1.0 0,5 No

Se non vengono visualizzati questi risultati, vedere Risoluzione dei problemi.