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

Статья
12/26/2024

Вы можете подключить агент к существующим каналам службы 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, вам нужно получить имя вашего агента и конечную точку токена.

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

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

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

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

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

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

При каждом запуске нового разговора внешнего канала службы 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;
 }

Для управления несколькими сеансами необходимо поддерживать сопоставление диалогов внешнего канала службы Azure Bot с соответствующими разговорами агента 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
}
```

Когда начинается новый разговор агента 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,
  };

Чтобы продолжить существующий разговор, после получения нового сообщения внешнего канала службы 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 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;
}

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

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

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

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

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

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

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