將 Agent 發佈到行動裝置或自訂應用程式

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

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

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

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

必要條件

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

將 Agent 連接至 Web 應用程式

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

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

提示

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

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

重要

本節中的指示需要由您或您的開發人員進行軟體開發。這些指示假設具備適合資深 IT 專業人員的專業程度，例如對開發工具、實用程式及整合開發人員環境 (IDE) 有扎實了解的 IT 管理員或開發人員。

擷取 Copilot Studio Agent 參數

若要連接到您組建的 Agent，需要檢索 Agent 的名稱和權杖端點以識別它。

在 Copilot Studio 中，瀏覽至 Agent 的概觀頁面，並複製 Agent 的名稱。
選取管道>行動應用程式。
在行動應用程式頁面上，選擇權杖端點旁的複製。取得 Direct Line 權杖步驟需要此端點。

取得 Direct Line 權杖

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

範例:

GET <BOT TOKEN ENDPOINT>

如果請求成功，終端節點將返回所請求 Agent 的 Direct Line 權杖、過期時間和 conversationId。

範例:

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

取得 Direct Line 權杖程式碼範例

下列範例可取得 Copilot Studio Agent 的 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 與 Agent 通訊

擷取 Direct Line 權杖之後，就可以開始使用 Direct Line 與 Copilot Studio Agent 進行交談。若要開始交談並傳送和接收訊息，請遵循 Bot Framework Direct Line API 的指示。

以下範例是從 Copilot Studio Agent 發起對話並發送與接收訊息。

使用 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，擷取 Agent 的回覆。擷取的 Direct Line 回應活動包含使用者和 Agent 的訊息。您可以依據 Agent 的名稱來篩選回覆活動，以只取 Agent 的回覆訊息。

   // 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 權杖

如果應用程式與 Agent 之間的交談很冗長，您可能需要新增程式碼以重新整理 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

從 Agent 剖析交談承載

開始與 Agent 進行交談之後，交談 JSON 承載會使用標準 Microsoft Bot Framework Direct Line 活動。您可以在 Bot Framework Direct Line API 中了解更多資訊。

處理移交活動

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

觸發歡迎訊息

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

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-12-17