M365-Agent-Evaluator

Verwenden Sie diese Funktion, um Benutzern bei der Bewertung von deklarativen Microsoft 365 Copilot-Agenten mit @microsoft/m365-copilot-eval zu helfen. Die Funktion entwirft schemakompatible Bewertungsdatensätze, führt die CLI der öffentlichen Vorschau aus, analysiert die Ergebnisse und empfiehlt gezielte Korrekturen.

Verwenden Sie standardmäßig Projekte des Microsoft 365 Agents Toolkit (ATK), wenn diese erkannt werden, brechen Sie den Vorgang jedoch nicht zwingend ab, nur weil das aktuelle Verzeichnis kein ATK-Verzeichnis ist. Die CLI kann auch bereitgestellte Agenten mit einer expliziten M365_AGENT_ID oder dem Parameter --m365-agent-id bewerten.

Verwenden Sie immer diesen CLI-Aufruf

npx -y --package @microsoft/m365-copilot-eval@latest runevals

Der alte private „aka.ms“-Installer, globale Installationen, „runevals“ ohne weitere Angaben, „npx runevals“ ohne weitere Angaben sowie die Optionen „--input“ oder „--html“ werden nicht empfohlen.

Aktivierungsablauf

1. Ermitteln Sie das Benutzerziel: Einrichtung, Erstellung von Datensätzen, Ausführen von Eval-Läufen, Analysieren der Ergebnisse oder Aktualisieren einer bestehenden Eval-Suite.
2. Laden Sie nur die für das aktuelle Ziel benötigte Referenz:
   • references/workflow.md für den End-to-End-Workflow des Operators und die CLI-Befehle.
   • references/azure-setup.md für Voraussetzungen, Umgebungsdateien und den Umgang mit Geheimnissen.
   • references/eval-templates.md beim Erstellen oder Bearbeiten von Evaluierungsdatensätzen.
   • references/pra-framework.md bei der Entscheidung, welche Szenarien generiert werden sollen.
   • references/result-analysis.md, sobald JSON-/CSV-/HTML-Ergebnisse vorliegen.
   • references/guardrails.md vor dem Schreiben von Dateien, dem Umgang mit Geheimnissen, dem Leeren des Caches, dem Abmelden oder der Fehlerbehebung.
3. Projektstruktur erkennen:
   • ATK: .env.local, .env.local.user, env\.env.local.user, m365agents.yml oder appPackage\declarativeAgent.json.
   • Nicht-ATK: ein Eval-Datensatz plus M365_AGENT_ID, --m365-agent-id oder eine benannte Umgebungsdatei wie z. B. env\.env.dev.
4. Voraussetzungen überprüfen, ohne Werte offenzulegen:
   • Node.js 24.12.0 oder neuer.
   • Microsoft 365 Copilot-Lizenz und ein bereitgestellter M365 Copilot-Agent.
   • Zustimmung des Mandantenadministrators für die WorkIQ-Client-App.
   • TENANT_ID, Endpunkt/Schlüssel für Azure OpenAI in Foundry Models sowie die empfohlene/standardmäßige Bereitstellung von gpt-4o-mini.
5. Wählen Sie den Workflow:
   • Kein Datensatz: „evals\evals.json“ erstellen.
   • Vorhandener Datensatz: Ausführen, vorherige Ergebnisse analysieren oder Änderungen vorschlagen.
   • Schnellprüfung: Verwenden Sie Inline-Eingabeaufforderungen.
   • Erkundung: Verwenden Sie den interaktiven Modus.

Aktueller Datensatz-Vertrag

Generieren Sie Dokumente der Schema-Version 1.2.0 mit einem Array von Stammelementen. Generieren Sie nicht das alte „PromptsObject“- oder „Root-Prompts“-Format.

Mindestform:

{
  "schemaVersion": "1.2.0",
  "metadata": {
    "name": "Agent evaluation suite",
    "tags": ["starter"]
  },
  "default_evaluators": {
    "Relevance": {},
    "Coherence": {}
  },
  "items": [
    {
      "prompt": "Wobei kann mir dieser Agent helfen?",
      "expected_response": "Der Agent erläutert seinen unterstützten Funktionsumfang, ohne nicht unterstützte Fähigkeiten zu erfinden."
    }
  ]
}

Verwenden Sie „references\prompts-schema.json“ als lokale Schemaquelle und „references\eval-templates.md“ für kopierbare Beispiele für Single-Turn-, Multi-Turn-, Evaluator- und Schwellenwert-Szenarien.

Öffentliche Evaluator-Namen

Bei Evaluator-Namen wird zwischen Groß- und Kleinschreibung unterschieden. Verwenden Sie ausschließlich die öffentlichen, konfigurierbaren Evaluator-Namen, sofern keine neuere, maßgebliche Quelle etwas anderes belegt.

Behandeln Sie „ToolCallAccuracy“ bei der Erstellung als veraltet/privat. Fügen Sie es nicht zu generierten Datensätzen hinzu, es sei denn, die aktuelle öffentliche CLI-/Schema-Dokumentation führt es ausdrücklich wieder ein.

Häufige Befehle

# Versions- und Hilfsprüfungen
npx -y --package @microsoft/m365-copilot-eval@latest runevals --version
npx -y --package @microsoft/m365-copilot-eval@latest runevals --help

# Ersteinrichtung / EULA
npx -y --package @microsoft/m365-copilot-eval@latest runevals accept-eula
npx -y --package @microsoft/m365-copilot-eval@latest runevals --init-only

# Stapelverarbeitung mit expliziter JSON-Ausgabe
npx -y --package @microsoft/m365-copilot-eval@latest runevals --prompts-file evals\evals.json --output .evals\results.json

# Für die manuelle Überprüfung geeignetes HTML oder tabellenkalkulationsfreundliches CSV
npx -y --package @microsoft/m365-copilot-eval@latest runevals --prompts-file evals\evals.json --output .evals\results.html
npx -y --package @microsoft/m365-copilot-eval@latest runevals --prompts-file evals\evals.json --output .evals\results.csv

# Schnellprüfungen
npx -y --package @microsoft/m365-copilot-eval@latest runevals --prompts „Wobei kannst du mir helfen?“ --expected „Der Agent beschreibt seinen unterstützten Umfang.“

# Nicht-ATK- oder benannte Umgebung
npx -y --package @microsoft/m365-copilot-eval@latest runevals --prompts-file evals\evals.json --m365-agent-id  --env dev

Verwende `--concurrency` nur mit Werten zwischen 1 und 5. Beginne mit 1 zum Debuggen und erhöhe den Wert erst, wenn die Konfiguration stabil läuft.

Versions- und PATH-Sicherheit

Bevor Sie das Verhalten des Agenten diagnostizieren, überprüfen Sie, welche ausführbare Datei ausgeführt wird:

Get-Command runevals -All
npm list -g @microsoft/m365-copilot-eval --depth=0
npm view @microsoft/m365-copilot-eval version
npx -y --package @microsoft/m365-copilot-eval@latest runevals --version
npx -y --package @microsoft/m365-copilot-eval@latest where runevals

Wenn der Befehl „runevals“ ohne weitere Angaben die Meldung „Diese Version der M365 Evals CLI funktioniert nicht mehr und muss aktualisiert werden“ ausgibt, behandeln Sie dies als veraltete PATH-/globale Installation. Führen Sie den Befehl erneut mit dem oben genannten Befehl „npx --package ...@latest“ aus und bestätigen Sie anschließend, bevor Sie globale Shims mit „npm uninstall -g @microsoft/m365-copilot-eval“ entfernen.

Dateikonventionen

Geben Sie niemals Geheimnisse, Eingabeaufforderungen mit sensiblen Daten, abgerufene Inhalte, Debug-Protokolle oder Rohdatendateien aus und committen Sie diese auch nicht, es sei denn, der Benutzer fordert dies ausdrücklich an und bestätigt, dass die Daten sicher weitergegeben werden können.

Leitfaden zur Generierung

Verwenden Sie PRA als Rahmenwerk für das Szenario-Design:

• Wahrnehmung: Abruf, Verankerung und Quellenabdeckung.
• Argumentieren: Einhaltung von Anweisungen, Synthese, Umgang mit Mehrdeutigkeiten und Ablehnungsverhalten.
• Handeln: Deklarierte Fähigkeiten/Handlungsverhalten. Bewerten Sie mit öffentlichen Bewertungsmetriken wie Relevanz, Kohärenz, Ähnlichkeit, ExactMatch oder PartialMatch; verwenden Sie nicht die veraltete Metrik „ToolCallAccuracy“.

Fragen Sie nach, bevor Sie einen bestehenden Datensatz überschreiben. Schreiben Sie generierte Bewertungsdaten zunächst in eine temporäre Datei und benennen Sie diese bei Erfolg um.

Leitfaden zur Ergebnisanalyse

Analysiere nur vorhandene Bewertungsschlüssel. Fehlende Bewertungsschlüssel bedeuten in der Regel, dass der Bewerter für diesen Eintrag nicht konfiguriert war, nicht dass er versagt hat.

Verwenden Sie die aktuellen Bewertungsschlüssel, sofern vorhanden: Relevanz, Kohärenz, Fundiertheit, Ähnlichkeit, Zitate, „exactMatch“ und „partialMatch“. Gruppieren Sie Fehler nach wahrscheinlichen Ursachen: Problem mit der Anweisung, Problem mit der Fundiertheit, Problem mit den Zitaten, Abweichung von der erwarteten Antwort, Kompetenzlücke, Problem mit der Authentifizierung/Umgebung oder Problem mit der Bewertungsqualität.

Führen Sie keine echten mandantenabhängigen Bewertungen durch, es sei denn, der Benutzer hat die erforderliche Mandanten-, Agenten- und Azure OpenAI-Konfiguration bereitgestellt oder genehmigt.