将代理发布到 Azure 机器人服务个频道

项目
12/09/2024

您可以将代理连接到现有的 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 机器人服务机器人

您需要一个 Azure 机器人服务机器人可以在 # Copilot Studio 代理和 Azure 机器人服务频道之间中继对话。

中继机器人图。

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

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

获取 # Copilot Studio 代理参数

要连接您构建的 Copilot Studio 代理，您需要检索代理的名称和令牌终结点。

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

使用 your Copilot Studio # 管理对话会话代理

Azure 机器人服务频道和 Direct Line 与 your Copilot Studio 代理的连接之间可以有多个对话。

您的 Azure 机器人服务机器人需要将对话从 Azure 机器人服务频道映射并中继到 Direct Line 与 Copilot Studio 代理的对话，反之亦然。

示例代码示例

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

在每个新的外部 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 代理对话映射。 A Copilot Studio 代理对话可以用两个属性来标识和连接： ConversationtId and Token。

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

要管理对话生命周期，请刷新 Direct Line 令牌或清理空闲对话。通过刷新 Direct Line 令牌了解有关令牌刷新的详细信息。支持刷新 Copilot Studio 令牌的 A Direct Line 代理对话定义如下：

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

当 new Copilot Studio 代理对话开始时，将键值对（external_Azure_Bot_Service_channel_conversationID， PowerVirtualAgentsConversation）添加到映射表中。

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

要继续现有对话，请在收到新的外部 Azure 机器人服务通道消息后，从映射表中检索现有对话，将外部对话活动中继到 your Copilot Studio 代理，然后获取回复。

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

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

有关如何获取 Direct Line 代理的回复，请参阅用于与代理 Copilot Studio 通信。 Copilot Studio 收到代理的回复后，请参阅解析代理中的对话有效负载了解如何将回复解析到外部 Azure 机器人服务通道回复。

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

部署到 Azure 机器人服务

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

设置 Azure 机器人服务渠道

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

通过