发布代理到 Azure 机器人服务渠道

项目
12/31/2024

您可以将代理连接到现有的 Azure Bot Service 渠道，如果您想将代理连接到 Azure Bot Service 渠道上的客户，这会很有帮助。

需要相当程度的开发人员专业知识，才能将代理添加到 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 令牌了解有关令牌刷新的详细信息。支持刷新 Direct Line 令牌的 Copilot Studio 代理对话的定义如下所示：

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

当新的 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 机器人服务渠道消息时，从映射表检索现有对话，将外部对话活动中继到您的 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;
}

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

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

部署到 Azure 机器人服务

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

设置 Azure 机器人服务渠道

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

通过