Публикация агента в каналах Службы Azure Bot

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

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

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

• Подписка на службу Azure Bot.
• Бот службы Azure Bot, использующий SDK версии 4.
• .NET SDK версии 10.0.
• Пакет 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 sample code который можно скомпилировать и развернуть на Azure Bot Service. Используйте пример кода как отправную точку. Пример кода не предназначен для использования в производстве. Вам нужно добавить код и оптимизацию, чтобы соответствовать потребностям вашего бизнеса.

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

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

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

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

   

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

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

   

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

   

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

Между Azure Bot Service каналами и 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 Service каналов разговоров с соответствующими Copilot Studio разговорами агентов. Свяжите разговор с агентом Copilot Studio, используя два свойства: ConversationtId и Token.

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

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

   /// <summary>
   /// Data model class for Copilot Studio agent conversation
   /// </summary>
   public class PowerVirtualAgentsConversation
   {
       public string ConversationtId { get; set; } // The Copilot Studio agent 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 agent
   }
   

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

   // After new Copilot Studio agent 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 Service канала. Передайте информацию о внешней беседе вашему агенту Copilot Studio и получите ответ.

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

   // Invoked when a message activity is received from the user
   // Send the user message to Copilot Studio agent and get response
   protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
   {
       // Retrieve agent conversation from mapping table
       // If not exists for the given external conversation ID, start a new Copilot Studio agent 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, обратитесь к Parse conversationload от агента чтобы узнать, как разобрать ответ на ответ внешнего Azure Bot Service канала.

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

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

После создания Azure Bot Service-релейного бота развернуть бота на Azure Bot Service.

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

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