將副手新增至行動應用程式或自訂應用程式

文章
04/22/2024

重要

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

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

您可以將副手連接至自訂應用程式，以便應用程式的使用者可以直接從您的應用程式中與副手互動。

在大部分的案例中，您的自訂應用程式將是行動裝置應用程式，它是 Web 應用程式，或是原生應用程式或您業務所需其他服務的配接器。

根據您的應用程式是 Web 應用程式或原生應用程式，有不同的程序可連接至行動裝置應用程式。

將副手連接至 Web 應用程式相對簡單，因為它涉及將程式碼片段複製到您的應用程式中。但是，Web 應用程式和原生或自訂應用程式仍然需要大量的開發人員專業知識，才能將副手完全整合到您的應用程式中。本文將說明這兩個程序。

先決條件

.NET Core SDK 版本 2.1。
Nuget 套件 Microsoft.Bot.Connector.DirectLine。
在 Copilot Studio 中建立的用來連接至應用程式的副手。

將副手連接至 Web 應用程式

在 Copilot Studio 導覽功能表的設定底下，選取管道。
選取行動裝置應用程式圖標以開啟設定視窗。
在 Web 應用程式區段中複製程式碼，並將它提供給您的應用程式開發人員，以新增至您的 Web 應用程式。

將您的副手連接至原生或自訂應用程式

提示

雖然本節描述如何連接至行動裝置應用程式，但是相同的程序可以應用於自訂或原生應用程式，例如 IoT (物聯網) 應用程式。

如果您的目標是連接至 Azure Bot Service 管道，除了遵循此指示之外，您的開發人員可以在將您的機器人連接至 Azure Bot Service 管道深入了解詳細資訊。

重要

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

程式碼範例

本文件所用的程式碼片段來自：

連接器範例程式碼

擷取您的 Copilot Studio 副手參數

若要連接至您建置的副手，您必須擷取副手名稱和權杖端點以進行識別。

在 Copilot Studio 中複製您的副手名稱。
在導覽功能表的設定底下，選取管道。
選取行動裝置應用程式。
在權杖端點旁邊，選取複製。在取得 Direct Line 權杖的步驟中，您會需要此端點。

取得 Direct Line權杖

若要開始與您的副手交談，您需要有一個 Direct Line 權杖。可以透過向 Copilot Studio 畫面中指示的端點發出 GET 要求來取得此權杖。然後必須將該權杖用作後續呼叫 directline API 的標題。

範例:

GET <BOT TOKEN ENDPOINT>

如果要求成功，將傳回 Direct Line 權杖、逾期時間和所要求副手的 conversationId。範例:

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

範例程式碼

下列範例使用連接器程式碼範例的範例來取得 Copilot Studio 副手的 Direct Line 權杖。

/// <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 權杖之後，您就可以使用 Direct Line 與 Copilot Studio 副手進行交談。要開始進行交談並傳送和接收訊息，請依照 Bot Framework Direct Line API 的指示進行。

下列範例使用連接器範例程式碼中的範例來開始交談，並從 Copilot Studio 副手傳送和接收訊息。

使用 Direct Line 權杖初始化 DirectLineClient 執行個體，並開始交談：

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

使用相同的 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 承載會使用標準 Microsoft Bot Framework Direct Line 活動。您可以在 Bot Framework Direct Line API 中學到更多內容。

處理移交活動

如果您的應用程式需要移交給真人專員提供者，您需要處理該移交活動。當點擊 [轉接專員] 節點時，會傳送移交活動。您可以深入了解移交活動的承載。

觸發歡迎訊息

如果您要讓副手在使用者開始交談時自動傳送問候系統主題，您可以使用 Type=event 和 Name=startConversation 來傳送活動。

分享方式：