Évaluateurs d’appels d’outils pour Microsoft 365 Copilot Evaluations CLI

Les évaluateurs d’appel d’outil inspectent les diagnostics d’exécution (informations sur le développeur) pour vérifier la sélection de l’outil et les résultats de l’exécution HTTP. Ils sont déterministes, n’utilisent pas de juge LLM et ne jugent pas le texte de la réponse ou n’exigent expected_responsepas .

Remarque

Les évaluateurs d’appel d’outil nécessitent les évaluations Microsoft 365 Copilot CLI v2 (preview) et schéma v2. Ils ne sont pas disponibles dans CLI v1 (latest).

Évaluateur Vérifications Scale Seuil Activées par défaut
ToolCallSelection Si les identités d’outil attendues ont été sélectionnées Réussite/échec/erreur 1.0, corrigé Non
ToolCallExecution Si chaque appel attendu a une exécution HTTP réussie distincte Réussite/échec/erreur 1.0, corrigé Non

Pour une configuration générale du jeu de données, voir Configurer les évaluateurs.

Configurer l’interface de ligne de commande d’aperçu

Suivez les conditions préalables d’accès au locataire et d’exécution dans le guide de démarrage rapide. La configuration de la notation Microsoft Foundry n’est pas nécessaire si vous exécutez uniquement des évaluateurs déterministes.

Installez la version préliminaire et acceptez les termes du contrat de licence :

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

Définissez TENANT_ID votre locataire Microsoft 365 dans votre environnement d’évaluation. Pour un agent déclaratif déployé, réussite --m365-agent-id "<your-agent-id>" lors de l’exécution d’un jeu de données.

Pour les évaluations de plug-in autonomes, configurez et activez d’abord le plug-in dans Microsoft 365 Copilot, puis effectuez toute connexion au connecteur requise dans Copilot. Sans ID d’agent configuré, la préversion v2 évalue la conversation Copilot. Keep M365_AGENT_ID and legacy AGENT_ID out of your shell and loaded environment files for these runs. Cela évalue les réponses Copilot qui utilisent un plug-in disponible, et non le point de terminaison du plug-in de manière isolée.

L’installation de l’une ou l’autre des balises de publication npm remplace la commande globale runevals . Pour revenir à la v1, réinstallez @microsoft/m365-copilot-eval@latest.

Autoriser les appels d’outils

Lorsqu’un outil nécessite une confirmation, configurez les attentes de l’approbation et de l’évaluateur. default_allowed_tools au niveau du document et allowed_tools par invite ou tour, laissez l’interface CLI approuver les invites de confirmation de l’outil. Chaque identifiant de consentement demandé doit être autorisé ; Dans le cas contraire, l’invite s’arrête avec une toolCallNotAllowed erreur.

Important

L’autorisation d’un appel accorde le consentement. Passez en revue les opérations que vous approuvez et commencez par des scénarios en lecture seule. Une attente n’accorde pas le consentement ; L’approbation ne force pas la sélection ou ne prouve pas l’exécution. Les outils qui ne demandent pas de confirmation ne sont pas contrôlés par cette liste, il ne s’agit donc pas d’une limite de sécurité.

Les identificateurs de consentement sont différents des calls[].tool identités. Ne fractionnez pas les identificateurs de consentement pour remplir les champs d’identité de l’évaluateur.

Rechercher des noms d’appels d’outils

Pour les agents déclaratifs, utilisez cette option runevals --list-tools pour répertorier les identificateurs de consentement et les identités d’évaluateur prêtes à être copiées. Microsoft 365 Agents Toolkit peut également inspecter les informations de lancement de l’agent acquis. Pour les plug-ins autonomes, --list-tools n’est pas pris en charge ; construisez plutôt des identificateurs de consentement à partir du manifeste de l’application.

Agents déclaratifs

# 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>"

Les outils découverts dynamiquement peuvent ne pas être répertoriés. Après une évaluation d’appel d’outil, confirmez leurs identités diagnostics.tool_callsdans le rapport JSON .

Agents Toolkit nécessite un accès à l’application et une connexion Microsoft 365 distincte (atk auth login m365). Son compte peut différer du compte utilisé pour l’évaluation.

Plug-ins autonomes

Construisez chaque identificateur de consentement à partir du manifeste d’application de votre plug-in (agentConnectors[]) comme suit :

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

Conservez le boyau. Supprimez les espaces, les traits d’union, les traits de soulignement, les signes de ponctuation et les caractères non-ASCII du nom d’affichage du connecteur uniquement. Ne modifiez pas le nom de la fonction.

Nom complet du connecteur Nom de la fonction allowed_tools entrée
Contoso Catalog get_product ContosoCatalog_get_product
Contoso Catalog-Tools_1! get_product ContosoCatalogTools1_get_product

Vous pouvez également exécuter une évaluation une seule fois : Si un outil nécessite un consentement et n’est pas autorisé, le message de résultat inclut son nom.

Identité d’appel d’outil

Les trois champs d’identité sont requis à l’intérieur calls[].tool:

Champ Type Description
plugin_id chaîne Copiez M365_TITLE_ID à partir du fichier d’environnement de votre projet d’agent ou de plug-in déployé, par exemple env\.env.local. Il s’agit de l’ID de titre du package (plugin.titleId dans les informations sur le développeur), nonplugin.id. Obligatoire même lorsque l’interface de ligne de commande cible déjà cet agent déclaratif.
toolset_id chaîne Pour une action d’agent déclaratif, utilisez sa actions[].id dans le manifeste de l’agent déclaratif. Pour un plug-in autonome, utilisez son agentConnectors[].id dans le manifeste de l’application.
function_name chaîne Nom de fonction défini par votre module, par exemple get_product. Conservez l’enveloppe ; Ceci est indiqué dans functionDisplayName les informations sur le développeur.

Le tuple (plugin_id, toolset_id, function_name) identifie un outil de manière unique. La correspondance est sensible à la casse. Utilisez les ID d’action ou de connecteur, pas les noms d’affichage. Par exemple :

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

Configuration de l’évaluateur

Configurez ces options sous ToolCallSelection ou ToolCallExecution dans default_evaluators, ou dans l’objet d’un élément ou d’un evaluators tour :

Option Type (Type) Obligatoire Description
calls tableau Oui Liste non vide des sélections ou exécutions attendues.
calls[].id chaîne Non Étiquette diagnostique locale de l’évaluateur non vide ; pas un ID d’appel d’exécution. Utilisez une étiquette unique pour chaque attente.
calls[].tool objet Oui Les trois champs de l’identité d’appel d’outil.
allow_additional_calls Booléen Non ToolCallSelection uniquement. La valeur par défaut est .true Défini sur false pour rejeter toute identité sélectionnée supplémentaire, y compris les sélections non identifiées.

ToolCallSelection

ToolCallSelection vérifie l’ensemble des identités d’outils attendues, en ignorant l’ordre et les doublons. Il ne vérifie pas la réussite de l’exécution ni le nombre d’appels.

Exemple de jeu de données ToolCallSelection

Enregistrez ce jeu de données sous le nom evals\tool-selection.json. Remplacez les exemples d’identité et d’identificateur de consentement par les vôtres :

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

Exécuter sur un agent déclaratif déployé :

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

Dans un scénario de plug-in autonome, omettez --m365-agent-id et assurez-vous qu’aucun ID d’agent n’est configuré, comme décrit dans Configurer l’interface de ligne de commande en préversion.

Les résultats suivants supposent plugin_id et toolset_id correspondent à l’exemple.

Sélections observées Résultat de cet échantillon
get_product, y compris les entrées en double Réussite
get_product et une autre fonction Échec : sélection supplémentaire
Aucune fonction sélectionnée ([]) Échec : sélection requise manquante
Télémétrie non disponible (null) Erreur

ToolCallExecution

ToolCallExecution requiert une exécution correspondante distincte avec un status HTTP entier 200-299 pour chaque entrée dans calls. Répéter une identité pour exiger plusieurs exécutions réussies.

Les tentatives supplémentaires, y compris les tentatives ayant échoué, sont autorisées. Le succès HTTP seul n’établit pas l’exactitude des affaires ou la qualité des réponses.

Exemple de jeu de données ToolCallExecution

Enregistrez ce jeu evals\tool-execution.json de données et remplacez les exemples d’identités et d’identificateur de consentement par les vôtres :

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

Exécutez le jeu de données avec la même configuration de cible que l’exemple de sélection :

runevals --m365-agent-id "<your-agent-id>" --prompts-file evals\tool-execution.json --output results\tool-execution.json
Résultats HTTP correspondants observés Résultat de cet échantillon
200, 200 Réussite
500, 200, 200 Passe : deux succès malgré une tentative ratée
200 Échec : un seul succès
200, inconnu Erreur : le résultat inconnu pourrait satisfaire le deuxième appel

Cet échantillon vérifie deux appels réussis, et non l’ID de produit utilisé. Chaque attente nécessite une exécution distincte ; Une exécution ne peut pas satisfaire les deux.

Interpréter les résultats

Utilisez ces règles pour distinguer les échecs des erreurs de l’évaluateur :

Constat Result (Résultat)
Chaque sélection attendue est présente et les règles relatives aux sélections supplémentaires sont respectées Passes de sélection
Une sélection obligatoire est absente d’une liste faisant autorité Échec de la sélection
Un nombre suffisant d’exécutions HTTP 2xx distinctes correspondent à chaque identité attendue Passes d’exécution
Une identité d’exécution attendue est manquante ou les résultats confirmés rendent impossible le nombre de réussites requises Échec d’exécution
Un appel observé a une identité incomplète Non crédité à un appel attendu
La télémétrie requise n’est pas disponible, plusieurs artefacts d’informations sur le développeur empêchent un instantané faisant autorité ou des résultats HTTP inalysables peuvent modifier le verdict Erreur de l’évaluateur : toolCallEvidenceIndeterminate

Un échec définitif a la priorité si une preuve inconnue ne peut pas répondre à toutes les attentes. Des tentatives supplémentaires illisibles n’invalident pas suffisamment de succès confirmés.

Réussite = 1.0; échec = 0.0. Les erreurs omettent score et threshold; ce ne sont pas des réussites ou nécessairement des défauts d’agent. Les clés de score JSON sont toolCallSelection et 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"
    }
  }
}

Diagnostics et évaluation des réponses enregistrées

Sortie Preuve d’appel d’outil
JSON diagnostics.tool_calls
CSV Objet de diagnostics sérialisé complet
HTML / console Outil Appel Diagnostics avec sélections et résultats HTTP

L’affichage de la sélection déduplique les identités ; Les diagnostics d’exécution conservent chaque tentative. null désigne les preuves non disponibles ; [] désigne une observation faisant autorité de l’absence d’appels.

Réévaluez les sélections enregistrées et les résultats d’exécution sans exécuter d’invites. Chaque élément ou tour enregistré doit comporter un response:

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

Avertissement

Les diagnostics peuvent contenir des détails sensibles sur l’outil et l’exécution. EVALS_SUPPRESS_DIAGNOSTICS=trueomet les diagnostics conservés.

Il ne supprime pas les invites, les réponses, les options d’évaluateur ou les messages de validation natifs. Examinez les artefacts avant de les partager. Les preuves supprimées ne sont pas disponibles pour la relecture.