將 Copilot Studio 副手新增至 Azure Bot Service 管道

文章
04/22/2024

重要

在對生成式 AI 進行大量投資並增強 Microsoft Copilot 的整合後，Power Virtual Agents 的功能和特性現已成為 Microsoft Copilot Studio 的一部分。

當我們更新文件和培訓內容時，某些文章和螢幕擷取畫面可能會參考 Power Virtual Agents。

您可以將副手連接至現有的 Azure Bot Service 管道。若要將您的副手連接至 Azure Bot Service 管道上的使用者，這將會很有用。

將副手新增至 Azure Bot Service 管道需要大量的開發人員專業知識。本文是為具備開發和撰寫程式碼的 IT 系統管理員或開發人員所撰寫。

提示

您不需要依照此文件，將您的 Copilot Studio 副手新增至您的網站、Facebook 或 Microsoft Teams。如果您的目標是連接至自訂的 Web 或原生應用程式，則您的開發人員可以在將副手新增至行動和自訂應用程式中學到更多內容。

重要

本節中的指示需要由您或您的開發人員進行軟體開發。它適用於有經驗的 IT 專業人員，例如 IT 系統管理員或開發人員，他們深刻了解開發人員工具、公用程式及 IDE。

先決條件

Azure Bot Service 訂閱。
使用 v4 SDK 的 Azure Bot Service 機器人。
.NET Core SDK 版本 2.1。
Nuget 套件 Microsoft.Bot.Connector.DirectLine。
在 Copilot Studio 中建立的用來連接至 Azure Bot Service 管道的副手。
將您的副手連接到行動應用程式和自訂應用程式。

程式碼範例

本文所用的程式碼片段來自於中繼機器人範例程式碼。

建立或使用現有的 Azure Bot Service 機器人

您需要可在您的 Copilot Studio 副手和 Azure Bot Service 管道之間中繼交談的 Azure Bot Service 機器人。

中繼機器人圖解。

如果您不具備現有的 Azure Bot Service 機器人，中繼機器人範例程式碼是一個好起點。它是由 Microsoft Bot Framework 機器人範例程式碼所建置，可以編譯並部署至 Azure Bot Service。範例程式碼是用做為起始點，而不是要直接用於生產中。您必須新增程式碼和最佳化，才能符合您的業務需求。

如果您已經有 Azure Bot Service 機器人，則需要新增 Copilot Studio 連接器和程式碼，才能管理交談工作階段。然後，您可以將機器人部署至 Azure Bot Service，並使用 Azure 入口網站連接至管道。

取得您的 Copilot Studio 副手參數

若要連接至您使用 Copilot Studio 建置的副手，您必須擷取您的副手名稱和權杖端點。

在 Copilot Studio 中複製您的副手名稱。
在導覽功能表的設定底下，選取管道。
選取您要連接的管道。此案例使用 Slack 做為範例。
若要複製並儲存權杖端點值，請選取複製。需要端點才能將副手連接到 Azure Bot Service 管道。

使用您的 Copilot Studio 副手管理交談工作階段

Azure Bot Service 管道與 Copilot Studio 副手的 Direct Line 連線之間可以存在多個交談。

您的 Azure Bot Service 機器人必須透過 Copilot Studio 副手將交談從 Azure Bot Service 管道對應並轉送至 Direct Line 交談，反之亦然。

範例程式碼

下列範例使用中繼機器人範例程式碼中的範例。

在每個新的外部 Azure Bot Service 管道交談開始時，開始 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 Service 管道交談至相應 Copilot Studio 副手交談的對應。您可以使用兩個屬性來識別和連接 Copilot Studio 副手交談：ConversationtId 與 Token。

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

若要管理交談生命週期，請重新整理 Direct Line 權杖或清除已閒置交談。如需深入了解權仗重新整理的資訊，請移至重新整理 Direct Line 權杖。支援這些功能的 Copilot Studio 副手交談定義如下：

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

開始新的 Copilot Studio 副手交談時，請將索引鍵/值組 (external_Azure_Bot_Service_channel_conversationID、PowerVirtualAgentsConversation) 新增至對應資料表。

// After new Copilot Studio copilot 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 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 copilot and get response
protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    // Retrieve copilot conversation from mapping table
    // If not exists for the given external conversation ID, start a new Copilot Studio copilot 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 Service 管道回覆。

您可以在中繼機器人範例程式碼 ResponseConverter.cs 中找到回覆剖析範例。

部署至 Azure Bot Service

在您將 Azure Bot Service 中繼機器人準備好之後，您需要將機器人部署到 Azure Bot Service。

設定 Azure Bot Service 管道

您可以透過登入 Azure 入口網站並選取您部署到的 Azure Bot Service 資源群組，來設定想要連接的管道。查看 Azure Bot Service 管道上每個管道的特定指示。