Analizzatori di chiamate di strumenti per l'interfaccia della riga di comando delle valutazioni di Microsoft 365 Copilot

Gli analizzatori delle chiamate agli strumenti esaminano la diagnostica di runtime (informazioni per gli sviluppatori) per verificare i risultati della selezione degli strumenti e dell'esecuzione HTTP. Sono deterministici, non usano un giudice LLM e non giudicano il testo di risposta o richiedono expected_response.

Nota

Gli analizzatori delle chiamate agli strumenti richiedono Microsoft 365 Copilot Evaluations CLI v2 (preview) e schema v2. Non sono disponibili nell'interfaccia della riga di comando v1 (latest).

Valutatore Assegni Scale Soglia Abilitato per impostazione predefinita
ToolCallSelection Se sono state selezionate le identità dello strumento previste Esito positivo/negativo/errore 1.0, fisso No
ToolCallExecution Se ogni chiamata prevista ha un'esecuzione HTTP corretta distinta Esito positivo/negativo/errore 1.0, fisso No

Per l'impostazione generale del set di dati, vedere Configurare gli analizzatori.

Configurare l'interfaccia della riga di comando di anteprima

Seguire i prerequisiti di accesso del tenant e di runtime nella guida introduttiva. La configurazione del punteggio di Microsoft Foundry non è necessaria se esegui solo analizzatori deterministici.

Installare la versione di anteprima e accettare le condizioni di licenza:

npm install -g @microsoft/m365-copilot-eval@preview
runevals accept-eula

Impostato TENANT_ID per il tenant di Microsoft 365 nell'ambiente di valutazione. Per un agente dichiarativo distribuito, passare --m365-agent-id "<your-agent-id>" durante l'esecuzione di un set di dati.

Per le valutazioni di plug-in autonomi, effettuare prima il provisioning e abilitarlo in Microsoft 365 Copilot e completare qualsiasi accesso al connettore richiesto in Copilot. Senza ID agente configurato, l'anteprima v2 valuta la chat di Copilot. Mantieni M365_AGENT_ID e legacy AGENT_ID fuori dalla shell e dai file di ambiente caricati per queste esecuzioni. Vengono valutate le risposte di Copilot che usano un plug-in disponibile, non l'endpoint del plug-in in isolamento.

L'installazione di uno dei tag di rilascio npm sostituisce il comando globale runevals . Per tornare alla versione 1, reinstallare @microsoft/m365-copilot-eval@latest.

Consente le chiamate agli strumenti

Quando uno strumento richiede la conferma, configurare le aspettative di approvazione e dell'analizzatore. default_allowed_tools a livello di documento e per prompt o turno, lasciare che la CLI approvi allowed_tools le richieste di conferma dello strumento. Ogni identificatore di consenso richiesto deve essere consentito; In caso contrario, il prompt si interrompe con un toolCallNotAllowed errore.

Importante

L'autorizzazione di una chiamata concede il consenso. Esaminare le operazioni approvate e avviare gli scenari di sola lettura. Un'aspettativa non concede il consenso; L'approvazione non forza la selezione o dimostra l'esecuzione. Gli strumenti che non richiedono conferma non sono controllati da questo elenco, pertanto non si tratta di un limite di sicurezza.

Gli identificatori del consenso sono diversi dalle calls[].tool identità. Non dividere gli identificatori di consenso per popolare i campi dell'identità dell'analizzatore.

Trovare nomi di chiamate di strumenti

Per gli agenti dichiarativi, usare runevals --list-tools per elencare gli identificatori di consenso e le identità degli analizzatori pronti per la copia. Microsoft 365 Agents Toolkit può anche esaminare le informazioni sull'avvio dell'agente acquisito. Per i plug-in autonomi, --list-tools non è supportato. È invece necessario creare identificatori di consenso dal manifesto dell'app.

Agenti dichiarativi

# List consent identifiers and evaluator identities for declarative agent actions.
npx -y --package @microsoft/m365-copilot-eval@preview runevals --list-tools "<your-agent-id>"

# Alternatively, inspect launch information with Agents Toolkit.
# Use the package Title ID without the .declarativeAgent suffix.
atk launchinfo --title-id "<your-title-id>"

Gli strumenti individuati dinamicamente potrebbero non essere elencati. Dopo una valutazione della chiamata di attrezzo, conferma le loro identità nel report JSON.diagnostics.tool_calls

Agents Toolkit richiede l'accesso all'app e un accesso separato a Microsoft 365 (atk auth login m365). Il suo account può essere diverso dall'account utilizzato per la valutazione.

Plug-in autonomi

Costruisci ogni identificatore di consenso dal manifesto dell'app del plug-in (agentConnectors[]) come segue:

<connector display name with only A-Z, a-z, and 0-9 retained>_<function name>

Conservare l'involucro. Rimuovere spazi, trattini, caratteri di sottolineatura, punteggiatura e caratteri non ASCII solo dal nome visualizzato del connettore. Mantenere invariato il nome della funzione.

Nome visualizzato connettore Nome funzione allowed_tools voce
Contoso Catalog get_product ContosoCatalog_get_product
Contoso Catalog-Tools_1! get_product ContosoCatalogTools1_get_product

In alternativa, esegui una valutazione una volta: se uno strumento richiede il consenso e non è consentito, il messaggio di risultato include il nome dello strumento.

Identità chiamata strumento

Tutti e tre i campi di identità sono obbligatori all'interno calls[].tool:

Campo Tipo Descrizione
plugin_id stringa Copiate M365_TITLE_ID dall'agente distribuito o dal file di ambiente del progetto plugin, ad esempio env\.env.local. Questo è l'ID del titolo del pacchetto (plugin.titleId in Informazioni sviluppatore), nonplugin.id. Obbligatorio anche quando l'interfaccia della riga di comando ha già come destinazione l'agente dichiarativo.
toolset_id stringa Per un'azione dichiarativa dell'agente, utilizzarla actions[].id nel manifesto dell'agente dichiarativo. Per un plug-in autonomo, usalo agentConnectors[].id nel manifesto dell'app.
function_name stringa Nome della funzione definito dal tuo plugin, ad esempio get_product. Conservare l'involucro; questo è riportato come functionDisplayName in Informazioni per gli sviluppatori.

La tupla (plugin_id, toolset_id, function_name) identifica in modo univoco uno strumento. Per la corrispondenza viene fatta distinzione tra maiuscole e minuscole. Usare gli ID delle azioni o dei connettori, non i nomi visualizzati. Ad esempio:

{
  "plugin_id": "T_1234",
  "toolset_id": "catalog",
  "function_name": "get_product"
}

Configurazione dell'analizzatore

Configura evaluators queste opzioni sotto ToolCallSelection o in default_evaluators, ToolCallExecution o nell'oggetto di un oggetto o di un turno:

Opzione Type Obbligatorio Descrizione
calls matrice Sì Elenco non vuoto di selezioni o esecuzioni previste.
calls[].id stringa No Non vuoto, etichetta di diagnostica locale dell'analizzatore; non è un ID chiamata di runtime. Usa un'etichetta univoca per ogni aspettativa.
calls[].tool oggetto Sì Tutti e tre i campi da Tool-call identity.
allow_additional_calls Valore booleano No Solo ToolCallSelection. Il valore predefinito è true. Impostare su false per rifiutare qualsiasi identità selezionata aggiuntiva, incluse le selezioni non identificate.

ToolCallSelection

ToolCallSelection controlla il set di identità dello strumento previste, ignorando l'ordine e i duplicati. Non verifica la riuscita dell'esecuzione o il numero di chiamate.

Set di dati di esempio ToolCallSelection

Salva questo set di dati come evals\tool-selection.json. Sostituire l'identificatore di identità e consenso di esempio con il proprio:

{
  "schemaVersion": "2.0.0",
  "default_allowed_tools": ["ContosoCatalog_get_product"],
  "default_evaluators": {
    "ToolCallSelection": {
      "calls": [
        {
          "tool": {
            "plugin_id": "T_1234",
            "toolset_id": "catalog",
            "function_name": "get_product"
          }
        }
      ],
      "allow_additional_calls": false
    }
  },
  "items": [
    {
      "prompt": "Find product SKU-123 in the Contoso Catalog."
    }
  ]
}

Esecuzione su un agente dichiarativo distribuito:

runevals --m365-agent-id "<your-agent-id>" --prompts-file evals\tool-selection.json --output results\tool-selection.json

Per uno scenario di plug-in autonomo, omettere --m365-agent-id e assicurarsi che non sia configurato alcun ID agente, come descritto in Configurare l'interfaccia della riga di comando di anteprima.

I risultati seguenti presuppongono plugin_id e toolset_id corrispondono all'esempio.

Selezioni osservate Risultato in questo esempio
get_product, incluse le voci duplicate Pass
get_product e un'altra funzione Operazione non riuscita: selezione aggiuntiva
Nessuna funzione selezionata ([]) Errore: selezione obbligatoria mancante
Telemetria non disponibile (null) Errore

ToolCallExecution

ToolCallExecution richiede un'esecuzione corrispondente distinta con uno stato HTTP intero 200-299 per ogni voce in calls. Ripetere un'identità per richiedere più esecuzioni riuscite.

Sono consentiti ulteriori tentativi, inclusi i tentativi non riusciti. Il successo HTTP da solo non stabilisce la correttezza aziendale o la qualità delle risposte.

Set di dati di esempio ToolCallExecution

Salvare questo set di dati con il nome evals\tool-execution.json e sostituire le identità di esempio e l'identificatore del consenso con i propri:

{
  "schemaVersion": "2.0.0",
  "default_evaluators": {
    "ToolCallExecution": {
      "calls": [
        {
          "id": "first-lookup",
          "tool": {
            "plugin_id": "T_1234",
            "toolset_id": "catalog",
            "function_name": "get_product"
          }
        },
        {
          "id": "second-lookup",
          "tool": {
            "plugin_id": "T_1234",
            "toolset_id": "catalog",
            "function_name": "get_product"
          }
        }
      ]
    }
  },
  "items": [
    {
      "prompt": "Look up products SKU-123 and SKU-456 individually in the Contoso Catalog.",
      "allowed_tools": ["ContosoCatalog_get_product"]
    }
  ]
}

Esegui il set di dati con la stessa configurazione di destinazione dell'esempio di selezione:

runevals --m365-agent-id "<your-agent-id>" --prompts-file evals\tool-execution.json --output results\tool-execution.json
Risultati HTTP corrispondenti osservati Risultato in questo esempio
200, 200 Pass
500, 200, 200 Passaggio: due successi nonostante un tentativo fallito
200 Fallito: solo un successo
200, sconosciuto Errore: il risultato sconosciuto potrebbe soddisfare la seconda chiamata

In questo esempio vengono controllate due chiamate riuscite, non gli ID prodotto utilizzati. Ogni aspettativa richiede un'esecuzione distinta; Un'esecuzione non può soddisfare entrambi.

Interpretare i risultati

Usare queste regole per distinguere gli errori dagli errori di valutazione:

Osservazione Risultato
Ogni selezione prevista è presente e le regole per le selezioni aggiuntive sono soddisfatte Passaggi di selezione
Una selezione obbligatoria è assente da un elenco autorevole La selezione non riesce
Un numero sufficiente di esecuzioni HTTP 2xx distinte corrispondono a tutte le identità previste Passaggi di esecuzione
Non è presente un'identità di esecuzione prevista o i risultati confermati rendono impossibile il numero di successi richiesto Esecuzione non riuscita
Una chiamata osservata ha un'identità incompleta Non accreditato ad alcuna chiamata prevista
I dati di telemetria necessari non sono disponibili, più artefatti di informazioni per gli sviluppatori impediscono uno snapshot autorevole o i risultati HTTP non analizzabili potrebbero modificare il verdetto Errore dell'analizzatore: toolCallEvidenceIndeterminate

Un fallimento definitivo ha la precedenza se le prove sconosciute non possono soddisfare tutte le aspettative. Tentativi extra illeggibili non invalidano abbastanza successi confermati.

Pass = 1.0; fail = 0.0. Gli errori omettono score e threshold; non sono passaggi o necessariamente difetti dell'agente. Le chiavi del punteggio JSON sono toolCallSelection e toolCallExecution:

{
  "scores": {
    "toolCallSelection": {
      "score": 1.0,
      "result": "pass",
      "threshold": 1.0,
      "reason": "All expected tool functions were selected."
    },
    "toolCallExecution": {
      "result": "error",
      "error": "Developer Info execution telemetry is unavailable.",
      "code": "toolCallEvidenceIndeterminate"
    }
  }
}

Diagnostica e valutazione delle risposte salvate

Output Evidenza della chiamata agli strumenti
JSON diagnostics.tool_calls
CSV Oggetto di diagnostica serializzato completo
HTML / console Diagnostica delle chiamate dello strumento con selezioni ed esiti HTTP

La visualizzazione della selezione deduplica le identità; La diagnostica di esecuzione preserva ogni tentativo. null indica la prova non disponibile; [] indica un'osservazione autorevole di nessuna chiamata.

Assegna nuovamente un punteggio alle selezioni salvate e ai risultati di esecuzione senza eseguire richieste. Ogni elemento o turno salvato deve includere un response:

npx -y --package @microsoft/m365-copilot-eval@preview runevals --evaluate-only results\captured-tool-calls.json --output results\rescored.html

Avviso

La diagnostica può contenere dettagli sensibili sullo strumento e sull'esecuzione. EVALS_SUPPRESS_DIAGNOSTICS=true Omette la diagnostica mantenuta.

Non oscura prompt, risposte, opzioni dell'analizzatore o messaggi di convalida nativi. Esaminare gli artefatti prima di condividerli. Le prove soppresse non sono disponibili per la riproduzione.