Публикация агента в мобильных или пользовательских приложениях

Note

Функции, описанные в этой статье, питаются стандартным жгутом, который использует опции выставления счетов, описанные в разделе «Лицензирование для агентов, работающих на стандартном жгуте». Узнайте, как получить доступ к стандартным функциям в стандартных агентах и потоках агентов доступа.

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

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

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

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

Необходимые условия

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

  1. В Copilot Studio в меню навигации выберите Каналы.

  2. Выберите плитку Мобильное приложение, чтобы открыть окно конфигурации.

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

    Добавьте агент в веб-приложение.

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

Tip

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

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

Important

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

Ссылки

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

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

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

  1. В Copilot Studio перейдите на страницу обзора вашего агента и скопируйте его имя.

  2. Выберите Каналы>Мобильное приложение.

  3. На странице Мобильное приложение рядом с пунктом Конечная точка токена выберите Копировать. Вам понадобится эта конечная точка для этапа Получение токена Direct Line.

    Получите параметры агента.

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

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

Пример:

GET <BOT TOKEN ENDPOINT>

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

Пример:

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

Пример кода для получения токена Direct Line

В следующем примере демонстрируется получение токена 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. Чтобы начать разговор и отправлять и получать сообщения, следуйте инструкциям в разделе API-интерфейс Direct Line платформы Bot Framework.

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

  1. Инициализируйте экземпляр 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;
   }

  2. После начала вы можете идентифицировать каждый разговор и подключиться к нему, используя комбинацию параметров 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",
           });
       }
   }

  3. Получите ответ агента при помощи тех же значений параметров 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 для разговора использует стандартное действие Direct Line платформы Microsoft Bot Framework. Чтобы узнать больше, см. статью API-интерфейс Direct Line платформы Bot Framework.

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

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

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

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

  • Last updated on