发布智能体到移动或自定义应用

2025-07-01

您可以将智能体连接到自定义应用程序，这样应用程序的用户就可以直接在您的应用程序中与智能体进行交互。

在大多数情况下，自定义应用是基于 Web 的移动设备应用或充当业务需要的其他服务的适配器的移动设备应用。

移动应用的连接过程不同，具体取决于应用是基于 Web 的应用还是本机应用。

将智能体连接到基于 Web 的应用相对简单，因为涉及将代码段复制到应用中。但是，基于 Web 的应用和本机或自定义应用仍然都需要相当丰富的开发人员专业知识，才能将智能体完全集成到应用中。本文中对这两种过程均有描述。

先决条件

.NET Core SDK 版本 2.1。
Nuget 包 Microsoft.Bot.Connector.DirectLine。
在 Copilot Studio 中创建的智能体，您希望将其连接到您的应用。

将智能体连接到基于 Web 的应用程序

在 Copilot Studio 的导航菜单中，选择渠道。
选择移动应用磁贴打开配置窗口。
复制基于 Web 的应用部分下的代码，然后将其提供给应用开发人员以添加到基于 Web 的应用中。

将智能体连接到本地应用程序或自定义应用程序

小费

虽然本部分介绍的是如何连接到移动应用，也可以将相同流程应用于自定义应用或本机应用，如 IoT（物联网）应用。

如果您的目标是连接到 Azure 机器人服务渠道，开发人员除了遵守此处的说明，还可以在将智能体发布到 Azure 机器人服务渠道中了解更多信息。

重要提示

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

引用

本文档中的说明引用了以下源材料：

检索 Copilot Studio 智能体参数

要连接到您构建的智能体，您需要检索智能体的名称和令牌终结点以进行识别。

在 Copilot Studio 中，导航至智能体的概述页面，并复制智能体名称。
选择渠道>移动应用。
在移动应用程序页面上，在令牌端点旁边，选择复制。获取 Direct Line 令牌步骤需要此终结点。

获取 Direct Line 令牌

要启动与智能体之间的对话，需要 Direct Line 令牌。可以通过向 Copilot Studio 屏幕中指示的终结点发出 GET 请求来获取此令牌。然后，必须将该令牌用作对 directline API 的后续调用的标头。

示例:

GET <BOT TOKEN ENDPOINT>

如果请求成功，将返回 Direct Line 令牌、过期时间和所请求智能体的 conversationId。

示例:

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

获取 Direct Line 令牌代码示例

以下示例为 Copilot Studio 智能体获取 Direct Line 令牌。

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

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

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

使用 Direct Line 与智能体通信

检索 Direct Line 令牌之后，就可以通过 Direct Line 与 Copilot Studio 智能体对话。要开始对话和收发消息，请按照 Bot Framework Direct Line API 中的说明操作。

以下示例启动对话并从 Copilot Studio 代理发送和接收消息。

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

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

启动后，可以使用 token 和 conversationtId 的组合识别和连接每个对话。向现有对话发送用户消息：

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

使用相同 token 和 conversationId 检索智能体的回复。检索到的 Direct Line 响应活动中同时包含用户的消息和智能体的消息。可以按智能体的名称筛选响应活动以仅获取智能体的响应消息。

   // 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 令牌。令牌会到期，但是可以在到期前刷新；可在 Direct Line 身份验证中了解详细信息。

以下示例刷新现有 Copilot Studio 对话的令牌：

  // 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 活动。可以在机器人框架 Direct Line API 中了解详细信息。

处理转接活动

如果应用程序需要转接给人工代理提供程序，需要处理转接活动。如果点击“转接到代理”节点，将发送转接活动。可以详细了解转接活动的有效负载。

触发欢迎消息

如果要让智能体在用户启动对话时自动发送问候系统主题，您可以发送 Type=event 和 Name=startConversation 的活动。