Рекомендации по созданию или обновлению подключаемого модуля расширения сообщений для Copilot для Microsoft 365
Важно!
- Подключаемые модули для Microsoft Copilot для Microsoft 365 доступны в предварительной версии и работают только в Microsoft 365 Chat в Microsoft Teams.
- Убедитесь, что Copilot для Microsoft 365 доступны для вашей организации. Вы можете получить среду разработчика для Copilot двумя способами:
- Клиент песочницы Microsoft 365 с Copilot (доступен в ограниченной предварительной версии благодаря членству в TAP).
- Рабочая среда для корпоративных клиентов с Microsoft Copilot для Microsoft 365 лицензиями.
Подключаемые модули Microsoft 365 обеспечивают интеграцию с различными продуктами Microsoft 365, такими как Teams и Outlook. Интеграция помогает пользователям искать или создавать содержимое во внешних системах. Подключаемые модули расширения сообщений позволяют Microsoft Copilot для Microsoft 365 взаимодействовать с API из другого программного обеспечения и служб через бота. С помощью Copilot для Microsoft 365 вы можете:
- Поиск для получения последних сведений или записей. Например, последний запрос на инцидент или результаты опроса.
- Суммирование сведений на основе нескольких записей. Например, сведите все билеты на инциденты, связанные с проектом Northwind.
Рекомендуется создавать или обновлять существующие расширения сообщений, чтобы максимально повысить их полезность и удобство использования в Copilot для Microsoft 365. Расширения сообщений должны поддерживать одну или несколько команд поиска, так как Copilot для Microsoft 365 распознает их как навыки, которые могут выполняться от имени пользователя. Кроме того, ваши расширения должны соответствовать стандартам соответствия, производительности, безопасности и взаимодействия с пользователем, описанным в этой статье.
Обязательные требования
Требования к созданию подключаемых модулей расширения сообщений для Copilot для Microsoft 365 включают:
Определение описаний
Хорошее описание содержит четкое и краткое описание функций приложения и позволяет Copilot для Microsoft 365 эффективно обнаруживать и выполнять операции поиска. Когда пользователь вводит имя приложения вместе с командой, например Найти билеты Contoso, подключаемый модуль расширения сообщений должен вызываться из Copilot для Microsoft 365 (чат M365).
Убедитесь, что вы придерживаетесь рекомендаций по описанию, перечисленных в следующей таблице:
| Действие | Reason |
|---|---|
|
Защита от конкуренции. Избегайте использования имени любого другого подключаемого модуля как в коротких, так и в длинных описаниях. |
|
|
Ответственный ИИ: избегайте использования недопустимых или оскорбительных ключевых слов. |
|
|
Запрос на внедрение. Убедитесь, что описания не помогут Copilot выполнять действия, которые обходят нормальное функционирование приложения. Кроме того, описание не должно содержать символы или текст, указывающие на то, что его можно использовать в качестве кода для внедрения запроса. Избегайте использования фраз, функций и кода, которые периодически вызывают приложение. |
Описание приложения
Длинные и короткие описания приложений должны быть четкими и определять область приложения. Чтобы отобразить приложение в виде подключаемого модуля в Copilot для Microsoft 365, измените описание приложения в соответствии со следующими требованиями к подключаемого модулям:
- Длинное описание должно четко объяснять функции и использование подключаемого модуля расширения сообщений в Copilot для Microsoft 365. Например, используйте облако Contoso в Copilot для Microsoft 365 для поиска и подведения итогов по задачам.
- Краткое описание должно кратко описывать функциональные возможности приложения на естественном языке и включать имя приложения.
В следующей таблице перечислены краткие примеры описания для каждой категории:
Описание: создание, поиск, просмотр билетов, ошибок и проектов.
Пример описания приложения:
{
"$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.13/MicrosoftTeams.schema.json",
"version": "1.0.0",
"manifestVersion": "1.13",
"id": "2bxxxxc5-5xxx-4xxx-aXXX-94xxxx8919e5",
"name": {
"short": "Tasks",
"full": "Contoso Tasks"
},
"description": {
"short": "Create, search, view tickets, bugs, and projects",
"full": "Contoso Tasks makes it easy to stay organized. Create, assign, and track tasks individually or collaboratively with your team, and see everything come together in one place."
},
Поиск описание команды
Описание команды сопоставляет намерения и высказывания пользователя с командой поиска в подключаемом модуле и должно быть построено на основе анализа намерения пользователя и ключевых слов. Поиск описания команд должны:
- Сосредоточьтесь на том, что и как команда выполняет поиск (подробный список) на естественном языке.
- Если применимо, включите глаголы и синонимы.
- Сосредоточьтесь на ключевых словах, которые, скорее всего, будут использоваться в функции поиска собственных приложений.
Семантическое описание
Свойство semanticDescription используется для предоставления подробного описания команды для Copilot для Microsoft 365. Семантическое описание команд поддерживает до 5000 символов и не отображается в пользовательском интерфейсе. semanticDescription Если свойство остается пустым, Copilot для Microsoft 365 использует сведения в description поле . При написании semanticDescriptionнеобходимо включить сведения об ожидаемых значениях, ограничениях и диапазонах для команды .
Свойство semanticDescription не является обязательным полем. Однако при добавлении semanticDescription в манифест приложения существующие проверки для кратких, параметров и описаний команд также применимы для семантических описаний.
Мы рекомендуем ознакомиться со следующими рекомендациями по семантике описания, чтобы повысить вероятность того, что ваше приложение пройдет процесс отправки в Microsoft Teams Store:
- Избегайте таких фраз, как "если пользователь говорит X", "игнорировать", "удалить", "сбросить", "новые инструкции", "Ответ полужирным шрифтом" или "Ничего не печатать". [Обязательное исправление]
- Избегайте URL-адресов, эмодзи или скрытых символов, таких как шестнадцатеричные, двоичные или нетрадиционные символы. [Обязательное исправление]
- Избегайте грамматических ошибок и ошибок препинания. [Обязательное исправление]
- Избегайте чрезмерно подробного, цветочного или маркетингового языка. [Предлагаемое исправление]
- Избегайте превосходных утверждений, таких как "#1", "удивительный" или "лучший". [Предлагаемое исправление]
В следующей таблице перечислены примеры команд и семантического описания для каждой категории:
Описание: Поиск для высокоприоритетных задач, связанных с Northwind, которые должны быть запланированы завтра.
Пример описания команды:
"commands": [
{
"id": "Search",
"type": "query",
"title": "Tasks",
"description": "Search for high priority tasks related to Northwind that are due tomorrow.",
"SemanticDescription": "Search for issues, epics, stories, tasks, sub tasks, bugs + additional details."
"initialRun": true,
"fetchTask": false,
"context": [
"commandBox",
"compose",
"message"
],
Описание параметра
Каждая команда расширения сообщений поддерживает соответствующее свойство parameters, которое поддерживает до пяти параметров, и первый параметр должен быть виден в строке поиска расширения сообщений. Параметр должен иметь хорошее описание, которое должно содержать сочетание допустимых параметров, перечислений, сокращений и формата вывода.
Свойство semanticDescription используется для предоставления подробного описания команды для Microsoft Copilot. Семантическое описание параметров поддерживает до 2000 символов и не отображается в пользовательском интерфейсе. semanticDescription Если свойство остается пустым, Copilot использует сведения в description поле . При написании semanticDescriptionнеобходимо включить сведения об ожидаемых значениях, ограничениях и диапазонах для команды .
Хорошее описание параметра объясняет требования к системе на естественном языке с форматом вывода. Ниже приведено несколько примеров базовых и расширенных поисковых запросов для каждой категории.
Базовый поиск: Поиск для задач, связанных с Northwind.Расширенный поиск: Поиск для высокоприоритетных задач, связанных с Northwind, которые должны быть запланированы завтра.
Пример описания параметра:
"parameters": [
{
"name": "Name",
"title": "Project or Task Name",
"description": "Project name or task name as keyword.",
"inputType": "text"
},
{
"name": "Time",
"title": "Time",
"description": "Date or number of days for which you need tasks for.",
"semanticDescription": "Date or number of days for which you need tasks for. Output: Number",
"inputType": "text"
},
{
"name": "Priority",
"title": "Priority",
"description": "Priority of tasks.",
"semanticDescription": "Priority of tasks. Acceptable values are high, medium, low, NA",
"inputType": "text"
}]
Составные речевые фрагменты
Примечание.
Поиск через диалоговое окно (называется модулем задач в TeamsJS версии 1.x) не поддерживается в чате M365.
Для чата M365 расширение сообщений на основе поиска должно поддерживать более трех уникальных составных речевых фрагментов для глубокого извлечения точной информации. Чтобы включить составные речевые фрагменты, необходимо развернуть область поиска для обработки трех или более параметров поиска, обновив манифест приложения (ранее — манифест приложения Teams) и обеспечить следующее:
Обновите веб-службу для поддержки поиска на основе нескольких параметров. Дополнительные сведения о том, как реагировать на запросы пользователей, см. в разделе Ответить на команду поиска.
Copilot для Microsoft 365 может передавать пустую строку или значение NULL для параметров, которые не являются частью пользовательского высказывания, обновите веб-службу для обработки параметров.
Расширение сообщений поддерживает до 10 команд (9 доступных для использования), и каждая команда имеет соответствующее
parametersсвойство, которое поддерживает до 5 параметров.
Следующий код является примером нескольких параметров, определенных в манифесте приложения:
"commands": [
{
"id": "inventorySearch",
"context": [
"compose",
"commandBox"
],
"description": "Search products by name, category, inventory status, supplier location, stock level",
"title": "Product inventory",
"type": "query",
"parameters": [
{
"name": "productName",
"title": "Product name",
"description": "Enter a product name here",
"inputType": "text"
},
{
"name": "categoryName",
"title": "Category name",
"description": "Enter the category of the product",
"inputType": "text"
},
{
"name": "inventoryStatus",
"title": "Inventory status",
"description": "Enter what status of the product inventory. Possible values are 'in stock', 'low stock', 'on order', or 'out of stock'",
"inputType": "text"
},
{
"name": "supplierCity",
"title": "Supplier city",
"description": "Enter the supplier city of product",
"inputType": "text"
},
{
"name": "stockQuery",
"title": "Stock level",
"description": "Enter a range of integers such as 0-42 or 100- (for >100 items). Only use if you need an exact numeric range.",
"inputType": "text"
}
]
},
{
"id": "discountSearch",
"context": [
"compose",
"commandBox"
],
"description": "Search for discounted products by category",
"title": "Discounts",
"type": "query",
"parameters": [
{
"name": "categoryName",
"title": "Category name",
"description": "Enter the category to find discounted products",
"inputType": "text"
}
]
},
{
"id": "revenueSearch",
"context": [
"compose",
"commandBox"
],
"description": "Find products based on their revenue/period",
"title": "Revenue",
"type": "query",
"parameters": [
{
"name": "revenueRange",
"title": "Revenue range",
"description": "Enter 'high' or 'low' or enter a range of integers such as 0-10000 or 5000- using this exact format",
"inputType": "text"
}
]
}
]
Параметры поиска должны иметь хорошее описание с допустимыми параметрами, перечислениями, сокращениями и форматом вывода. Дополнительные сведения и примеры см. в разделе Описание параметра.
Примеры запросов
Свойство samplePrompts содержит инструкции по использованию различных подключаемых модулей в Copilot. Copilot использует примеры запросов для отображения запросов для пользователя. Запросы должны быть адаптированы к разным языковым стандартом и понятны для разных команд. Примеры запросов доступны в следующих областях в Copilot для Microsoft 365:
- Интерфейс первого запуска (FRE): когда пользователь впервые устанавливает или включает подключаемый модуль.
- Запрашивать библиотеку или Copilot Lab: когда пользователь обращается за помощью с запросами.
- Рекомендации по подключаемым модулям: рекомендации для пользователей по улучшению речевых фрагментов.
Примечание.
- Если в манифесте приложения не указано
samplePromptsсвойство, запросы не отображаются. - Свойство
samplePromptsявляется обязательным для проверки приложения во время отправки приложения. - При определении нескольких команд для приложения пользователю отображается не более трех запросов (по одному из трех первых команд). Запросы сменяются, чтобы предоставить пользователю разнообразный набор запросов в разных командах.
Мы рекомендуем следовать этим рекомендациям, чтобы повысить вероятность того, что ваше приложение пройдет процесс отправки в Microsoft Teams Store:
- Подключаемый модуль должен содержать не менее трех запросов и не более пяти запросов для каждой команды.
- Каждый запрос не должен превышать 128 символов.
- Две команды в одном подключаемом модуле не должны иметь одинаковые запросы.
- Примеры запросов должны быть универсальными по своей природе и не включать пользовательские ссылки. Например, имена проектов и задачи.
- Все примеры запросов должны быть функциональными и возвращать ответы.
- Запрос должен быть связан с командами.
Следующий код является примером свойства в манифесте samplePrompts приложения:
"composeExtensions": [
{
"canUpdateConfiguration": true,
"botId": "bxxxxxx5-xxxx-xxxx-xxxx-4xxxxxx16599",
"commands": [
{
"id": "orders",
"title": "Orders",
"context": [
"Commandbox",
"Compose"
],
"description": "Search for orders",
"semanticDescription": "Search for orders",
"samplePrompts": [
{
"text": "Search for all orders"
},
{
"text": "Search for orders related to Contoso"
},
{
"text": "Search for all pending orders"
},
{
"text": "Search for all completed ordered for Fabrikam"
}
]
}
]
}
]
Ответ адаптивной карточки
Расширения сообщений реагируют на ввод пользователем адаптивной карточки. Адаптивная карточка для подключаемого модуля расширения сообщений должна эффективно функционировать, многофункционально и соответствовать следующим требованиям:
Ответ адаптивной карточки должен включать содержимое адаптивной карточки и предварительный просмотр карта сведения в рамках одного шаблона. [Обязательно]
Пример шаблона ответа адаптивной карточки
{ "$schema": "http://adaptivecards.io/schemas/adaptive-card.json", "type": "AdaptiveCard", "version": "1.5", "body": [ { "type": "Container", "items": [ { "type": "TextBlock", "text": "${companyName}", "size": "Medium", "wrap": true, "style": "heading" }, { "type": "TextBlock", "text": "${stockExchange} ${stockSymbol}", "isSubtle": true, "spacing": "None", "wrap": true }, { "type": "TextBlock", "text": "${formattedDate} ${formattedTime}", "wrap": true } ] }, { "type": "Container", "spacing": "None", "items": [ { "type": "ColumnSet", "columns": [ { "type": "Column", "width": "stretch", "items": [ { "type": "TextBlock", "text": "${currentPrice} ", "size": "ExtraLarge", "wrap": true }, { "type": "TextBlock", "text": "${priceChange} ${percentChange}", "color": "${changeColor}", "spacing": "None", "wrap": true } ] }, { "type": "Column", "width": "auto", "items": [ { "type": "FactSet", "facts": [ { "title": "Open", "value": "${openPrice} " }, { "title": "High", "value": "${highPrice} " }, { "title": "Low", "value": "${lowPrice} " } ] } ] } ] } ] } ], "previewCard": { "contentType": "application/vnd.microsoft.card.hero", "content": { "title": "${companyName}", "text": "${stockSymbol}" } } }Помимо логотипа приложения, заголовка, эскиза и заголовка информации, данные в адаптивной карточке должны представлять не менее двух фрагментов информации. Поля можно определить по наиболее часто используемым атрибутам, таким как измененные данные, автор, состояние и флаги. [Обязательно]
Адаптивная карточка должна быть представлена на настольных компьютерах, в Интернете и мобильных устройствах (iOS и Android). [Обязательно]
Адаптивная карточка должна содержать по крайней мере одну кнопку действия, но не более четырех кнопок действий. [Обязательно]
Примечание.
Типы
imBackmessageBackдействий не поддерживаются в объекте данных.Рекомендуется использовать следующие типы действий:
Action.OpenUrl: открывает указанный URL-адрес из карточки.Action.ToggleVisibility: отображает или скрывает один или несколько элементов в карта.Action.Execute: собирает поля ввода и отправляет их в качестве запроса в службу бота.Action.Submit: открывает диалоговое окно или представление стадии с помощью вызова типа в объекте данных.
Если пользователь может изменить какую-либо информацию о карта с помощью диалогового окна, просмотра этапов или непосредственно из карта, рекомендуется использовать адаптивную карточку для поддержки универсальных действий и автоматического обновления. [Рекомендуется]
Адаптивные карточки должны содержать URL-адрес в составе метаданных, что позволяет легко копировать карточки из одного концентратора в другой. [Рекомендуется]
Помимо эскизов, любое изображение в адаптивной карточке должно иметь замещающий текст. [Рекомендуется]
Технические требования
Чтобы подключаемый модуль проверялся, вызывался и работал без проблем, убедитесь, что он соответствует следующим критериям:
| Критерии | Выполнение |
|---|---|
| Версия манифеста | Манифест приложения должен быть версии 1.13 или более поздней. [Обязательно] |
| Канал Microsoft 365 | Чтобы пользователи взаимодействовали с расширением сообщений из Outlook, необходимо добавить в бот канал Microsoft 365. Дополнительные сведения см. в разделе Добавление канала Microsoft 365. [Обязательно] |
| Время отклика | Время отклика не должно превышать 9 секунд для 99 процентов, 5 секунд для 75 процентов и 2 секунд для 50 процентов. [Обязательно] |
| Надежность | Приложения должны поддерживать доступность 99,9 %. Например, если Microsoft 365 Chat вызывает подключаемый модуль 1000 раз, он должен предоставить значимый ответ 999 раз. [Обязательно] |
| Ноль регрессий | Если необходимо повторно отправить приложение для проверки, существующие функции расширения сообщений, которые работали ранее, не должны прерываться. Это требование применимо только к приложениям независимых поставщиков программного обеспечения (ISV), а не к приложениям, созданным для вашей организации. [Обязательно] |
| Единый вход (SSO) | Если применимо, обновите регистрацию приложения Microsoft Entra ID для единого входа. [Рекомендуется] |
| Политика безопасности содержимого | При необходимости измените заголовки политики безопасности содержимого. [Рекомендуется] |
Важно!
Если применимо, обновите заголовки Политики безопасности содержимого и X-Frame-Options в соответствии с параметром Настройка заголовков политики безопасности содержимого.
Примеры кода
| Название примера | Описание | TypeScript |
|---|---|---|
| Расширение сообщений инвентаризации Northwind | В этом примере показано, как использовать расширение сообщений Teams в качестве подключаемого модуля в Microsoft Copilot для Microsoft 365. | Просмотр |
См. также
Platform Docs
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по