Toolcall-Evaluatoren für Microsoft 365 Copilot Auswertungen CLI

Tool-Call-Evaluatoren untersuchen die Laufzeit-Diagnose (Entwicklerinformationen), um die Toolauswahl und die Ergebnisse der HTTP-Ausführung zu überprüfen. Sie sind deterministisch, verwenden keinen LLM-Richter und beurteilen keinen Antworttext oder verlangen expected_response.

Hinweis

Toolaufruf-Evaluatoren erfordern Microsoft 365 Copilot Auswertungen CLI v2 (preview) und Schema v2. Sie sind in der CLI v1 nicht verfügbar ().latest

Evaluator Schecks Scale Schwellenwert Standardmäßig aktiviert
ToolCallSelection Ob die erwarteten Toolidentitäten ausgewählt wurden Bestanden/Fehler/Fehler 1.0, behoben Nein
ToolCallExecution Ob jeder erwartete Aufruf eine eindeutige erfolgreiche HTTP-Ausführung hat Bestanden/Fehler/Fehler 1.0, behoben Nein

Allgemeine Dataset-Einrichtung finden Sie unter Konfigurieren von Evaluatoren.

Einrichten der Vorschau-CLI

Befolgen Sie die Voraussetzungen für den Mandantenzugriff und die Laufzeit im Schnellstart. Die Microsoft Foundry-Bewertungskonfiguration ist nicht erforderlich, wenn Sie nur deterministische Evaluatoren ausführen.

Installieren Sie die Vorschauversion und akzeptieren Sie die Lizenzbedingungen:

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

Für Ihren Microsoft 365-Mandanten in Ihrer Evaluierungsumgebung festlegen TENANT_ID . Für einen bereitgestellten deklarativen Agent, übergeben --m365-agent-id "<your-agent-id>" Sie beim Ausführen eines Datasets.

Für eigenständige Plug-In-Evaluierungen stellen Sie das Plug-In zuerst in Microsoft 365 Copilot bereit und aktivieren Sie es, und schließen Sie alle erforderlichen Connector-Anmeldungen in Copilot ab. Ohne konfigurierte Agent-ID wertet die v2-Vorschau den Copilot-Chat aus. Bewahren Sie M365_AGENT_ID Legacydateien AGENT_ID für diese Ausführungen aus Ihrer Shell und geladenen Umgebungsdateien heraus. Dadurch werden Copilot-Antworten ausgewertet, die ein verfügbares Plug-In verwenden, nicht den Plug-In-Endpunkt isoliert.

Die Installation eines der beiden npm-Release-Tags ersetzt den globalen runevals Befehl. Um zu Version 1 zurückzukehren, installieren Sie @microsoft/m365-copilot-eval@latesterneut .

Toolaufrufe zulassen

Wenn ein Tool eine Bestätigung erfordert, konfigurieren Sie sowohl die Genehmigungs- als auch die Evaluatorerwartungen. default_allowed_tools auf Dokumentebene und allowed_tools pro Eingabeaufforderung oder Wendung lassen Sie die CLI Toolbestätigungsaufforderungen genehmigen. Jeder angeforderte Zustimmungsbezeichner muss zugelassen werden; Andernfalls bleibt die Eingabeaufforderung mit einem toolCallNotAllowed Fehler stehen.

Wichtig

Das Zulassen eines Anrufs erteilt die Zustimmung. Überprüfen Sie die Vorgänge, die Sie genehmigen, und beginnen Sie mit schreibgeschützten Szenarien. Eine Erwartung gewährt keine Zustimmung; Die Genehmigung erzwingt weder die Auswahl noch beweist die Ausführung. Tools, die keine Bestätigung anfordern, werden nicht von dieser Liste gesteuert, es handelt sich also nicht um eine Sicherheitsgrenze.

Zustimmungsbezeichner unterscheiden sich von calls[].tool Identitäten. Teilen Sie die Zustimmungsbezeichner nicht auf, um die Felder für die Evaluatoridentität aufzufüllen.

Suchen nach Toolcall-Namen

Für deklarative Agents wird verwendet runevals --list-tools , um Zustimmungsbezeichner und kopierbereite Evaluatoridentitäten aufzulisten. Microsoft 365 Agents Toolkit kann auch die Startinformationen des erworbenen Agenten überprüfen. Für eigenständige Plug-Ins wird dies nicht unterstützt. --list-tools Erstellen Sie stattdessen Zustimmungsbezeichner aus dem App-Manifest.

Deklarative Agents

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

Dynamisch ermittelte Tools sind möglicherweise nicht aufgeführt. Bestätigen Sie nach einer Tool-Call-Auswertung ihre Identitäten in den Tabellen des JSON-Berichts.diagnostics.tool_calls

Agents Toolkit erfordert Zugriff auf die App und eine separate Microsoft 365-Anmeldung (atk auth login m365). Das Konto kann sich von dem Konto unterscheiden, das für die Bewertung verwendet wird.

Eigenständige Plugins

Erstellen Sie die einzelnen Zustimmungsbezeichner aus dem App-Manifest (agentConnectors[]) Ihres Plug-Ins wie folgt:

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

Bewahren Sie das Gehäuse auf. Entfernen Sie Leerzeichen, Bindestriche, Unterstriche, Satzzeichen und Nicht-ASCII-Zeichen nur aus dem Anzeigenamen des Verbinders. Den Funktionsnamen unverändert lassen.

Anzeigename des Connectors Funktionsname allowed_tools Eintrag
Contoso Catalog get_product ContosoCatalog_get_product
Contoso Catalog-Tools_1! get_product ContosoCatalogTools1_get_product

Alternativ können Sie eine Auswertung einmal ausführen: Wenn ein Tool eine Zustimmung erfordert und nicht zulässig ist, enthält die Ergebnismeldung den Namen des Tools.

Toolaufruf-Identität

Alle drei Identitätsfelder sind erforderlich calls[].tool:

Feld Typ Beschreibung
plugin_id Zeichenfolge Kopieren Sie M365_TITLE_ID z. B env\.env.local. aus der Umgebungsdatei Ihres bereitgestellten Agent- oder Plug-In-Projekts. Dies ist die Titel-ID des Pakets (plugin.titleId in der Entwicklerinformation), nichtplugin.id. Auch dann erforderlich, wenn die CLI bereits auf diesen deklarativen Agent abzielt.
toolset_id Zeichenfolge Verwenden Sie für eine deklarative Agent-Aktion its actions[].id im Manifest des deklarativen Agents. Verwenden Sie für ein eigenständiges Plug-In das agentConnectors[].id App-Manifest.
function_name Zeichenfolge Von Ihrem Plugin definierter Funktionsname, z.B get_product. . . Gehäuse aufbewahren; dies wird wie functionDisplayName in den Entwicklerinformationen gemeldet.

Das Tupel (plugin_id, toolset_id, function_name) identifiziert ein Tool eindeutig. Beim Abgleich wird die Groß-/Kleinschreibung beachtet. Verwenden Sie Aktions- oder Connector-IDs, keine Anzeigenamen. Beispiel:

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

Konfiguration des Evaluators

Konfigurieren Sie diese Optionen unter ToolCallSelection oder ToolCallExecution in default_evaluatorsoder im Objekt eines Elements oder einer Runde evaluators :

Option Type Erforderlich Beschreibung
calls Matrix Ja Nicht leere Liste der erwarteten Auswahlen oder Ausführungen.
calls[].id Zeichenfolge Nein Nicht leere, auswertungslokale Diagnosebezeichnung; keine Laufzeitaufruf-ID. Verwenden Sie für jede Erwartung eine eindeutige Bezeichnung.
calls[].tool Objekt Ja Alle drei Felder aus Tool-Call-Identität.
allow_additional_calls Boolescher Wert Nein Nur ToolCallSelection. Der Standardwert ist true. Legen Sie diese Einstellung fest false , um jede zusätzliche ausgewählte Identität abzulehnen, einschließlich nicht identifizierter Auswahlen.

ToolCallSelection

ToolCallSelection überprüft den Satz der erwarteten Toolidentitäten und ignoriert Reihenfolge und Duplikate. Der Ausführungserfolg oder die Anzahl der Aufrufe wird nicht überprüft.

ToolCallSelection sample dataset

Dieses Dataset speichern als evals\tool-selection.json. Ersetzen Sie die Beispielidentitäten und den Einwilligungsbezeichner durch Ihre eigenen:

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

Ausführen für einen bereitgestellten deklarativen Agent:

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

Lassen Sie --m365-agent-id für ein eigenständiges Plug-In-Szenario keine Agent-ID aus, und stellen Sie sicher, dass keine Agent-ID konfiguriert ist, wie unter Einrichten der Vorschau-CLI beschrieben.

Die folgenden Ergebnisse entsprechen plugin_idtoolset_id dem Beispiel.

Beobachtete Auswahl Ergebnis in diesem Beispiel
get_product, einschließlich doppelter Einträge Bestanden
get_product und eine weitere Funktion Fehler: zusätzliche Auswahl
Keine Funktionen ausgewählt ([]) Fehler: Erforderliche Auswahl fehlt
Nicht verfügbare Telemetrie (null) Fehler

ToolCallExecution

ToolCallExecution erfordert eine eindeutige übereinstimmende Ausführung mit einem ganzzahligen HTTP-Status 200-299 für jeden Eintrag in calls. Wiederholen einer Identität, um mehrere erfolgreiche Ausführungen zu erfordern.

Zusätzliche Versuche, einschließlich fehlgeschlagener Wiederholungsversuche, sind zulässig. Der Erfolg von HTTP allein ist noch kein Beweis für geschäftliche Korrektheit oder Antwortqualität.

ToolCallExecution sample dataset

Speichern Sie dieses Dataset unter evals\tool-execution.json , und ersetzen Sie die Beispielidentitäten und den Zustimmungsbezeichner durch Ihre eigenen:

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

Führen Sie das Dataset mit der gleichen Zielkonfiguration wie im Auswahlbeispiel aus:

runevals --m365-agent-id "<your-agent-id>" --prompts-file evals\tool-execution.json --output results\tool-execution.json
Beobachtete übereinstimmende HTTP-Ergebnisse Ergebnis in diesem Beispiel
200, 200 Bestanden
500, 200, 200 Bestanden: Zwei Erfolge trotz gescheitertem Versuch
200 Fehler: nur ein Erfolg
200, unbekannt Fehler: Das unbekannte Ergebnis könnte den zweiten Aufruf erfüllen

In diesem Beispiel werden zwei erfolgreiche Aufrufe überprüft, nicht die verwendeten Produkt-IDs. Jede Erwartung erfordert eine bestimmte Ausführung; Eine Ausführung kann nicht beide erfüllen.

Interpretieren der Ergebnisse

Verwenden Sie die folgenden Regeln, um Fehler von Auswertungsfehlern zu unterscheiden:

Beobachtung Result
Jede erwartete Auswahl ist vorhanden, und Regeln für zusätzliche Auswahlen werden erfüllt Auswahl durchläuft
Eine erforderliche Auswahl fehlt in einer maßgeblichen Liste Auswahl schlägt fehl
Genügend eindeutige HTTP 2xx-Ausführungen entsprechen jeder erwarteten Identität Ausführungsdurchläufe
Eine erwartete Ausführungsidentität fehlt oder bestätigte Ergebnisse machen die erforderliche Erfolgszählung unmöglich Ausführung schlägt fehl
Ein beobachteter Anruf weist eine unvollständige Identität auf Keinem erwarteten Anruf gutgeschrieben
Erforderliche Telemetrie ist nicht verfügbar, mehrere Entwicklerinformationen-Artefakte verhindern eine autorisierende Momentaufnahme, oder nicht analysierbare HTTP-Ergebnisse könnten das Urteil ändern Evaluator-Fehler: toolCallEvidenceIndeterminate

Ein definitives Scheitern hat Vorrang, wenn unbekannte Beweise nicht alle Erwartungen erfüllen können. Unlesbare zusätzliche Versuche machen nicht genügend bestätigte Erfolge ungültig.

Pass = 1.0; fail = . 0.0 Fehler lassen und scorethreshold; sie sind keine Durchläufe oder notwendigerweise Agentenfehler. JSON-Bewertungsschlüssel sind toolCallSelection und 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"
    }
  }
}

Diagnose und Auswertung gespeicherter Antworten

Ausgabe Beweise für Toolaufrufe
JSON-Code diagnostics.tool_calls
CSV Vollständiges serialisiertes Diagnoseobjekt
HTML / Konsole Toolaufrufdiagnose mit Auswahlmöglichkeiten und HTTP-Ergebnissen

Auswahlanzeige dedupliziert Identitäten; Die Ausführungs-Diagnose bewahrt jeden Versuch. null bedeutet nicht verfügbare Beweise; [] bedeutet eine maßgebliche Beobachtung von No Calls.

Bewerten Sie gespeicherte Auswahlen und Ausführungsergebnisse neu, ohne Eingabeaufforderungen auszuführen. Jeder gespeicherte Gegenstand oder Spielzug muss Folgendes responseenthalten:

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

Warnung

Diagnosen können sensible Tool- und Ausführungsdetails enthalten. EVALS_SUPPRESS_DIAGNOSTICS=trueLässt die aufbewahrte Diagnose aus.

Eingabeaufforderungen, Antworten, Auswertungsoptionen oder systemeigene Validierungsmeldungen werden nicht geschwärzt. Überprüfen Sie Artefakte vor der Freigabe. Unterdrückte Beweise sind nicht für die Wiedergabe verfügbar.