将 Copilot Studio 助手添加到 Azure 机器人服务渠道

项目
04/22/2024

重要提示

继在生成式人工智能的重大投资和跨 Microsoft Copilot 的增强集成之后，Power Virtual Agents 功能和特性现已成为 Microsoft Copilot Studio 的一部分。

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

可以将助手连接到现有 Azure 机器人服务渠道。如果要将助手连接到 Azure 机器人服务渠道中的最终用户，这可能非常有用。

需要相当程度的开发人员专业知识，才能将助手添加到 Azure 机器人服务渠道。本文面向拥有开发和编写代码经验的 IT 管理员或开发人员。

小费

将 Copilot Studio 助手添加到网站、Facebook 或 Microsoft Teams 时，无需遵守本文的说明。如果目标是连接到基于 Web 的自定义应用或本机应用，开发人员可以在向移动应用和自定义应用添加助手中了解详细信息。

重要提示

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

先决条件

Azure 机器人服务订阅。
使用 4 SDK 的 Azure 机器人机器人。
.NET Core SDK 版本 2.1。
Nuget 包 Microsoft.Bot.Connector.DirectLine。
在 Copilot Studio 中创建的要连接到 Azure 机器人服务渠道的助手。
将助手连接到移动应用和自定义应用。

代码示例

本文中使用的代码段来自中继机器人示例代码。

引用

本文档中的说明引用了以下内容：

将机器人部署到 Azure，以获取有关部署 Azure 机器人服务机器人的说明。
Azure 机器人服务渠道，以连接到支持 Azure 机器人服务的渠道。
使用模拟器调试 Azure 机器人服务，以获取有关调试 Azure 机器人服务机器人的说明。

创建或使用现有 Azure 机器人服务机器人

需要可以中继 Copilot Studio 助手与 Azure 机器人服务渠道之间的对话的 Azure 机器人服务机器人。

中继机器人图。

如果还没有 Azure 机器人服务机器人，中继机器人示例代码是很好的起点。其基于可编译并部署到 Azure 机器人服务的 Microsoft Bot Framework 机器人示例代码生成。此示例代码应该用作起点，而不应直接在生产中使用。您将需要添加代码和优化来满足业务要求。

如果已经有 Azure 机器人服务机器人，需要添加 Copilot Studio 连接器和代码以管理对话会话。然后可以将机器人部署到 Azure 机器人服务并通过 Azure 门户连接到渠道。

获取 Copilot Studio 助手参数

若要连接到使用 Copilot Studio 创建的助手，需要检索助手的名称和令牌终结点。

在 Copilot Studio 中复制助手的名称。
在导航菜单中的设置下面，选择渠道。
选择想要连接到的渠道。此场景以 Slack 为例。
若要复制并保存令牌终结点值，请选择复制。您将需要使用终结点以将助手连接到 Azure 机器人服务渠道。

使用 Copilot Studio 助手管理对话会话

Azure 机器人服务渠道和与 Copilot Studio 助手的 Direct Line 连接之间可以有多个对话。

Azure 机器人服务机器人需要将对话从 Azure 机器人服务渠道映射和中继到与 Copilot Studio 助手之间的 Direct Line 对话，反之亦然。

示例代码示例

以下示例使用中继机器人示例代码中的示例。

每个新外部 Azure 机器人服务渠道对话开始时，将启动一个 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 机器人服务渠道对话到相应 Copilot Studio 助手对话的映射。可以通过两个属性识别和连接 Copilot Studio 助手对话：ConversationtId 和 Token。

Dictionary<string, PowerVirtualAgentsConversation> ConversationRouter = new Dictionary<string, PowerVirtualAgentsConversation>();

要管理对话生命周期，请刷新 Direct Line 令牌或清理空闲对话。通过刷新 Direct Line 令牌了解有关令牌刷新的详细信息。下面是用于为这些提供支持的 Copilot Studio 助手对话的定义：

/// <summary>
/// Data model class for Copilot Studio copilot conversation
/// </summary>
public class PowerVirtualAgentsConversation
{
    public string ConversationtId { get; set; } // The Copilot Studio copilot 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 copilot
}

当新的 Copilot Studio 助手对话开始时，将键值对（external_Azure_Bot_Service_channel_conversationID、PowerVirtualAgentsConversation）添加到映射表中。

// After new Copilot Studio copilot conversation starts
ConversationRouter[external_Azure_Bot_Service_channel_conversationID] = new PowerVirtualAgentsConversation()
  {
    Token = token,
    ConversationtId = conversationId,
    WaterMark = null,
    LastConversationUpdateTime = DateTime.Now,
    LastTokenRefreshTime = DateTime.Now,
  };

若要继续现有对话，请在收到新的外部 Azure 机器人服务渠道消息时，从映射表检索现有对话，将外部对话活动中继到您的 Copilot Studio 助手，然后获取响应。

以下示例显示通过覆盖 ActivityHandler.OnMessageActivityAsync((ITurnContext<IMessageActivity>, CancellationToken) 方法中继对话

// Invoked when a message activity is received from the user
// Send the user message to Copilot Studio copilot and get response
protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    // Retrieve copilot conversation from mapping table
    // If not exists for the given external conversation ID, start a new Copilot Studio copilot 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;
}

有关如何获取 Copilot Studio 助手的响应的信息，请参阅使用 Direct Line 与助手通信。收到 Copilot Studio 助手的响应时，请参阅分析助手中的对话有效负载了解如何分析对外部 Azure 机器人服务渠道响应的响应。

可以在中继机器人示例代码 ResponseConverter.cs 中找到响应分析的示例。

部署到 Azure 机器人服务

准备好 Azure 机器人服务中继机器人之后，需要将机器人部署到 Azure 机器人服务。

设置 Azure 机器人服务渠道

可以设置要连接到的渠道，方法是登录 Azure 门户，然后选择已部署到的 Azure 机器人服务资源组。在 Azure 机器人服务渠道中查看各渠道的特定说明。

通过