Передача copilot

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

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

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

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

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

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

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

1. Настройка 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 сведений, чтобы продолжить беседу без проблем. Это включает получение журнала бесед, предпочтений пользователей или любого другого контекста, необходимого для обеспечения согласованного взаимодействия.

2. Обработка типа вызова. В коде бота управляйте вызовом handoff/action с помощью обработчика onInvokeActivity . В коде бота управляйте вызовом 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 не может продолжиться.

Примеры кода