【Microsoft Copilot Studio】将copilot 添加到移动或自定义应用程序

重要事项

在对生成式人工智能进行了大量投资并增强了Microsoft Copilot之间的集成后，Power Virtual Agents的功能和特性现在是Microsoft Copiloth Studio的一部分。

在我们更新文档和培训内容时，一些文章和屏幕截图可能会参考Power Virtual Agents。

您可以将副驾驶连接到自定义应用程序，以便该应用程序的用户可以直接从您的应用程序中与副驾驶进行交互。

在大多数情况下，您的自定义应用程序是一个移动设备应用程序，它要么是基于网络的应用程序，要么是本地应用程序，或者是您的业务所需的其他服务的适配器。

连接到您的移动应用程序有不同的程序，具体取决于您的应用程序是基于网络的应用程序还是原生应用程序。

将您的副驾驶连接到基于web的应用程序相对简单，因为它涉及将代码片段复制到您的应用程序中。然而，基于网络的应用程序和原生或自定义应用程序仍然需要相当多的开发人员专业知识才能将副产品完全集成到您的应用程序中。本文介绍了这两种程序。

先决条件

.NET Core SDK version 2.1.

• Nuget package Microsoft.Bot.Connector.DirectLine.
• A copilot created in Copilot Studio that you want to connect to your app.

将副驾驶连接到基于网络的应用程序

1. 在Copilot Studio的导航菜单中的“设置”下，选择“频道”。
2. 选择移动应用程序互动程序以打开配置窗口。
3. 复制基于Web的应用程序部分下的代码，并将其提供给您的应用程序开发人员，以添加到您的基于网络的应用程序中。
4. 

将副驾驶添加到基于web的应用程序中。

将副驾驶连接到本地或自定义应用程序
 

小贴士

虽然本节描述了如何连接到移动应用程序，但同样的过程也可以应用于自定义或本地应用程序，如物联网应用程序。

如果您的目标是连接到Azure Bot Service频道，除了遵循此处的说明外，您的开发人员还可以在将您的机器人连接到Azure Bot Service频道上了解更多信息。

重要事项

本节中的说明要求您或您的开发人员进行软件开发。它适用于经验丰富的It专业人员，如对开发工具、实用程序和IDE有扎实了解的It管理员或开发人员。

代码示例

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

• Connector sample code

工具书类

本文档中的说明参考了以下源材料：

• Bot Framework Direct Line API
• Direct Line Authentication
• Context variables available upon handoff
• Microsoft Bot Framework Activity

检索您的Copilot Studio副驾驶参数

要连接到您构建的副驾驶，您需要检索副驾驶的名称和令牌端点来识别它。

• 在copilot Studio中复制副驾驶的姓名。

获取副驾驶姓名。

• 在导航菜单的“设置”下，选择“频道”。
• 选择移动应用程序。

移动应用频道。

• 在令牌终结点旁边，选择复制。您需要此端点来执行Get Direct Line令牌步骤。

获取副驾驶参数。

获取直线令牌【Direct Line token】

要与副驾驶开始对话，您需要一个直线令牌。此令牌可以通过向Copilot Studio屏幕中指示的端点发出GET请求来获得。然后，此令牌必须用作对directline API的后续调用的头。

例子：

restapi

GET <BOT TOKEN ENDPOINT>

如果请求成功，将返回所请求副驾驶的Direct Line令牌、到期时间和会话ID。例子：

Json

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

示例代码示例

以下示例使用连接器示例代码中的示例来获取Copilot Studio副驾驶的直线令牌。

C#

/// <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;
   }        
}

C

/// <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请求相同。

JSON

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

使用直线[Direct Line]与copilot沟通

检索Direct Line令牌后，您就可以使用Direct Line与您的Copilot Studio副驾驶进行对话了。要开始对话并发送和接收消息，请按照Bot Framework Direct Line API中的说明进行操作。

以下示例使用连接器示例代码中的示例来启动对话，并从Copilot Studio副驾驶发送和接收消息。

• 使用Direct Line令牌初始化DirectLineClient实例并开始对话：

C

// 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;
  }

• 一旦开始，每个对话都可以使用令牌和对话ID的组合进行识别和连接。向现有对话发送用户消息：

C

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

• 使用相同的令牌和会话ID检索副驾驶的响应。检索到的直线响应活动包含用户和副驾驶的消息。您可以根据副驾驶的姓名过滤响应活动，只获取副驾驶的响应消息。

C

// 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 Authentication了解更多信息。

以下示例使用连接器示例代码中的示例来刷新现有Copilot Studio对话的令牌：

C

// 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上了解更多信息。

处理交接活动

如果您的应用程序需要切换到实时代理提供商，您需要处理切换活动。当点击“转移到代理”节点时，会发送切换活动。您可以了解有关切换活动有效载荷的更多信息。

触发欢迎消息

如果你想让你的副驾驶在用户开始对话时自动发送问候系统主题，你可以发送一个类型为event、名称为startConversation的活动。