Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
Questa guida fornisce consigli per la risoluzione dei problemi comuni che potrebbero verificarsi durante lo sviluppo di un'app Model Context Protocol (MCP) da integrare con un agente dichiarativo all'interno di Microsoft 365 Copilot.
Abilitare la modalità sviluppatore
L'abilitazione della modalità sviluppatore mostra i log e gli errori nelle risposte degli agenti. Queste informazioni sono essenziali per il debug. Per abilitare la modalità sviluppatore, digita il comando seguente in Microsoft Copilot.
-developer on
Gli strumenti MCP disponibili per l'agente vengono visualizzati nella sezione Azioni della scheda informazioni di debug. Per informazioni dettagliate sulla scheda informazioni di debug, vedere Usare la modalità sviluppatore in Microsoft 365 Copilot per testare ed eseguire il debug degli agenti.
Problemi di individuazione e ingresso
Nessun utensile elencato
Se la sezione Azioni della scheda informazioni di debug non elenca alcuno strumento MCP, controllare quanto segue:
- Verifica che il server MCP sia in esecuzione e che ti connetti all'endpoint MCP corretto nel manifesto del plug-in.
- Verificare che l'autenticazione abbia esito positivo. Molti server MCP non restituiscono strumenti finché l'utente non accede, quindi un accesso non riuscito o ignorato può comportare un elenco di strumenti vuoto.
Individuazione dinamica degli utensili
Se l'agente utilizza l'individuazione dinamica degli strumenti (impostazione predefinita), gli strumenti vengono risolti dal server in fase di esecuzione. Verificare che:
- Il
RemoteMCPServerruntime viene impostatorun_for_functionssu["*"]e la matrice di primo livellofunctionsè vuota. - Il metodo del
tools/listserver restituisce gli strumenti. È possibile esaminare la risposta usando uno strumento come MCP Inspector. - Uno strumento appena individuato o modificato non viene trattenuto dalla convalida runtime. Verificare le informazioni di debug per verificare la presenza di errori di convalida.
"runtimes": [
{
"type": "RemoteMCPServer",
"spec": {
"url": "https://api.contoso.com/mcp"
},
"run_for_functions": [
"*"
]
}
]
Strumenti bloccati
Se è stato aggiunto un set fisso di strumenti, verificare che il runtimes runtime del server MCP specificato nella proprietà del manifesto del plug-in:
- Include gli strumenti previsti nella proprietà di primo livello
functions. - Fa riferimento agli strumenti nella
mcp_tool_descriptionproprietà:- Riferimento a un file JSON che contiene le descrizioni degli
filestrumenti nella proprietà OR - Elencare le descrizioni degli strumenti in linea nella
toolsproprietà
- Riferimento a un file JSON che contiene le descrizioni degli
- Include i nomi degli strumenti nella
run_for_functionsproprietà.
"runtimes": [
{
"type": "RemoteMCPServer",
"spec": {
"url": "https://api.contoso.com/mcp",
"mcp_tool_description": {
"file": "mcp-tools.json"
}
},
"run_for_functions": [
"get_widget",
"create_widget"
]
}
]
Strumenti che non si attivano dalla chat di Copilot
- Rivedi le descrizioni degli strumenti e dei parametri per assicurarti che forniscano un contesto sufficiente. Considera di riscriverli usando "Usa questa funzione/parametro quando..." frase.
- Mantenere le descrizioni al di sotto di 1.024 caratteri. Il testo che supera i 1.024 caratteri viene ignorato.
- Assicurarsi che la visibilità dell'utensile sia impostata correttamente.
- Per le app MCP,
_meta.ui.visibilityincludemodel. - Per le app OpenAI SDK,
meta["openai/visibility"]è impostato supublic.
- Per le app MCP,
Viene selezionato lo strumento sbagliato
- Evita gli strumenti con nomi simili o descrizioni sovrapposte.
- Aggiungi chiari elementi di differenziazione nelle descrizioni che spiegano quando ogni strumento deve essere usato.
Problemi con i widget
Il widget non esegue il rendering
Se viene chiamato lo strumento MCP corretto ma il widget dell'interfaccia utente non viene visualizzato nella risposta, è probabile che il server MCP restituisca solo contenuto strutturato senza componenti dell'interfaccia utente. Assicurati che l'associazione dell'interfaccia utente sia configurata correttamente.
- Per le app MCP, la definizione dello strumento include
_meta.ui.resourceUril'impostazione su una risorsa HTML registrata con tipotext/html;profile=mcp-appMIME. - Per le app OpenAI SDK, la definizione dello strumento include
_meta["openai/outputTemplate"]il set su una risorsa HTML registrata con tipotext/html+skybridgeMIME.
Il widget non si carica
- Apri gli strumenti di sviluppo del browser e verifica la presenza di violazioni dei criteri di sicurezza del contenuto (CSP) nella console. Assicurati che le richieste dall'URL host del widget siano consentite nell'elenco. Per altre informazioni, vedere Requisiti del server MCP per le app MCP.
- Verifica che il widget compili tutte le dipendenze HTML e JavaScript in un unico file senza risorse esterne non risolte.
Il widget si carica senza dati
- Verificare la struttura delle risposte dello strumento.
-
contentDeve contenere solo i dati (modello). -
structuredContentDeve contenere sia i dati che il widget. -
_metaDeve contenere solo il widget.
-
- Assicurati di includere
structuredContenti_metadati necessari.
Il widget ha una doppia barra di scorrimento
Il contenitore host Copilot ha già uno scorrimento con altezza massima. Disabilitare lo scorrimento interno nel widget impostando overflow: hidden gli stili del contenitore.
I collegamenti ipertestuali nel widget non si aprono
I tag <a> di ancoraggio non funzionano per i collegamenti esterni in Copilot. Utilizza invece le API della piattaforma appropriate.
- Per le app MCP, usa
app.openLink. - Per le app OpenAI SDK, usa
window.openai.openExternal.
La modalità a schermo intero non funziona in alcuni host Copilot
La visualizzazione a schermo intero non è supportata in tutti gli host Copilot. Come procedura consigliata, verifica sempre le funzionalità host e visualizza in modo condizionale gli elementi dell'interfaccia utente, ad esempio un pulsante a schermo intero. Per altre informazioni, vedi Verificare la disponibilità dell'API.
Problemi di risposta
Problemi di scadenza dei risultati dell'utensile
Assicurarsi che le risposte dello strumento inviate content o structuredContent non siano eccessivamente grandi. Se il widget richiede metadati complessi che non sono utili per il modello, come URL avatar o dettagli specifici dell'interfaccia utente, includere i dati _meta completi e fornire un riepilogo conciso in content. Questo approccio garantisce che il modello conservi le informazioni chiave, supportando al contempo un'esperienza multigiro efficace.
Dati duplicati nel widget e nel riepilogo di testo
Risolvi il problema utilizzando una delle opzioni seguenti:
-
Ottimizza la separazione dei dati: utilizza
_metaper dati specifici del widget econtentper riepiloghi visibili al modello. - Formattazione steer: usa le istruzioni nel manifesto dell'agente dichiarativo per guidare la struttura e la presentazione delle risposte.
Problemi di autenticazione
Per problemi di autenticazione, ad esempio errori di accesso, errori di token, richieste di consenso e mancate corrispondenze della configurazione di autenticazione, vedere Risolvere i problemi di autenticazione dei plug-in MCP e API.