將代理程式發佈到 Azure Bot Service 通道

發行項
12/31/2024

您可以將代理程式連接到現有的 Azure 機器人服務管道，如果您希望將代理程式連接到 Azure 機器人服務管道上的客戶，這會很有幫助。

將代理程式新增至 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 機器人服務通道。

管理與您的 Copilot Studio 代理程式的交談工作階段

透過您的 Copilot Studio 代理程式，Azure Bot Service 管道與 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 權杖。支援重新整理 Direct Line 權杖的 Copilot Studio 代理程式工作階段定義如下：

/// <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 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 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 Service 管道回覆。

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

部署至 Azure Bot Service

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

設定 Azure Bot Service 管道

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

共用方式為