将代理发布到移动设备或自定义应用程序

项目
12/09/2024

您可以将代理连接到自定义应用程序，以便该应用程序的用户可以直接从应用程序内与代理交互。

在大多数情况下，自定义应用是基于 Web 的移动设备应用或充当业务需要的其他服务的适配器的移动设备应用。

移动应用的连接过程不同，具体取决于应用是基于 Web 的应用还是本机应用。

将代理连接到基于 Web 的应用程序相对简单，因为它涉及将代码片段复制到应用程序中。但是，基于 Web 的应用程序和原生或自定义应用程序仍然需要大量的开发人员专业知识才能将代理完全集成到您的应用程序中。本文中对这两种过程均有描述。

先决条件

.NET Core SDK 版本 2.1。
Nuget 包 Microsoft.Bot.Connector.DirectLine。
在中创建的代理中， Copilot Studio 您希望将连接到您的应用程序。

连接代理连接到基于 Web 的应用程序

在 Copilot Studio 的导航菜单中，选择渠道。
选择移动应用磁贴打开配置窗口。
复制基于 Web 的应用部分下的代码，然后将其提供给应用开发人员以添加到基于 Web 的应用中。

连接代理到本机或自定义应用程序

小费

虽然本部分介绍的是如何连接到移动应用，也可以将相同流程应用于自定义应用或本机应用，如 IoT（物联网）应用。

如果您的目标是连接 Azure 机器人服务个渠道，除了按照此处的说明操作之外，您的开发人员还可以在发布代理到 Azure 机器人服务渠道中了解更多信息。

重要提示

本部分中的说明要求您或您的开发人员进行软件开发。其面向经验丰富的 IT 专业人士，如深谙开发人员工具、实用程序和 IDE 的 IT 管理员或开发人员。

代码示例

本文中使用的代码段来自：

连接器示例代码

引用

本文档中的说明引用了以下源材料：

检索 # Copilot Studio 代理参数

要连接您构建的代理，您需要检索代理的名称和令牌终结点来识别它。

Copilot Studio在 代理的 Overview（概述 ）页面，然后复制代理的名称。
选择渠道>移动应用程序。
在移动应用程序页面上，在令牌端点旁边，选择复制。获取 Direct Line 令牌步骤中需要此终结点。

获取 Direct Line 令牌

要使用代理开始对话，您需要一个 Direct Line 令牌。可以通过向 Copilot Studio 屏幕中指示的端点发出 GET 请求来获取此令牌。然后，必须将该令牌用作对 directline API 的后续调用的标头。

示例:

GET <BOT TOKEN ENDPOINT>

如果请求成功，将返回 Direct Line 请求的代理的 token、过期时间和 conversationId。示例:

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

示例代码示例

以下示例使用连接器示例代码中的示例来获取 Direct Line a Copilot Studio 代理的令牌。

/// <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 后，您就可以与 your Copilot Studio 代理进行 Direct Line对话了。按照 Bot Framework Direct Line API 中的说明启动对话并收发消息。

以下示例使用连接器示例代码中的示例来启动会话并从 a 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 and conversationId 检索代理的回复。 retrieved Direct Line 回复活动同时包含 user 和代理的消息。您可以按代理的名称筛选回复活动，以仅获取代理的回复消息。

   // 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 有效负载将使用 standard Microsoft Bot Framework Direct Line 活动。可以在 Bot Framework Direct Line API 中了解详细信息。

处理转接活动

如果应用程序需要转接给人工代理提供程序，需要处理转接活动。如果点击“转接到代理”节点，将发送转接活动。可以详细了解转接活动的有效负载。

触发欢迎消息

如果您希望代理在用户开始对话时自动发送 Greeting 系统主题，则可以使用 and Type=event 发送活动 Name=startConversation。

通过