Copilot ハンドオフ

[アーティクル]
10/16/2024

注:

Copilot ハンドオフは、パブリック開発者プレビューでのみ使用できます。
Copilot ハンドオフは、ボットとの 1 対 1 のチャットでのみサポートされます。

Copilot ハンドオフは、チャットコンテキストを引き継ぐプラグインによって提供されるディープリンクであり、ユーザーはMicrosoft 365 Copilotを使用してチャットをボットサービスにシームレスに移行できます。複雑な IT サポートクエリ、詳細な製品の問い合わせ、対話型の注文管理など、専門的な知識やアクションが必要なシナリオを処理するために、Copilot メッセージ拡張エージェントを拡張してカスタムエンジンエージェントに会話を渡すことができます。

次の図では、ユーザーは、Microsoft 365 Copilotを使用して技術の問題に関するヘルプを検索し、エンタープライズデータセットから結果を受け取ります。ユーザーは、使用可能な情報が不十分であると検出し、Contoso ボットエージェントとの対話を続行したいと考えています。ユーザーが Contoso ボットを選択すると、新しいチャットが開始され、Contoso ボットで会話が続行されます。会話コンテキストを失うことなく、Microsoft 365 Copilotから Contoso ボットへのこのシームレスな切り替えは、copilot ハンドオフと呼ばれます。

グラフィカルな表現は、Microsoft 365 Copilotと Contoso チャットボットの間の会話のハンドオフを示しています。

copilot ハンドオフのしくみ

カスタムエンジンエージェントは、継続トークンを含むディープリンクをMicrosoft 365 Copilotに送信します。継続トークンを持つディープリンククエリパラメーターを使用すると、プラグイン呼び出しパラメーターからの情報が確実に参照されます。ユーザーがディープリンクを選択すると、Microsoft 365 Copilotは継続トークンを使用してボットに呼び出し呼び出しを送信し、ボットはコンテキストに基づいて会話を再開します。このプロセスにより、Microsoft 365 Copilotからカスタムエンジンエージェントへのシームレスな移行が可能になり、会話の継続性とコンテキストが維持され、ユーザーエクスペリエンスが最適化されます。

アクションボタンの continuation クエリパラメーターを含むディープリンク URL を作成し、引き継ぎ処理を容易にするために継続トークンをパラメーターに割り当てる必要があります。ユーザーがアクションボタンを選択すると、Microsoft Teamsは URL から継続トークンを読み取り、ボットへの呼び出し呼び出しを開始します。ボットまたはエージェントは継続トークンを使用して応答を作成し、エージェントチャットウィンドウにユーザーに表示されます。

copilot ハンドオフを有効にする

Teams で copilot ハンドオフを有効にするには、次の手順に従います。

ディープリンク URL の構成: チャットへのディープリンクを作成し、ディープリンク形式に 28:<botId> と continuationToken を追加します。ディープリンク形式は 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 呼び出しアクティビティを受け取ると、継続トークンを使用して、会話をシームレスに続行するために必要な情報を検索します。これには、会話履歴、ユーザー設定、または一貫性のあるエクスペリエンスを提供するために必要なその他のコンテキストの取得が含まれます。

呼び出しの種類を処理する: ボットコードで、onInvokeActivity ハンドラーを使用して呼び出handoff/actionを管理します。呼び出しを処理するには、 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 にはディープリンク URL に設定された continuationToken が含まれます。ハンドオフ中にアプリがインストールされていない場合、ユーザーは 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!`,
  }
]);
```
継続トークンのライフサイクルを管理して、妥当な期間が経過した後に期限切れになるようにし、ユーザーが継続トークンの要求を再生するシナリオを処理することをお勧めします。たとえば、同じトークンが表示された場合は、copilot からのハンドオフを続行できないため、ボットとの新しい会話を開始する必要があることをユーザーに知らせます。

コードサンプル

サンプルの名前	説明	Node.js
Northwind インベントリメッセージ拡張機能	このサンプルは、Microsoft 365 Copilotのエージェントとして機能する Teams メッセージ拡張機能です。これは、copilotハンドオフを備え、ユーザーがチャットをMicrosoft 365 Copilotから Northwind Database に移行できるようにします。	表示

次の方法で共有

Copilot ハンドオフ

copilot ハンドオフのしくみ

copilot ハンドオフを有効にする

ベストプラクティス

コードサンプル

その他のリソース

次の方法で共有

Copilot ハンドオフ

copilot ハンドオフのしくみ

copilot ハンドオフを有効にする

ベスト プラクティス

コード サンプル

その他のリソース

ベストプラクティス

コードサンプル