Copilot ハンドオフ

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

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

copilot ハンドオフのしくみ

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

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

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

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

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

2. 呼び出しの種類を処理する: ボット コードで、onInvokeActivity ハンドラーを使用して呼び出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 からのハンドオフを続行できないため、ボットとの新しい会話を開始する必要があることをユーザーに知らせます。

コード サンプル