Примечание.
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
В этом руководстве содержатся советы по устранению распространенных проблем, которые могут возникнуть при разработке приложения Model Context Protocol (MCP) для интеграции с декларативным агентом внутри Microsoft 365 Copilot.
Включить режим разработчика
Включение режима разработчика отображает журналы и ошибки в ответах агента. Эти сведения необходимы для отладки. Чтобы включить режим разработчика, введите следующую команду в Microsoft Copilot.
-developer on
Средства MCP, доступные вашему агенту, отображаются в разделе "Действия" на карте сведений об отладке. Подробности об карте сведений об отладке см. в статье "Использование режима разработчика в Microsoft 365 Copilot для тестирования и отладки агентов".
Проблемы обнаружения и входа
Инструменты не указаны
Если в разделе «Действия» карты сведений об отладке отсутствуют инструменты MCP, проведите проверку указанные ниже элементы.
- Убедитесь, что сервер MCP работает и вы подключаетесь к правильной конечной точке MCP в манифесте подключаемого модуля.
- Убедитесь, что проверка подлинности прошла успешно. Многие серверы MCP не возвращают инструменты, пока пользователь не выполнит вход в систему, поэтому сбой или пропуск входа в систему может привести к пустому списку инструментов.
Динамическое обнаружение инструментов
Если агент использует динамическое обнаружение средств (по умолчанию), средства разрешаются с сервера во время выполнения. Проверьте следующее.
- Среда
RemoteMCPServerвыполнения задаетrun_for_functionsзначение и["*"]массив верхнего уровняfunctionsпуст. - Метод сервера
tools/listвозвращает инструменты. Вы можете проверить ответ с помощью такого инструмента, как MCP Inspector. - Недавно обнаруженное или измененное средство не скрывается при проверке во время выполнения. Проверьте сведения об отладке на наличие ошибок проверки.
"runtimes": [
{
"type": "RemoteMCPServer",
"spec": {
"url": "https://api.contoso.com/mcp"
},
"run_for_functions": [
"*"
]
}
]
Закрепленные инструменты
Если вы закрепили фиксированный набор инструментов, убедитесь, что среда выполнения сервера MCP, указанная runtimes в свойстве в манифесте подключаемого модуля:
- Включает ожидаемые средства в свойстве верхнего уровня
functions. - Ссылается на средства в свойстве
mcp_tool_descriptionодним из следующих способов:- Ссылка на файл JSON, который содержит описания инструментов в свойстве
fileИЛИ - Перечисление описаний инструментов в свойстве
tools
- Ссылка на файл JSON, который содержит описания инструментов в свойстве
- Включает имена инструментов в свойство
run_for_functions.
"runtimes": [
{
"type": "RemoteMCPServer",
"spec": {
"url": "https://api.contoso.com/mcp",
"mcp_tool_description": {
"file": "mcp-tools.json"
}
},
"run_for_functions": [
"get_widget",
"create_widget"
]
}
]
Инструменты не запускаются из чата Copilot
- Пересмотрите описания инструментов и параметров, чтобы убедиться, что они предоставляют достаточный контекст. Попробуйте переписать их с помощью фразы "Использовать эту функцию/параметр, если...". формулировки.
- Длина описания не должна превышать 1024 символа. Текст более 1024 символов игнорируется.
- Убедитесь, что видимость инструмента настроена правильно.
- Для приложений
_meta.ui.visibilityMCP в числоmodel - Для приложений
meta["openai/visibility"]OpenAI SDK установлено значениеpublic.
- Для приложений
Выбран не тот инструмент
- Старайтесь не использовать инструменты с похожими именами или совпадающими описаниями.
- Добавьте четкие отличительные черты в описания, объясняющие, когда следует использовать каждый инструмент.
Проблемы с мини-приложением
Мини-приложение не отображается
Если вызывается правильное средство MCP, но мини-приложение пользовательского интерфейса не отображается в отклике, сервер MCP, скорее всего, возвращает только структурированное содержимое без компонента пользовательского интерфейса. Убедитесь, что привязка пользовательского интерфейса настроена правильно.
- Для приложений MCP определение инструмента включает
_meta.ui.resourceUriв себя задание в зарегистрированный HTML-ресурс с типомtext/html;profile=mcp-appMIME. - Для приложений OpenAI SDK определение инструмента включает в себя
_meta["openai/outputTemplate"]задан зарегистрированный HTML-ресурс с типомtext/html+skybridgeMIME .
Мини-приложение не загружается
- Откройте средства разработчика браузера и проверка на наличие нарушений политики безопасности содержимого (CSP) в консоли. Убедитесь, что запросы с URL-адреса узла мини-приложения разрешены. Дополнительные сведения см. в разделе Требования к серверу MCP для приложений MCP.
- Убедитесь, что мини-приложение компилирует все зависимости HTML и JavaScript в один файл без внешних неразрешенных ресурсов.
Мини-приложение загружается без данных
- Проверьте структуру отклика средства.
-
contentдолжна содержать только данные (модель). -
structuredContentдолжен содержать как данные, так и мини-приложение. -
_metaдолжен содержать только мини-приложение.
-
- Найдите
structuredContentили_metaвключите необходимые данные.
Мини-приложение имеет двойную полосу прокрутки
В контейнере узла Copilot уже есть прокрутка с максимальной высотой. Отключите внутреннюю прокрутку в мини-приложении, задав overflow: hidden стили контейнеров.
Гиперссылки в мини-приложении не открываются
Теги <a> привязки не работают для внешних ссылок в Copilot. Вместо этого используйте подходящие API платформы.
- Для приложений MCP используйте
app.openLink. - Для приложений OpenAI SDK используйте
window.openai.openExternal.
Полноэкранный режим не работает в некоторых узлах Copilot
Полноэкранный режим поддерживается не на всех узлах Copilot. Рекомендуется всегда выполнять проверку возможностей узла и условно отображать элементы пользовательского интерфейса (например, кнопку "Во весь экран"). Дополнительные сведения см. в статье Проверка доступности API.
Проблемы с реагированием
Проблемы со сроком действия результатов средства
Убедитесь, что отклики инструментов отправлены content или structuredContent не имеют слишком большого размера. Если мини-приложению требуются расширенные метаданные, которые не полезны для модели, такие как URL-адреса аватаров или детали, относящиеся к пользовательскому интерфейсу, включите полные данные и _meta предоставьте краткую сводку в content. Такой подход гарантирует, что модель сохраняет ключевую информацию и поддерживает эффективное многооборотное взаимодействие.
Дублирование данных в мини-приложении и текстовом резюме
Эту проблему можно решить одним из следующих способов:
-
Оптимизация разделения данных: используйте
_metaдля данных, относящихся к мини-приложениям, иcontentдля сводок, видимых для модели. - Управление форматированием: используйте инструкции в манифесте декларативного агента, чтобы управлять структурой и представлением ответов.
Проблемы с проверкой подлинности
Информацию о проблемах проверки подлинности, таких как сбои при входе, ошибки маркеров, запросы на продолжение и несоответствия конфигурации проверки подлинности, см. в статье Устранение неполадок проверки подлинности подключаемого модуля MCP и API.