Добавление помощника Copilot Studio в каналы Службы Azure Bot

Важно

Возможности и функции Power Virtual Agents теперь являются частью Microsoft Copilot Studio после значительных инвестиций в генеративный искусственный интеллект и расширенную интеграцию с Microsoft Copilot.

Некоторые статьи и снимки экрана могут ссылаться на Power Virtual Agents, пока мы обновляем документацию и учебные материалы.

Вы можете подключить свой помощник к существующим каналам службы Azure Bot. Это может быть полезно, если вы хотите подключить свой помощник к конечным пользователям в каналах службы Azure Bot.

Добавление вашего помощника в каналы службы Azure Bot требует значительного опыта разработчиков. Эта статья предназначена для ИТ-администраторов или разработчиков, имеющих опыт разработки и написания кода.

Совет

Вам не нужно следовать этому документу, чтобы добавить свой помощник Copilot Studio на ваш веб-сайт, в Facebook или в Microsoft Teams. Если ваша цель — подключиться к пользовательскому веб-приложению или собственному приложению, разработчики могут узнать больше в разделе Добавление помощника в мобильные и пользовательские приложения.

Важно

Инструкции в этом разделе требуют разработки программного обеспечения от вас или ваших разработчиков. Они предназначены для опытных ИТ-специалистов, таких как ИТ-администраторы или разработчики, которые хорошо разбираются в инструментах разработчика, утилитах и интегрированных средах разработки (IDE).

Предварительные условия

• Подписка на службу Azure Bot.
• Бот службы Azure Bot, использующий SDK версии 4.
• Пакет SDK для .NET Core версии 2.1.
• Пакет Nuget Microsoft.Bot.Connector.DirectLine.
• Помощник, созданный в Copilot Studio, который вы хотите подключить к каналу службы Azure Bot.
• Подключение помощника к мобильным и пользовательским приложениям.

Примеры кода

Фрагменты кода, используемые в этом документе, взяты из примера кода бота-ретранслятора.

Ссылки

Инструкции в этом документе ссылаются на следующее:

• Развертывание бота в Azure содержит инструкции по развертыванию бота службы Azure Bot.
• Каналы службы Azure Bot для подключения к любому каналу, поддерживаемому службой Azure Bot.
• Отладка службы Azure Bot с помощью эмулятора содержит инструкции по отладке бота службы Azure Bot.

Создание или использование существующего бота службы Azure Bot

Вам нужен бот службы Azure Bot, который может передавать разговоры между вашим помощником Copilot Studio и каналами службы Azure Bot.

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

Если у вас уже есть бот службы Azure Bot, вам нужно добавить соединитель Copilot Studio и код для управления сеансами разговора. Затем вы можете развернуть бот в службе Azure Bot и подключиться к каналам с помощью портала Azure.

Получение параметров вашего помощника Copilot Studio

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

1. Скопируйте имя вашего помощника в Copilot Studio.

   

2. В меню навигации в разделе Параметры выберите Каналы.

3. Выберите канал, к которому требуется подключиться. В этом сценарии используется Slack в качестве примера.

   

4. Чтобы скопировать и сохранить значение поля Конечная точка токена, выберите Копировать. Конечная точка вам понадобится, чтобы подключить помощника к каналу службы Azure Bot.

   

Управление сеансами бесед с вашим помощником Copilot Studio

Между каналами службы Azure Bot и подключением Direct Line с вашим помощником Copilot Studio может быть несколько разговоров.

Вашему боту службы Azure Bot потребуется сопоставить и ретранслировать разговор из канала службы Azure Bot в разговор Direct Line с помощником Copilot Studio и наоборот.

Пример образца кода

В следующем примере используются примеры из примера кода бота-ретранслятора.

1. При каждом запуске нового разговора внешнего канала службы Azure Bot начинайте разговор с помощником Copilot Studio. Инструкции по началу нового разговора с ботом см. в темах Получение токена Direct Line и Использование Direct Line для общения с помощником.

   using (var httpRequest = new HttpRequestMessage())
   {   
       httpRequest.Method = HttpMethod.Get;
       UriBuilder uriBuilder = new UriBuilder(TokenEndPoint);
       httpRequest.RequestUri = uriBuilder.Uri;
       using (var response = await s_httpClient.SendAsync(httpRequest))
       {
           var responseString = await response.Content.ReadAsStringAsync();
           string token = SafeJsonConvert.DeserializeObject<DirectLineToken>(responseString).Token;
       }
   }
   
   /// <summary>
   /// class for serialization/deserialization DirectLineToken
   /// </summary>
   public class DirectLineToken
   {
       public string Token { get; set; }
   }
   

    // Use the retrieved token to create a DirectLineClient instance
    using (var directLineClient = new DirectLineClient(token))
    {
        var conversation = await directLineClient.Conversations.StartConversationAsync();
        string conversationtId = conversation.ConversationId;
    }
   

2. Для управления несколькими сеансами необходимо поддерживать сопоставление диалогов внешнего канала службы Azure Bot с соответствующими разговорами с помощниками Copilot Studio. Разговор с помощником Copilot Studio может быть идентифицирован и связан с двумя свойствами: ConversationtId и Token.

   Dictionary<string, PowerVirtualAgentsConversation> ConversationRouter = new Dictionary<string, PowerVirtualAgentsConversation>();  
   

   Чтобы управлять жизненным циклом диалога, обновите токены Direct Line или очистите неиспользуемые разговоры. Узнайте больше об обновлении токена в Обновление токена Direct Line. Разговор с помощником Copilot Studio для их поддержки определяется следующим образом:

   /// <summary>
   /// Data model class for Copilot Studio copilot conversation
   /// </summary>
   public class PowerVirtualAgentsConversation
   {
       public string ConversationtId { get; set; } // The Copilot Studio copilot conversation ID retrieved from step 1
   
       public string Token { get; set; } // The DirectLine token retrieved from step 1
   
       public string WaterMark { get; set; } // Identify turn in a conversation
   
       public DateTime LastTokenRefreshTime { get; set; } = DateTime.Now; // Timestamp of last token refresh
   
       public DateTime LastConversationUpdateTime { get; set; } = DateTime.Now; // Timestamp of last active user message sent to copilot
   }
   

3. Когда начинается новый разговор с помощником Copilot Studio, добавьте пару ключ-значение (external_Azure_Bot_Service_channel_conversationID, PowerVirtualAgentsConversation) в таблицу сопоставления.

   // After new Copilot Studio copilot conversation starts
   ConversationRouter[external_Azure_Bot_Service_channel_conversationID] = new PowerVirtualAgentsConversation()
     {
       Token = token,
       ConversationtId = conversationId,
       WaterMark = null,
       LastConversationUpdateTime = DateTime.Now,
       LastTokenRefreshTime = DateTime.Now,
     }; 
   

4. Чтобы продолжить существующий разговор, после получения нового сообщения внешнего канала службы Azure Bot извлеките существующий разговор из таблицы сопоставления, передайте действие внешнего разговора вашему помощнику Copilot Studio и получите ответ.

   В следующем примере показана передача разговора путем переопределения метода ActivityHandler.OnMessageActivityAsync(ITurnContext<IMessageActivity>, CancellationToken)

   // Invoked when a message activity is received from the user
   // Send the user message to Copilot Studio copilot and get response
   protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
   {
       // Retrieve copilot conversation from mapping table
       // If not exists for the given external conversation ID, start a new Copilot Studio copilot conversation
       ConversationRouter.TryGetValue(externalCID, out PowerVirtualAgentsConversation currentConversation) ?
               currentConversation : /*await StartBotConversationAsync(externalCID)*/;
   
       // Create DirectLine client with the token associated to current conversation
       DirectLineClient client = new DirectLineClient(currentConversation.Token);
   
       // Send user message using directlineClient
       await client.Conversations.PostActivityAsync(currentConversation.ConversationtId, new DirectLineActivity()
       {
         Type = DirectLineActivityTypes.Message,
         From = new ChannelAccount { Id = turnContext.Activity.From.Id, Name = turnContext.Activity.From.Name },
         Text = turnContext.Activity.Text,
         TextFormat = turnContext.Activity.TextFormat,
         Locale = turnContext.Activity.Locale,
       });
   
       // Update LastConversationUpdateTime for session management
       currentConversation.LastConversationUpdateTime = DateTime.Now;
   }  
   

5. См. раздел Использование Direct Line для общения с помощником, чтобы узнать, как заставить помощника Copilot Studio отвечать. Когда ответ помощника Copilot Studio получен, см. раздел Анализ полезной нагрузки разговора из помощника, чтобы узнать о том, как анализировать ответ на ответ внешнего канала службы Azure Bot.

Пример синтаксического анализа ответа можно найти в примере кода бота-ретранслятора ResponseConverter.cs.

Развертывание службы Azure Bot

После того как у вас будет готов бот-ретранслятор службы Azure Bot, вам нужно развернуть бот в службе Azure Bot.

Настройка каналов службы Azure Bot

Вы можете настроить каналы, к которым хотите подключиться, войдя на портал Azure и выбрав группу ресурсов службы Azure Bot, в которой вы выполнили развертывание. Посмотрите конкретные инструкции для каждого канала в разделе Каналы службы Azure Bot.