Поделиться через

Рекомендации по созданию и обновлению агентов

Примечание.

Агенты предоставляют более гибкий, интеллектуальный и готовый к будущему интерфейс, который обеспечивает более широкие возможности для анализа, более простой разработки и лучшее согласование с развивающейся платформой Teams и Microsoft 365. Рекомендуется изучать и создавать агенты.

Дополнительные сведения см. в разделе Создание декларативных агентов и агентов сборки в Teams.

Если у вас есть расширение для сообщений на основе бота, его также можно расширить как агент .

Важно!

  • Агенты для Microsoft 365 Copilot находятся в предварительной версии и работают только в Microsoft 365 Copilot.
  • Агенты расширения сообщений находятся в предварительной версии.
  • Агенты расширений сообщений в Microsoft 365 Copilot доступны в общедоступной предварительной версии для Microsoft Word и PowerPoint.
  • Убедитесь, что Microsoft 365 Copilot доступны для вашей организации. Вы можете получить среду разработчика для Microsoft 365 Copilot двумя способами:
    • Клиент песочницы Microsoft 365 с Microsoft 365 Copilot (доступна в ограниченной предварительной версии через членство в TAP).
    • Корпоративная клиентская рабочая среда с Microsoft 365 Copilot лицензиями. Дополнительные сведения о рекомендациях по проверке для агентов, чтобы увеличить их шансы на получение списка в Team Store, см. в разделе Рекомендации по проверке для агентов.

Агенты Microsoft 365 обеспечивают интеграцию с различными продуктами Microsoft 365, такими как Teams и Outlook. Интеграция помогает пользователям искать или создавать содержимое во внешних системах. Агенты расширения сообщений позволяют Microsoft 365 Copilot взаимодействовать с API из другого программного обеспечения и служб через бота. С помощью Microsoft 365 Copilot вы можете:

  • Поиск последних сведений или записей. Например, последний запрос на инцидент или результаты опроса.
  • Суммирование сведений на основе нескольких записей. Например, сведите все билеты на инциденты, связанные с проектом Northwind.

Рекомендуется создавать или обновлять существующие расширения сообщений, чтобы максимально повысить их полезность и удобство использования в Microsoft 365 Copilot. Расширения сообщений должны поддерживать одну или несколько команд поиска. Поскольку Microsoft 365 Copilot распознает их как навыки, он может выполнять команды от имени пользователя.

На рисунке показан пользовательский интерфейс между Microsoft Teams и Microsoft 365 Copilot.

Определение описаний приложений, команд и параметров

[Необходимо исправить]

Хорошее описание содержит четкое и краткое описание функций приложения и позволяет Microsoft 365 Copilot эффективно обнаруживать и выполнять операции поиска. Когда пользователь вводит имя приложения вместе с командой, например Найти билеты Contoso, агент расширения сообщений должен вызываться из Microsoft 365 Copilot.

Снимок экрана: сценарий прохождения с примером запроса для агента расширения сообщений в Microsoft 365 Copilot.

Снимок экрана: сценарий сбоя без примера запроса на расширение сообщений в качестве агента в Microsoft 365 Copilot.

Описание приложения

Длинные и короткие описания приложений должны быть четкими и определять область приложения. Чтобы отобразить приложение в качестве агента в Microsoft 365 Copilot, измените описание приложения в соответствии со следующими требованиями к агенту:

  • Длинное описание должно четко объяснять функции и использование агента расширения сообщений в Microsoft 365 Copilot. Например, используйте облако Contoso в Microsoft 365 Copilot для поиска и подведения итогов по задачам.
  • Краткое описание должно кратко описывать функциональные возможности приложения на естественном языке и включать имя приложения.

В следующих фрагментах кода показаны краткие примеры описания для каждой категории:

Описание: создание, поиск, просмотр билетов, ошибок и проектов.

Пример описания приложения:

{
  "$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 используется для предоставления подробного описания команды для Microsoft 365 Copilot. Семантическое описание команд поддерживает до 5000 символов и не отображается в пользовательском интерфейсе. semanticDescription Если свойство остается пустым, Microsoft 365 Copilot использует сведения в description поле . При написании semanticDescriptionнеобходимо включить сведения об ожидаемых значениях, ограничениях и диапазонах для команды .

Свойство semanticDescription не является обязательным полем. Однако при добавлении semanticDescription в манифест приложения существующие проверки для кратких, параметров и описаний команд также применимы для семантических описаний.

В следующих фрагментах кода показаны примеры команд и семантического описания для каждой категории:

Описание. Найдите высокоприоритетные задачи, связанные с 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"
          ],

Важно!

Чтобы активировать ссылку для входа OAuth в агенте, убедитесь, что свойству initialRun задано значение true для команд поиска в манифесте приложения.

Описание параметра

Каждая команда расширения сообщений имеет соответствующее parameters свойство, которое поддерживает до пяти параметров. Первый параметр должен быть виден на панели поиска расширения сообщений. Параметр должен иметь хорошее описание, которое должно содержать сочетание допустимых параметров, перечислений, сокращений и формата вывода.

Свойство semanticDescription используется для предоставления подробного описания команды для Microsoft 365 Copilot. Семантическое описание параметров поддерживает до 2000 символов и не отображается в пользовательском интерфейсе. semanticDescription Если свойство остается пустым, Microsoft 365 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"
    }]

Ниже приведены рекомендации, которые можно адаптировать при определении параметров:

  • Параметры должны быть четко определены, чтобы обеспечить точные ответы от агентов. Copilot использует эти описания для выбора лучшей команды и прогнозирования значений параметров на основе пользовательского запроса.
  • Описание параметра не должно содержать грамматические ошибки и ошибки препинания.
  • Параметры, определенные в манифесте, не должны быть идентичными.

Расширение расширения сообщений для получения информации с помощью составных речевых фрагментов

Примечание.

Поиск в диалоговом окне (в TeamsJS версии 1.x называется модулем задач) не поддерживается в Microsoft 365 Copilot.

Для Microsoft 365 Copilot расширение сообщений на основе поиска должно поддерживать более трех уникальных составных речевых фрагментов для глубокого получения точной информации. Чтобы включить составные речевые фрагменты, необходимо развернуть область поиска для обработки трех или более параметров, обновив [манифест приложения (ранее — манифест приложения Teams)]/microsoft-365/extensibility/schema/#composeextensionscommands) и обеспечить следующее:

  • Обновите веб-службу для поддержки поиска на основе нескольких параметров. Дополнительные сведения о том, как реагировать на запросы пользователей, см. в разделе Ответить на команду поиска.

  • Microsoft 365 Copilot может передавать пустую строку или значение NULL для параметров, которые не являются частью пользовательского высказывания. Обновите веб-службу для обработки параметров.

  • Расширение сообщений поддерживает до 10 команд (9 доступных для использования), и каждая команда имеет соответствующее parameters свойство, которое поддерживает до пяти параметров.


Следующий код является примером нескольких параметров, определенных в манифесте приложения: 
"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"
                        }
                    ]
                }
            ]

Снимок экрана: пример сценария прохода, в котором приложение Northwind возвращает ответ для морепродуктов и в параметрах запаса.

Параметры поиска должны иметь хорошее описание с допустимыми параметрами, перечислениями, сокращениями и форматом вывода. Дополнительные сведения и примеры см. в описании параметра.

Определение примеров запросов

[Необходимо исправить]

Свойство samplePrompts помогает пользователям использовать различные агенты в Microsoft 365 Copilot. Microsoft 365 Copilot использует примеры запросов для отображения запросов для пользователя. Запросы должны быть адаптированы к разным языковым стандартом и понятны для разных команд. Примеры запросов доступны для первого запуска (FRE) в Microsoft 365 Copilot, когда пользователь впервые устанавливает или включает агент.

Снимок экрана: примеры запросов, отображаемые при включении агента расширения сообщений в Microsoft 365 Copilot.

Примечание.

  • Если в манифесте приложения не указано samplePrompts свойство, запросы не отображаются.
  • Свойство samplePrompts является обязательным для проверки приложения во время отправки приложения.
  • При определении нескольких команд для приложения пользователю отображается не более трех запросов (по одному из трех первых команд). Запросы сменяются, чтобы предоставить пользователю разнообразный набор запросов в разных командах.

Следующий код является примером свойства в манифесте 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"
     }
    ]
   }
  ]
 }
]

Создание многофункциональных ответов адаптивной карточки

[Необходимо исправить]

Расширения сообщений реагируют на ввод пользователем адаптивной карточки. Адаптивная карточка для агента расширения сообщений должна эффективно функционировать, выглядеть полнофункционалемной и соответствовать следующим требованиям:

  • Ответ адаптивной карточки должен включать содержимое адаптивной карточки и предварительный просмотр карта сведения в рамках одного шаблона. [Необходимо исправить]

    Снимок экрана: пример приложения, на котором показано, Microsoft 365 Copilot ответ приложения содержит предварительный просмотр и содержимое в одном ответе.


    Пример шаблона ответа адаптивной карточки 
    {
    "$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}"
      }
    }
  }

    Примечание.

    Типы imBack действий и messageBack не поддерживаются в объекте данных.

    Рекомендуется использовать следующие типы действий:

    • Action.OpenUrl: открывает указанный URL-адрес из карта.
    • Action.ToggleVisibility: отображает или скрывает один или несколько элементов в карта.
    • Action.Execute: собирает поля ввода и отправляет их в качестве запроса в службу бота.
    • Action.Submit: открывает диалоговое окно или представление стадии с помощью вызова типа в объекте данных.

    На рисунке показан пример кнопок действий

  • Если пользователь может изменить сведения о карта с помощью диалогового окна, stageview или непосредственно из карта, рекомендуется, чтобы адаптивная карточка поддерживала универсальные действия и автоматическое обновление. [Рекомендуется]

  • Адаптивные карточки должны содержать URL-адрес в составе метаданных, что позволяет легко копировать карточки из одного концентратора в другой. [Рекомендуется]

  • Помимо эскизов, любое изображение в адаптивной карточке должно иметь замещающий текст. [Рекомендуется]

Агенты расширения сообщений в приложениях Microsoft 365 Copilot

[Необходимо исправить]

Агенты настраивают и расширяют возможности Microsoft 365 Copilot, предоставляя дополнительные навыки и знания для Microsoft 365 Copilot для персонализированного взаимодействия с пользователем. Используя агенты, которые являются подмножеством агентов, пользователи могут интегрировать дополнительные возможности в Microsoft 365 Copilot, взаимодействуя со сторонними приложениями, как для получения, так и для изменения информации в этих приложениях. Например, агенты расширения сообщений упрощают поиск данных в других приложениях, чтобы Microsoft 365 Copilot могли представить их по запросу при активации агента.

Если вы разработали агент для Microsoft 365 Copilot в Teams или copilot.microsoft.com, вы уже знаете о преимуществах, которые он предлагает пользователям в рамках рабочего процесса.

Примеры кода

Название примера Описание TypeScript
Расширение сообщений инвентаризации Northwind В этом примере реализуется расширение сообщений Teams, которое можно использовать в качестве подключаемого модуля для Microsoft 365 Copilot. Расширение сообщений позволяет пользователям запрашивать базу данных Northwind. Просмотр

См. также

  • Last updated on