【Microsoft Copilot Studio】将copilot 添加到Azure Bot服务通道

重要事项

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

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

您可以将副驾驶连接到现有的Azure Bot Service通道。如果您想将副驾驶连接到Azure Bot Service通道上的最终用户，这可能会很有帮助。

将副驾驶添加到Azure Bot Service渠道需要相当多的开发人员专业知识。本文是为具有开发和编写代码经验的IT管理员或开发人员编写的。

小贴士

您不需要按照此文档将您的Copilot Studio副驾驶添加到您的网站、Facebook或Microsoft Teams。如果你的目标是连接到自定义的基于网络或本地的应用程序，你的开发人员可以在“将副驾驶添加到移动和自定义应用程序”中了解更多信息。

重要事项

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

先决条件

• An Azure Bot Service subscription.
• An Azure Bot Service bot using v4 SDK.
• .NET Core SDK version 2.1.
• Nuget package Microsoft.Bot.Connector.DirectLine.
• A copilot created in Copilot Studio that you want to connect to an Azure Bot Service channel.
• Connect your copilot to mobile and custom apps.

代码示例

本文档中使用的代码片段来自中继机器人示例代码【relay bot sample code.】。

工具书类

本文档中的说明参考了以下内容：

• Deploy your bot to Azure for instructions on deploying the Azure Bot Service bot.
• Azure Bot Service Channels to connect to any Azure Bot Service-supported channel.
• Azure Bot Service debug with the emulator for instructions on debugging the Azure Bot Service bot.

创建或使用现有的Azure Bot Service机器人

您需要一个Azure Bot Service机器人，可以在您的Copilot Studio副驾驶和Azure Bot Service通道之间中继对话。

中继机器人图。

如果您没有现有的Azure bot Service机器人，中继机器人示例代码是一个很好的起点。它是由Microsoft bot Framework机器人示例代码构建的，可以编译并部署到Azure bot Service。示例代码旨在用作起点，而不是直接用于生产。您需要添加代码和优化以满足您的业务需求。

如果你已经有一个Azure Bot Service机器人，你需要添加一个Copilot Studio连接器和代码来管理对话会话。然后，您可以将机器人部署到Azure机器人服务，并使用Azure门户连接到通道。

获取您的Copilot Studio副驾驶参数

要连接到使用copilot Studio构建的副驾驶，您需要检索副驾驶的名称和令牌端点。

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

获取机器人名称。

• 在导航菜单的“设置”下，选择“频道”。
• 选择要连接的频道。此场景使用Slack作为示例。

Slack频道。

• 要复制和保存令牌终结点值，请选择复制。您需要您的端点将副驾驶连接到Azure Bot Service通道。

获取机器人参数。

管理与您的Copilot Studio副驾驶的对话会话

Azure Bot Service通道和与您的Copilot Studio副驾驶的直线连接之间可以进行多次对话。

您的Azure Bot Service机器人需要将对话从Azure Bot Service频道映射并中继到与Copilot Studio副驾驶的直线对话，反之亦然。

示例代码示例

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

• 在每次启动新的外部Azure Bot Service通道对话时，启动Copilot Studio副驾驶对话。有关与机器人开始新对话的说明，请参阅获取直线令牌和使用直线与副驾驶通信。

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 Bot Service通道对话到相应Copilot Studio副驾驶对话的映射。Copilot Studio副驾驶对话可以用两个属性标识和连接：ConversationtId和Token。

C

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

要管理对话生命周期，请刷新Direct Line令牌或清理空闲的对话。在refresh Direct Line令牌中了解有关令牌刷新的更多信息。支持这些功能的Copilot Studio副驾驶对话定义如下：

C#

/// <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_Azur_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 Bot Service通道消息后，从映射表中检索现有对话，将外部对话活动中继到您的Copilot Studio副驾驶，并获得响应。

以下示例显示了通过覆盖ActivityHandler来中继对话。OnMessageActivityAsync（（ITurnContext<IMessageActivity>，CancellationToken）方法

C#

// 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副驾驶的响应时，请参阅从副驾驶解析对话负载，了解如何解析对外部Azure Bot Service通道响应的响应。

响应解析的示例【relay bot sample code】可以在中继机器人示例代码ResponseConverter.cs中找到。

部署到Azure Bot服务

准备好Azure Bot Service中继机器人后，您需要将机器人部署到Azure Bot Service【deploy the bot to your Azure Bot Service.】。

设置Azure Bot服务通道

您可以通过登录Azure门户并选择已部署到的Azure Bot Service资源组来设置要连接的通道。在Azure Bot Service channels【Azure Bot Service Channels.】上查看每个通道的具体说明。