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

Статья
12/09/2024

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

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

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

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

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

Пакет 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 Пример:

{
    "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",
           });
       }
   }

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

   // 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.

Поделиться через