Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
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.