Передача copilot

Статья
09/16/2024

Примечание.

Передача Copilot доступна только в общедоступной предварительной версии для разработчиков.
Передача Copilot поддерживается только в одном чате с ботом.

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

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

Графическое представление показывает передачу диалога между Microsoft 365 Copilot и чат-ботом Contoso.

Как работает передача copilot

Агент пользовательского обработчика отправляет прямую ссылку с маркером продолжения в Microsoft 365 Copilot. Параметр запроса deep link с маркером продолжения гарантирует, что все сведения из параметров вызова подключаемого модуля будут указываться. Когда пользователь выбирает прямую ссылку, Microsoft 365 Copilot отправляет вызов боту с маркером продолжения, а затем бот возобновляет беседу на основе контекста. Этот процесс обеспечивает простой переход от Microsoft 365 Copilot к пользовательскому агенту обработчика, поддерживая непрерывность и контекст беседы, что оптимизирует взаимодействие с пользователем.

Необходимо создать URL-адрес прямой ссылки с параметром continuation запроса для кнопки действия и назначить параметру маркер продолжения, чтобы упростить процесс передачи. Когда пользователь нажимает кнопку действия, Microsoft Teams считывает маркер продолжения из URL-адреса и инициирует вызов бота. Бот или агент использует маркер продолжения для создания ответа, который затем отображается пользователю в окне чата агента.

Включение передачи copilot

Чтобы включить передачу copilot в Teams, выполните следующие действия.

Настройка URL-адреса прямой ссылки. Создайте прямую ссылку на чат и добавьте 28:<botId> и continuationToken в формат прямой ссылки. Формат глубокой ссылки должен иметь значение https://teams.microsoft.com/l/chat/0/0?users=28:${botId}&continuation=${continuationToken}.

Пример.
```
{ 
"type": "Action.OpenUrl", 
"title": "Handoff to Bot", 
"url": "https://teams.microsoft.com/l/chat/0/0?users=28:${botId}&continuation=${continuationToken}" 
}
```
Свойство Action.OpenUrl позволяет пользователю передать беседу боту. Когда пользователь нажимает кнопку действия, активируется прямая ссылка и открывается новое окно чата с ботом. Бот получает вызов вызова с полезными данными, которые содержат маркер продолжения из URL-адреса и используют маркер для поддержания контекста беседы.

Пример полезных данных
```
{ 
 "name": "handoff/action", 
 "type": "invoke", 
 "timestamp": "2024-04-15T19:50:32.945Z", 
 "localTimestamp": "2024-04-15T19:50:32.945Z", 
 "id": "f:00000000-0000-0000-0000-000000000000",
 "channelId": "msteams", 
 "serviceUrl": "https://smba.trafficmanager.net/amer/", 
 "from": { 
     "id": "29:1jzORtjcfpYTLQDR9O4TyLz9LDwHskubQN1Ljc-aFO4L8dnZatjFpSw1PCGa-Mm-Jo4uLp67Lvekcjq2hkPoxdA", 
     "aadObjectId": "00000000-0000-0000-0000-000000000000" 
 }, 
 "conversation": { 
     "conversationType": "personal", 
     "tenantId": "00000000-0000-0000-0000-000000000000",
     "id": "a:13tOiSzRqeub3zaqoTHKpvOkk8Y1zFxk-g8WKdAUM2tjhTBFMt4RSuL8YWi7uwFNBmbxsyzYYktJEyfimYXYiEoplQ34aJs1y8trDb7EIcG09xOjSUieHVzFZ2b8tkagZ" 
 }, 
 "recipient": { 
     "id": "28:00000000-0000-0000-0000-000000000000", 
     "name": "NorthwindProducts" 
 }, 
 "entities": [ 
     { 
         "locale": "en-US", 
         "country": "US", 
         "platform": "Android", 
         "timezone": "America/Chicago", 
         "type": "clientInfo" 
     } 
 ], 
 "channelData": { 
     "tenant": { 
         "id": "00000000-0000-0000-0000-000000000000" 
     }, 
     "source": { 
         "name": "message" 
     }, 
     "legacy": { 
         "replyToId": "1:1_qLAAGcfze29QAWxzicc7gvR3vuNAlKvth08vavxYYs" 
     } 
 }, 
 "replyToId": "1713210583687", 
 "value": { 
     "continuation": "test-continuation-token" 
 }, 
 "locale": "en-US", 
 "localTimezone": "America/Chicago", 
 "rawTimestamp": "2024-04-15T19:50:32.945Z", 
 "rawLocalTimestamp": "2024-04-15T14:50:32.945-05:00", 
 "callerId": "urn:botframework:azure" 
}
```
Тип handoff/action вызова позволяет боту передавать управление беседой другой службе или инициировать определенное действие, требующее дальнейшей обработки. Когда бот получает действие вызова, он использует маркер продолжения для поиска всех необходимых handoff/action сведений, чтобы продолжить беседу без проблем. Это включает получение журнала бесед, предпочтений пользователей или любого другого контекста, необходимого для обеспечения согласованного взаимодействия.
Обработка типа вызова. В коде бота управляйте вызовом handoff/action с помощью обработчика onInvokeActivity . Необходимо переопределить метод для onInvokeActivity обработки вызова вызова. Если вызов выполнен успешно, бот должен вернуть код состояния HTTP 200. При возникновении ошибки бот должен ответить соответствующим кодом состояния HTTP в диапазоне 400 или 500. Если пользователь получает сообщение об ошибке, он должен подождать и повторить попытку, пока ошибки регистрируются в серверной службе.

Примечание.

Не отправляйте полезные данные с этим ответом, так как он не отображается в окне чата. Ответы, основанные на маркере продолжения, должны отправляться пользователю отдельно.

Ниже приведен пример обработки вызова вызова в searchApp.ts файле:
```
         case "handoff/action": {
           // TODO: Save the continuation token and use it to process final response to user later
          return {status: 200}; // return just the http status
         }
```
Когда бот получает вызов вызова, содержит объект , context.activity.value.continuation заданный continuationToken в URL-адресе прямой ссылки. Если приложение не установлено во время передачи, пользователь перенаправляется в Магазин Teams для установки приложения.

Лучшие методики

Бот должен уведомлять пользователей о том, что они направляются в чат бота после нажатия кнопки действия, так как визуальные признаки отсутствуют. Это помогает управлять ожиданиями, так как может возникнуть задержка, прежде чем бот вернет ответ из-за задержки сети и времени обработки. Например, бот может отправить ряд действий, чтобы информировать пользователя о ходе выполнения:
```
await context.sendActivities([
  {
    type: ActivityTypes.Message,
    text: "Continuing conversation from copilot...",
  },
  { type: ActivityTypes.Typing },
  { type: "delay", value: 1000 },
  {
    type: ActivityTypes.Message,
    text: `Fetching more details using the continuation token passed: ${continuationToken}`,
  },
  { type: ActivityTypes.Typing },
  { type: "delay", value: 4000 },
  {
    type: ActivityTypes.Message,
    text: `Handoff successful!`,
  }
]);
```
Мы рекомендуем управлять жизненным циклом маркера продолжения, чтобы гарантировать его истечение по истечении разумного периода времени, и обрабатывать сценарии, в которых пользователь воспроизводит запрос на маркер продолжения. Например, если появится тот же маркер, сообщите пользователю, что он должен начать новую беседу с ботом, так как передача из copilot не может продолжиться.

Примеры кода

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

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

Передача copilot

Как работает передача copilot

Включение передачи copilot

Лучшие методики

Примеры кода

Дополнительные ресурсы