Добавление помощника в мобильные и пользовательские приложения

Статья
04/19/2024

Важно

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

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

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

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

Существуют различные процедуры подключения к мобильному приложению в зависимости от того, является ли ваше приложение веб-приложением или собственным приложением.

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

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

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

Подключение помощника к веб-приложению

В меню навигации Copilot Studio в разделе Параметры выберите Каналы.
Выберите плитку Мобильное приложение, чтобы открыть окно конфигурации.
Скопируйте код в разделе Веб-приложения и предоставить его разработчикам вашего приложения для добавления в ваше веб-приложение.

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

Совет

Хотя в этом разделе описывается, как подключить к мобильному приложению, этот же процесс может быть применен для пользовательских или собственных приложений, таких как приложения Интернета вещей (IoT).

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

Внимание

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

Примеры кода

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

Пример кода соединителя

Ссылки

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

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

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

Скопируйте имя вашего помощника в Copilot Studio.
В меню навигации в разделе Параметры выберите Каналы.
Выберите Мобильное приложение.
Рядом с пунктом Конечная точка токена выберите Копировать. Эта конечная точка понадобится вам на шаге Получение токена Direct Line.

Получение токена Direct Line

Чтобы начать разговор с вашим помощником, нужен токен Direct Line. Этот токен можно получить, выполнив запрос GET к конечной точке, указанной на экране Copilot Studio. Затем этот токен необходимо использовать в качестве заголовка для последующих вызовов API Direct Line.

Пример:

GET <BOT TOKEN ENDPOINT>

Если запрос выполнен успешно, будет возвращен токен Direct Line, время окончания срока действия и conversationId для запрошенного помощника. Пример:

{
    "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
    "expires_in": 3600,
    "conversationId": "abc123"
}

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

В следующем примере используются образцы из примера кода соединителя, чтобы получить токен Direct Line для помощника Copilot Studio.

/// <summary>
/// Get directline token for connecting bot
/// </summary>
/// <returns>directline token as string</returns>
public async Task<DirectLineToken> GetTokenAsync(string url)
{
    try
    {
        return await _httpClient.GetFromJsonAsync<DirectLineToken>(url);
    }
    catch (HttpRequestException ex)
    {
        throw ex;
    }        
}

/// <summary>
/// class for serialization/deserialization DirectLineToken
/// </summary>
public class DirectLineToken
{
  public string Token { get; set; }
  public int Expires_in { get; set; }
  public string ConversationId { get; set; }
}

Объект ответа такой же, как и запрос GET, который мы видели ранее.

{
  "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
  "expires_in": 3600,
  "conversationId": "abc123"
}

Использование Direct Line для общения с помощником

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

В следующем примере используются образцы из раздела Пример кода соединителя, чтобы начать разговор и отправлять и получать сообщения от помощника Copilot Studio.

Инициализируйте экземпляр DirectLineClient с помощью токена Direct Line и начните разговор:

   // 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;
   }

После начала каждый разговор может быть идентифицирован и подключен с использованием комбинации параметров token и conversationtId. Отправьте сообщение пользователя в существующий разговор:

   // Use the retrieved token to create a DirectLineClient instance
   // Use the conversationId from above step
   // endConversationMessage is your predefined message indicating that user wants to quit the chat
   while (!string.Equals(inputMessage = /*Get_User_Input()*/, endConversationMessage, StringComparison.OrdinalIgnoreCase))
   {
       using (var directLineClient = new DirectLineClient(token))
       {
           // Send user message using directlineClient
           // Payload is a Microsoft.Bot.Connector.DirectLine.Activity
           await directLineClient.Conversations.PostActivityAsync(conversationtId, new Activity()
           {
               Type = ActivityTypes.Message,
               From = new ChannelAccount { Id = "userId", Name = "userName" },
               Text = inputMessage,
               TextFormat = "plain",
               Locale = "en-Us",
           });
       }
   }

Получите ответ помощника, используя те же значения параметров token и conversationId. Полученные действия ответа Direct Line содержат сообщения как пользователя, так и помощника. Вы можете отфильтровать действия ответа по имени вашего помощника, чтобы получить только ответное сообщение помощника.

   // Use the same token to create a directLineClient
   using (var directLineClient = new DirectLineClient(token))
   {
       // To get the first response set string watermark = null
       // More information about watermark is available at
       // https://learn.microsoft.com/azure/bot-service/rest-api/bot-framework-rest-direct-line-1-1-receive-messages?view=azure-bot-service-4.0

       // response from bot is of type Microsoft.Bot.Connector.DirectLine.ActivitySet
       ActivitySet response = await directLineClient.Conversations.GetActivitiesAsync(conversationtId, watermark);

       // update watermark from response
       watermark = response?.Watermark;

       // response contains set of Activity from both user and bot
       // To display bot response only, filter Activity.From.Name equals to your bot name
       List<Activity> botResponses = response?.Activities?.Where(x =>
                 x.Type == ActivityTypes.Message &&
                   string.Equals(x.From.Name, /*Bot_Name*/, StringComparison.Ordinal)).ToList();

       // Display botResponses
   }

Обновление токена Direct Line

Возможно, вам потребуется добавить код, чтобы обновить токен Direct Line, если ваше приложение имеет длительный разговор с помощником. Срок действия токена истекает, но его можно обновить до истечения срока действия; узнайте больше в теме Проверка подлинности Direct Line.

В следующем примере используются образцы из раздела Пример кода соединителя, чтобы обновить токен для существующего разговора Copilot Studio.

  // DirectLine provides a token refresh method
  // Requires the currentToken valid when refreshing
  string refreshToken = new DirectLineClient(currentToken).Tokens.RefreshToken().Token;
  // create a new directline client with refreshToken
  directLineClient = new DirectLineClient(refreshToken);
  // use new directLineClient to communicate to your bot

Анализ полезной нагрузки разговора от помощника

После начала разговора с помощником полезная нагрузка JSON разговора использует стандартное действие Microsoft Bot Framework Direct Line. Вы можете узнать больше в Bot Framework Direct Line API.

Обработка действия передачи обслуживания

Если ваше приложение должно передать обслуживание поставщику агента-человека, вам нужно обработать передачу обслуживания. Действие передачи отправляется при попадании на узел "Передать агенту". Вы можете узнать больше о полезной нагрузке действия передачи обслуживания.

Запуск приветственного сообщения

Если вы хотите, чтобы ваш помощник автоматически отправлял системную тему приветствия, когда пользователь начинает разговор, вы можете отправить действие с параметрами Type=event и Name=startConversation.