Copilot 移交

项目
10/16/2024

注意

Copilot 移交仅在公共开发人员预览版中可用。
仅在与机器人的一对一聊天中支持 Copilot 切换。

Copilot 移交是插件提供的深层链接，可传递聊天上下文，使用户能够将聊天与智能 Microsoft 365 Copilot 副驾驶®无缝过渡到机器人服务。可以增强 Copilot 消息扩展代理，以便将对话移交给自定义引擎代理，以处理需要专业知识或操作的方案，例如复杂的 IT 支持查询、详细产品查询或交互式订单管理。

在下图中，用户使用智能 Microsoft 365 Copilot 副驾驶®查找有关技术问题的帮助，并从企业数据集接收结果。用户发现可用信息不足，并希望继续与 Contoso 机器人代理交互。当用户选择 Contoso 机器人时，将开始新的聊天，并在 Contoso 机器人中继续对话。这种从智能 Microsoft 365 Copilot 副驾驶®无缝切换到 Contoso 机器人而不丢失对话上下文的这种切换称为副驾驶切换。

图形表示形式显示智能 Microsoft 365 Copilot 副驾驶®与 Contoso 聊天机器人之间的对话切换。

副驾驶交接的工作原理

自定义引擎代理将带有继续标记的深层链接发送到智能 Microsoft 365 Copilot 副驾驶®。具有继续标记的深层链接查询参数可确保引用插件调用参数中的任何信息。当用户选择深层链接时，智能 Microsoft 365 Copilot 副驾驶®使用继续令牌向机器人发送调用，然后机器人根据上下文继续聊天。此过程可实现从智能 Microsoft 365 Copilot 副驾驶®到自定义引擎代理的无缝转换，从而保持对话的连续性和上下文，从而优化用户体验。

必须使用操作按钮的查询参数创建深层链接 URL continuation ，并为参数分配延续令牌，以便促进移交过程。当用户选择操作按钮时，Microsoft Teams 从 URL 读取延续令牌，并启动对机器人的调用。机器人或代理使用继续令牌创建响应，然后在代理聊天窗口中向用户显示该响应。

启用副驾驶移交

若要在 Teams 中启用 copilot 移交，请执行以下步骤：

配置深层链接 URL：创建聊天的深层链接，并将和 continuationToken 添加到28:<botId>深层链接格式。深层链接格式必须为 https://teams.microsoft.com/l/chat/0/0?users=28:${botId}&continuation=${continuationToken}。

示例：

{ 
"type": "Action.OpenUrl", 
"title": "Handoff to Bot", 
"url": "https://teams.microsoft.com/l/chat/0/0?users=28:${botId}&continuation=${continuationToken}" 
}

属性 Action.OpenUrl 允许用户将对话移交给机器人。当用户选择操作按钮时，将激活深层链接，并打开与机器人的新聊天窗口。机器人接收具有有效负载的调用，该有效负载包含 URL 中的继续标记，并使用令牌来维护会话的上下文。

示例有效负载

{ 
 "name": "handoff/action", 
 "type": "invoke", 
 "timestamp": "2024-04-15T19:50:32.945Z", 
 "localTimestamp": "2024-04-15T19:50:32.945Z", 
 "id": "f:00000000-0000-0000-0000-000000000000",
 "channelId": "msteams", 
 "serviceUrl": "https://smba.trafficmanager.net/amer/", 
 "from": { 
     "id": "29:1jzORtjcfpYTLQDR9O4TyLz9LDwHskubQN1Ljc-aFO4L8dnZatjFpSw1PCGa-Mm-Jo4uLp67Lvekcjq2hkPoxdA", 
     "aadObjectId": "00000000-0000-0000-0000-000000000000" 
 }, 
 "conversation": { 
     "conversationType": "personal", 
     "tenantId": "00000000-0000-0000-0000-000000000000",
     "id": "a:13tOiSzRqeub3zaqoTHKpvOkk8Y1zFxk-g8WKdAUM2tjhTBFMt4RSuL8YWi7uwFNBmbxsyzYYktJEyfimYXYiEoplQ34aJs1y8trDb7EIcG09xOjSUieHVzFZ2b8tkagZ" 
 }, 
 "recipient": { 
     "id": "28:00000000-0000-0000-0000-000000000000", 
     "name": "NorthwindProducts" 
 }, 
 "entities": [ 
     { 
         "locale": "en-US", 
         "country": "US", 
         "platform": "Android", 
         "timezone": "America/Chicago", 
         "type": "clientInfo" 
     } 
 ], 
 "channelData": { 
     "tenant": { 
         "id": "00000000-0000-0000-0000-000000000000" 
     }, 
     "source": { 
         "name": "message" 
     }, 
     "legacy": { 
         "replyToId": "1:1_qLAAGcfze29QAWxzicc7gvR3vuNAlKvth08vavxYYs" 
     } 
 }, 
 "replyToId": "1713210583687", 
 "value": { 
     "continuation": "test-continuation-token" 
 }, 
 "locale": "en-US", 
 "localTimezone": "America/Chicago", 
 "rawTimestamp": "2024-04-15T19:50:32.945Z", 
 "rawLocalTimestamp": "2024-04-15T14:50:32.945-05:00", 
 "callerId": "urn:botframework:azure" 
}

调用 handoff/action 类型允许机器人将会话的控制权转移到另一个服务，或启动需要进一步处理的特定操作。当机器人收到 handoff/action 调用活动时，它会使用继续令牌查找任何必要的信息，以便无缝地继续聊天。这包括检索对话历史记录、用户首选项或提供一致体验所需的任何其他上下文。

处理调用类型：在机器人代码中 handoff/action ，使用 onInvokeActivity 处理程序管理调用。必须重写 onInvokeActivity 方法才能处理调用。如果调用成功，机器人必须返回 HTTP 状态代码 200。如果出现错误，机器人必须响应 400 或 500 范围内的相应 HTTP 状态代码。如果用户收到错误，则必须等待，并在后端服务中记录错误时重试。

注意

请勿使用此响应发送任何有效负载，因为它不会在聊天窗口中呈现。基于延续令牌的响应必须单独发送给用户。

下面是如何处理文件中 searchApp.ts 的调用调用的示例：
```
         case "handoff/action": {
           // TODO: Save the continuation token and use it to process final response to user later
          return {status: 200}; // return just the http status
         }
```
当机器人收到调用调用时， context.activity.value.continuation 包含 continuationToken 深层链接 URL 中设置的。如果在移交过程中未安装应用，则会将用户重定向到 Teams 应用商店以安装应用。

最佳做法

在选择操作按钮后，机器人必须在用户被定向到机器人聊天时通知用户，因为没有视觉指示。这有助于管理预期，因为机器人在返回响应之前可能会由于网络延迟和处理时间而延迟。例如，机器人可以发送一系列活动，使用户随时了解进度：

await context.sendActivities([
  {
    type: ActivityTypes.Message,
    text: "Continuing conversation from copilot...",
  },
  { type: ActivityTypes.Typing },
  { type: "delay", value: 1000 },
  {
    type: ActivityTypes.Message,
    text: `Fetching more details using the continuation token passed: ${continuationToken}`,
  },
  { type: ActivityTypes.Typing },
  { type: "delay", value: 4000 },
  {
    type: ActivityTypes.Message,
    text: `Handoff successful!`,
  }
]);

建议管理继续令牌的生命周期，以确保它在合理的时间段后过期，并处理用户重播继续令牌请求的方案。例如，如果出现相同的令牌，请让用户知道他们需要开始与机器人的新对话，因为副驾驶的移交无法继续。

代码示例

示例名称	Description	Node.js
Northwind 清单消息扩展	此示例是充当智能 Microsoft 365 Copilot 副驾驶®代理的 Teams 消息扩展。它具有副驾驶切换功能，使用户能够将其聊天从智能 Microsoft 365 Copilot 副驾驶®转换到 Northwind 数据库。	View

通过

Copilot 移交

副驾驶交接的工作原理

启用副驾驶移交

最佳做法

代码示例

其他资源