Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Este guia fornece conselhos de solução de problemas comuns que você pode encontrar ao desenvolver um aplicativo MCP (Protocolo de Contexto de Modelo) para integração com um agente declarativo dentro do Microsoft 365 Copilot.
Habilitar o modo de desenvolvedor
A ativação do modo de desenvolvedor mostra logs e erros nas respostas do agente. Essas informações são essenciais para depuração. Para habilitar o modo de desenvolvedor, digite o comando a seguir no Microsoft Copilot.
-developer on
As ferramentas MCP disponíveis para seu agente aparecem na seção Ações do card de informações de depuração. Para obter detalhes sobre o card de informações de depuração, consulte Usar o modo de desenvolvedor no Microsoft 365 Copilot para testar e depurar agentes.
Problemas de descoberta e entrada
Nenhuma ferramenta listada
Se a seção Ações do card de informações de depuração não listar nenhuma ferramenta MCP, marque os seguintes itens:
- Confirme se o servidor MCP está em execução e se você está se conectando ao ponto de extremidade MCP correto no manifesto do plug-in.
- Confirme se a autenticação foi bem-sucedida. Muitos servidores MCP não retornam ferramentas até que o usuário entre, portanto, uma entrada com falha ou ignorada pode resultar em uma lista de ferramentas vazia.
Descoberta dinâmica de ferramentas
Se o agente usar a descoberta dinâmica de ferramentas (o padrão), as ferramentas serão resolvidas a partir do servidor em tempo de execução. Verifique se:
- O
RemoteMCPServertempo de execução é definidorun_for_functionscomo["*"]e a matriz de nívelfunctionssuperior está vazia. - O método do
tools/listservidor retorna ferramentas. Você pode inspecionar a resposta usando uma ferramenta como MCP Inspector. - Uma ferramenta recém-descoberta ou modificada não é retida pela validação de runtime. Verifique se há erros de validação nas informações de depuração.
"runtimes": [
{
"type": "RemoteMCPServer",
"spec": {
"url": "https://api.contoso.com/mcp"
},
"run_for_functions": [
"*"
]
}
]
Ferramentas fixadas
Se você fixou um conjunto fixo de ferramentas, verifique se o tempo de execução do servidor MCP foi especificado na propriedade do manifesto runtimes do plug-in:
- Inclui as ferramentas esperadas na propriedade de nível
functionssuperior. - Faz referência às
mcp_tool_descriptionferramentas na propriedade:- Referenciar um arquivo JSON que contém as descrições da ferramenta na
filepropriedade OU - Listar as descrições embutidas da
toolsferramenta na propriedade
- Referenciar um arquivo JSON que contém as descrições da ferramenta na
- Inclui os nomes de ferramenta na
run_for_functionspropriedade.
"runtimes": [
{
"type": "RemoteMCPServer",
"spec": {
"url": "https://api.contoso.com/mcp",
"mcp_tool_description": {
"file": "mcp-tools.json"
}
},
"run_for_functions": [
"get_widget",
"create_widget"
]
}
]
Ferramentas não acionadas a partir do chat do Copilot
- Reveja as descrições de ferramentas e parâmetros para garantir que forneçam contexto suficiente. Considere reescrevê-los usando "Usar esta função/parâmetro quando..." fraseado.
- Mantenha as descrições com menos de 1.024 caracteres. Texto com mais de 1.024 caracteres será ignorado.
- Certifique-se de que a visibilidade da ferramenta esteja definida corretamente.
- Para aplicativos MCP,
_meta.ui.visibilityincluimodel. - Para aplicativos SDK do OpenAI,
meta["openai/visibility"]é definido comopublic.
- Para aplicativos MCP,
A ferramenta errada está selecionada
- Evite ferramentas com nomes semelhantes ou descrições sobrepostas.
- Adicione diferenciais claros nas descrições que explicam quando cada ferramenta deve ser usada.
Problemas com widgets
O widget não renderiza
Se a ferramenta MCP correta for chamada, mas o widget de interface do usuário não for renderizado na resposta, o servidor MCP provavelmente retornará apenas conteúdo estruturado sem componente de interface do usuário. Verifique se a associação da interface do usuário está configurada corretamente.
- Para aplicativos MCP, a definição da ferramenta inclui
_meta.ui.resourceUridefinido como um recurso HTML registrado com o tipotext/html;profile=mcp-appMIME. - Para aplicativos OpenAI SDK, a definição da ferramenta inclui
_meta["openai/outputTemplate"]definir um recurso HTML registrado com o tipotext/html+skybridgeMIME.
Falha ao carregar o widget
- Abra as ferramentas de desenvolvedor do navegador e marque se há violações da Política de Segurança de Conteúdo (CSP) no console. Certifique-se de que as solicitações da URL do host do widget estejam listadas na lista de permissões. Para obter mais informações, consulte Requisitos do servidor MCP para aplicativos MCP.
- Verifique se o widget compila todas as dependências de HTML e JavaScript em um único arquivo sem ativos externos não resolvidos.
O widget é carregado sem dados
- Verifique a estrutura de resposta da ferramenta.
-
contentdeve conter apenas os dados (modelo). -
structuredContentdeve conter os dados e o widget. -
_metadeve conter apenas o widget.
-
- Garantir
structuredContentou_metaincluir os dados necessários.
O widget tem uma barra de rolagem dupla
O contêiner de host do Copilot já tem um scroll com altura máxima. Desative a rolagem interna em seu widget definindo overflow: hidden em seus estilos de contêiner.
Os hiperlinks no widget não abrem
Tags <a> âncora não funcionam para links externos no Copilot. Em vez disso, use as APIs de plataforma apropriadas.
- Para aplicativos MCP, use
app.openLink. - Para aplicativos SDK do OpenAI, use
window.openai.openExternal.
A tela inteira não funciona em alguns hosts Copilot
A exibição em tela inteira não é compatível com todos os hosts do Copilot. Como prática recomendada, sempre marque os recursos do host e exiba condicionalmente os elementos da interface do usuário (como um botão de tela inteira). Para obter mais informações, consulte Verificar disponibilidade da API.
Problemas de resposta
Problemas de expiração do resultado da ferramenta
Certifique-se de que as respostas da ferramenta sejam enviadas ou contentstructuredContent não sejam excessivamente grandes. Se o widget exigir metadados avançados que não são úteis para o modelo, como URLs de avatar ou detalhes específicos da interface do usuário, inclua os dados completos e _meta forneça um resumo conciso no contentformato . Essa abordagem garante que o modelo retenha informações importantes, ao mesmo tempo em que oferece suporte a uma experiência eficaz de várias voltas.
Dados duplicados no widget e resumo de texto
Resolva esse problema usando uma das seguintes opções:
-
Otimize a separação de dados: use
_metapara dados específicos de widgets econtentpara resumos visíveis ao modelo. - Formatação de direção: use instruções no manifesto do agente declarativo para orientar como as respostas são estruturadas e apresentadas.
Problemas de autenticação
Para problemas de autenticação, como falhas de entrada, erros de token, solicitações de consentimento e incompatibilidades de configuração de autenticação, consulte Solucionar problemas de autenticação de plug-in MCP e API.