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.
Dieses Handbuch enthält Ratschläge zur Problembehandlung für häufige Probleme, die beim Entwickeln einer MCP-App (Model Context Protocol) zur Integration in einen deklarativen Agent in Microsoft 365 Copilot auftreten können.
Entwicklermodus aktivieren
Wenn Sie den Entwicklermodus aktivieren , werden Protokolle und Fehler in den Antworten des Agents angezeigt. Diese Informationen sind wichtig für das Debuggen. Geben Sie in Microsoft Copilot den folgenden Befehl ein, um den Entwicklermodus zu aktivieren.
-developer on
MCP-Tools, die Ihrem Agent zur Verfügung stehen, werden im Abschnitt "Aktionen" der Debug-Informations-Karte angezeigt. Ausführliche Informationen zur Debug-Information-Karte finden Sie unter Verwenden des Entwicklermodus in Microsoft 365 Copilot zum Testen und Debuggen von Agents.
Probleme bei der Ermittlung und Eingabe
Keine Tools aufgeführt
Wenn im Abschnitt "Aktionen" der Debug-Informations-Karte keine MCP-Tools aufgeführt sind, überprüfen Sie die folgenden Elemente:
- Vergewissern Sie sich, dass Ihr MCP-Server ausgeführt wird und Sie eine Verbindung mit dem richtigen MCP-Endpunkt in Ihrem Plug-In-Manifest herstellen.
- Vergewissern Sie sich, dass die Authentifizierung erfolgreich war. Viele MCP-Server geben keine Tools zurück, bis sich der Benutzer anmeldet, sodass eine fehlgeschlagene oder übersprungene Anmeldung zu einer leeren Toolliste führen kann.
Dynamische Toolermittlung
Wenn Ihr Agent die dynamische Toolermittlung verwendet (Standardeinstellung), werden die Tools zur Laufzeit vom Server aufgelöst. Stellen Sie Folgendes sicher:
- Die
RemoteMCPServerLaufzeit wirdrun_for_functionsauf festgelegt,["*"]und das Array der obersten Ebenefunctionsist leer. - Die Methode des
tools/listServers gibt Werkzeuge zurück. Sie können die Antwort mit einem Tool wie MCP Inspector überprüfen. - Ein neu entdecktes oder geändertes Tool wird nicht von der Laufzeitüberprüfung zurückgehalten. Überprüfen Sie die Debuginformationen auf Validierungsfehler.
"runtimes": [
{
"type": "RemoteMCPServer",
"spec": {
"url": "https://api.contoso.com/mcp"
},
"run_for_functions": [
"*"
]
}
]
Angeheftete Tools
Wenn Sie einen festen Satz von Tools angeheftet haben, stellen Sie sicher, dass die MCP-Serverruntime, die in der runtimes Eigenschaft Ihres Plug-In-Manifests angegeben ist:
- Enthält die erwarteten Werkzeuge in der Eigenschaft der obersten Ebene
functions. - Verweist auf die Tools in der
mcp_tool_descriptionEigenschaft, indem er entweder:- Verweisen auf eine JSON-Datei, die die Werkzeugbeschreibungen in der
fileEigenschaft ODER - Auflisten der Toolbeschreibungen in der
toolsEigenschaft
- Verweisen auf eine JSON-Datei, die die Werkzeugbeschreibungen in der
- Fügt die Werkzeugnamen in die
run_for_functionsEigenschaft ein.
"runtimes": [
{
"type": "RemoteMCPServer",
"spec": {
"url": "https://api.contoso.com/mcp",
"mcp_tool_description": {
"file": "mcp-tools.json"
}
},
"run_for_functions": [
"get_widget",
"create_widget"
]
}
]
Tools, die nicht vom Copilot-Chat ausgelöst werden
- Überprüfen Sie Ihre Tool- und Parameterbeschreibungen, um sicherzustellen, dass sie genügend Kontext bieten. Erwägen Sie, sie mit "Verwenden Sie diese Funktion/diesen Parameter, wenn..." Formulierung.
- Halten Sie Beschreibungen unter 1.024 Zeichen. Text mit mehr als 1.024 Zeichen wird ignoriert.
- Stelle sicher, dass die Sichtbarkeit des Tools richtig eingestellt ist.
- Für MCP-Apps
_meta.ui.visibilitybeinhaltetmodel. - Für OpenAI SDK-Apps
meta["openai/visibility"]ist festgelegt aufpublic.
- Für MCP-Apps
Das falsche Tool ist ausgewählt
- Vermeiden Sie Tools mit ähnlichen Namen oder überlappenden Beschreibungen.
- Fügen Sie klare Unterscheidungsmerkmale in Beschreibungen hinzu, die erklären, wann jedes Tool verwendet werden sollte.
Probleme mit Widget
Widget wird nicht gerendert
Wenn das richtige MCP-Tool aufgerufen wird, Ihr UI-Widget jedoch nicht in der Antwort gerendert wird, gibt Ihr MCP-Server wahrscheinlich nur strukturierte Inhalte ohne UI-Komponente zurück. Stellen Sie sicher, dass die Benutzeroberflächenbindung korrekt konfiguriert ist.
- Für MCP-Apps enthält
_meta.ui.resourceUridie Tooldefinition eine auf eine registrierte HTML-Ressource mit dem MIME-Typtext/html;profile=mcp-appfestgelegte . - Für OpenAI SDK-Apps enthält
_meta["openai/outputTemplate"]die Tooldefinition das Festlegen auf eine registrierte HTML-Ressource mit dem MIME-Typtext/html+skybridge.
Widget kann nicht geladen werden
- Öffnen Sie die Entwicklertools Ihres Browsers, und überprüfen Sie die Konsole auf Verstöße gegen die Inhaltssicherheitsrichtlinie (Content Security Policy, CSP). Stellen Sie sicher, dass Anforderungen von der Host-URL des Widgets auf die Zulassungsliste gesetzt sind. Weitere Informationen finden Sie unter MCP-Serveranforderungen für MCP-Apps.
- Stellen Sie sicher, dass Ihr Widget alle HTML- und JavaScript-Abhängigkeiten in eine einzige Datei ohne externe unaufgelöste Ressourcen kompiliert.
Widget wird ohne Daten geladen
- Überprüfen Sie die Antwortstruktur des Tools.
-
contentdarf nur die Daten (das Modell) enthalten. -
structuredContentsollte sowohl die Daten als auch das Widget enthalten. -
_metasollte nur das Widget enthalten.
-
- Stellen Sie
structuredContentsicher, dass die erforderlichen Daten vorhanden sind, oder_metaschließen Sie sie ein.
Widget hat eine doppelte Bildlaufleiste
Der Copilot-Hostcontainer verfügt bereits über einen Bildlauf mit maximaler Höhe. Deaktivieren Sie den inneren Bildlauf in Ihrem Widget, indem Sie Container-Stile festlegen overflow: hidden .
Links im Widget werden nicht geöffnet
Ankertags <a> funktionieren nicht für externe Links in Copilot. Verwenden Sie stattdessen die entsprechenden Plattform-APIs.
- Verwenden Sie
app.openLinkfür MCP-Apps . - Verwenden Sie
window.openai.openExternalfür OpenAI SDK-Apps .
Vollbildmodus funktioniert in einigen Copilot-Hosts nicht
Die Vollbildansicht wird nicht auf allen Copilot-Hosts unterstützt. Überprüfen Sie als bewährte Methode immer die Hostfunktionen und zeigen Sie bedingt UI-Elemente (z. B. eine Schaltfläche im Vollbildmodus) an. Weitere Informationen finden Sie unter Überprüfen der API-Verfügbarkeit.
Probleme mit der Antwort
Probleme mit Ablauf des Toolergebnisses
Stellen Sie sicher, dass die Toolantworten gesendet werden content oder structuredContent nicht übermäßig groß sind. Wenn Ihr Widget umfangreiche Metadaten benötigt, die für das Modell nicht nützlich sind, wie z. B. Avatar-URLs oder UI-spezifische Details, fügen Sie die vollständigen Daten ein _meta und geben Sie eine präzise Zusammenfassung in content. Dieser Ansatz stellt sicher, dass das Modell wichtige Informationen beibehält und gleichzeitig ein effektives Multiturn-Erlebnis unterstützt.
Duplizieren von Daten in Widget und Textzusammenfassung
Verwenden Sie eine der folgenden Optionen, um das Problem zu beheben:
-
Optimieren Sie die Datentrennung: Verwenden Sie diese Option
_metafür Widget-spezifische Daten undcontentfür modellsichtbare Zusammenfassungen. - Steuerung der Formatierung: Verwenden Sie Anweisungen im manifesten deklarativen Agent, um zu steuern, wie Antworten strukturiert und präsentiert werden.
Authentifizierungsprobleme
Bei Authentifizierungsproblemen wie Anmeldefehlern, Tokenfehlern, Zustimmungsaufforderungen und nicht übereinstimmender Authentifizierungskonfiguration finden Sie weitere Informationen unter Problembehandlung bei der MCP- und API-Plug-In-Authentifizierung.