Problembehandlung für die Agent-Auswertungs-CLI (Vorschau)

Dieser Artikel enthält Informationen zur Problembehandlung für die cli für Microsoft 365 Copilot-Agent-Auswertungen. Probleme werden nach der Phase des Workflows gruppiert, die sie betreffen: Setup, Authentifizierung, Laufzeit und Umgebung.

Setupprobleme

Probleme, die während der Installation oder beim erstmaligen Ausführen der CLI aufgetreten sind.

Installationsfehler

Wenn npm install -g @microsoft/m365-copilot-eval ein Fehler auftritt:

• Vergewissern Sie sich, dass Sie Node.js 24.12.0 oder höher ausführen: node --version.
• Überprüfen Sie, ob Sie über die Berechtigung zum Installieren globaler npm-Pakete verfügen. Unter Unix/macOS benötigen sudo Sie möglicherweise oder eine nvm-verwaltete Node-Installation.
• Wenn Sie sich hinter einem Unternehmensproxy befinden, finden Sie weitere Informationen unter Netzwerk- oder Proxyprobleme.

runevals Befehl nicht gefunden

Wenn der Befehl nach der runevals Installation nicht erkannt wird:

# Verify the package is installed globally
npm list -g @microsoft/m365-copilot-eval

# Reinstall if missing
npm install -g @microsoft/m365-copilot-eval

Wenn das Paket aufgeführt ist, der Befehl aber immer noch nicht gefunden wird, überprüfen Sie, ob sich Ihr globales bin npm-Verzeichnis in Ihrem PATHbefindet:

npm bin -g

Fügen Sie das Ausgabeverzeichnis zu Ihrer PATH hinzu, wenn es fehlt.

Zwischenspeichern der Python-Umgebung

Das Tool lädt eine Python-Runtime und Abhängigkeiten bei der ersten Ausführung herunter. So richten Sie die Umgebung im Voraus ein, ohne Auswertungen auszuführen:

runevals --init-only

Dies ist nützlich für:

• Voraberwärmung des Caches in CI/CD-Pipelines.
• Testen des Setups, ohne Auswertungen auszuführen.
• Isolieren von Installationsfehlern von Auswertungsproblemen.

Kombinieren Sie für die Problembehandlung des Setups selbst mit der Debugprotokollierung:

runevals --init-only --log-level debug

Authentifizierungsprobleme

Probleme mit Mandanten-, Agent- oder Azure OpenAI-Anmeldeinformationen.

Authentifizierungsfehler

Wenn die Authentifizierung fehlschlägt:

• Überprüfen Sie, ob TENANT_ID dem Mandanten entspricht, in dem Ihr Agent bereitgestellt wird.
• Vergewissern Sie sich, dass Sie unter Windows ausgeführt werden. Unterstützung für andere Betriebssysteme ist in Kürze verfügbar.
• Stellen Sie sicher, dass Sie beim richtigen Microsoft 365-Konto angemeldet sind.
• Wenn Sie mehrere Mandanten verwenden, melden Sie sich von anderen Konten ab, bevor Sie ausführen runevals.

Mandantenkonflikt

Wenn das Tool eine Verbindung herstellt, aber keinen Agent zurückgibt, stimmt ihr TENANT_ID möglicherweise nicht mit dem Mandanten überein, in dem der Agent bereitgestellt wird. Überprüfen Sie die Mandanten-ID, indem Sie Folgendes ausführen:

az account show --query tenantId

Sie können auch die Anweisungen unter Erforderliche Umgebungsvariablen befolgen.

Azure OpenAI-API-Schlüsselfehler

Wenn bei der Auswertungsbewertung ein Fehler vom Typ 401 oder 403 auftritt:

• Überprüfen Sie, ob AZURE_AI_API_KEY korrekt und nicht abgelaufen ist.
• Vergewissern Sie sich, dass AZURE_AI_OPENAI_ENDPOINT mit der Ressource übereinstimmt, zu der der Schlüssel gehört.
• Überprüfen Sie, ob gpt-4o-mini (oder der Modellsatz in AZURE_AI_MODEL_NAME) in Ihrer Azure OpenAI-Ressource bereitgestellt wurde.

Laufzeitprobleme

Probleme, die beim Ausführen von Auswertungen nach dem erfolgreichen Setup auftreten.

Agent nicht gefunden

Wenn das Tool Ihren Agent nicht finden kann:

• Überprüfen Sie M365_AGENT_ID (oder M365_TITLE_ID für Agents Toolkit-Projekte) die Richtigkeit.
• Vergewissern Sie sich, dass Ihr Agent auf dem von TENANT_IDangegebenen Mandanten bereitgestellt wurde.
• Stellen Sie sicher, dass Sie über die Berechtigung für den Zugriff auf den Agent verfügen.
• Geben Sie die Agent-ID explizit an: runevals --m365-agent-id "<your-agent-id>".

Auswertungsfehler

Wenn Auswertungen gestartet werden, während der Ausführung aber fehlschlagen:

• Führen Sie mit ausführlicher Protokollierung aus, um detaillierte Fehler anzuzeigen: runevals --log-level debug.
• Überprüfen Sie exit codes for the general failure category (Allgemeine Fehlerkategorie). Weitere Informationen finden Sie unter Exitcodes in der CLI-Referenz.

Umgebungsprobleme

Probleme mit der zwischengespeicherten Python-Runtime, dem Cacheverzeichnis oder der Netzwerkkonnektivität.

Cacheprobleme

Das Auswertungstool verwendet einen lokalen Cache für die Python-Runtime und Abhängigkeiten.

# View cache info
runevals cache-info

# Clear and rebuild the cache
runevals cache-clear
runevals --init-only --log-level debug

Berechtigungsprobleme

Wenn Cachevorgänge mit Berechtigungsfehlern fehlschlagen:

# View the cache directory path
runevals cache-dir

# Fix permissions (Unix/macOS)
chmod -R u+w $(runevals cache-dir)

# Fix permissions (Windows PowerShell)
icacls "$(runevals cache-dir)" /grant ${env:USERNAME}:F /T

Netzwerk- oder Proxyprobleme

Wenn die Initialisierung hinter einem Unternehmensproxy fehlschlägt:

# Set proxy (Unix/macOS)
export HTTPS_PROXY=http://proxy:8080
export HTTP_PROXY=http://proxy:8080

# Set proxy (Windows PowerShell)
$env:HTTPS_PROXY="http://proxy:8080"
$env:HTTP_PROXY="http://proxy:8080"

# Retry initialization with verbose output
runevals --init-only --log-level debug

Support anfordern

Wenn das Problem mit den obigen Schritten zur Problembehandlung nicht behoben werden kann, melden Sie ein Problem im GitHub-Repository M365 Copilot-Agent-Auswertungen.

Bevor Sie ein Problem melden, sammeln Sie Folgendes:

• Die CLI-Version: runevals --version.
• Der genaue Befehl, den Sie ausgeführt haben.
• Fehlerausgabe (redigieren Sie alle PII, Schlüssel oder mandantenspezifischen Bezeichner).
• Ihr Betriebssystem und Node.js Version: node --version.

So melden Sie das Problem:

• Öffnen Sie eine neue Ausgabe unter M365 Copilot Agent Evaluation – Issues.
• Wenden Sie die entsprechende Bezeichnung (z. B setup. , authentication, runtime, environment) an, um die Selektierung zu erleichtern.

Verwandte Inhalte

• Übersicht über die Cli für Agent-Auswertungen
• Schnellstart: Verwenden der Agent-Auswertungs-CLI
• Datasetschema und Testentwurf
• CLI-Referenz