カスタム エンジン エージェントに非同期メッセージングとプロアクティブ メッセージングを実装する

この記事では、Microsoft Bot Frameworkを使用してビルドするカスタム エンジン エージェントに非同期およびプロアクティブ メッセージング パターンを実装する方法について説明します。 これらのパターンを使用すると、エージェントは遅延後、またはユーザーが開始したメッセージなしでユーザーに応答できます。

非同期メッセージングとプロアクティブ メッセージングを使用して、カスタム エンジン エージェントで次のことができます。

• バックグラウンド処理を続行しながら、遅延後に応答します。
• ユーザー入力なしでメッセージを開始します (システムによってトリガーされる更新プログラムなど)。

各ユーザー クエリは、15 秒以内に最初の応答を受け取る必要があります。 実行時間の長いタスクの場合、エージェントはフォローアップ メッセージを送信できます。 ストリーミング更新の間に 45 秒のタイムアウトが適用されます。

非同期メッセージ

非同期メッセージは、エージェントがユーザーによって開始されたバックグラウンド タスクを完了した後に送信されます。 このパターンは、注文の追跡や状態の更新などのシナリオに役立ちます。

たとえば、ユーザーがノート PC を注文した場合、エージェントは要求を確認し、注文が行われたときに後でフォローアップ メッセージをユーザーに送信できます。 次の例は、 Bot Framework を使用してノート PC の注文に関する非同期メッセージを送信する方法を示しています。

app.message( 

    CustomMessageTypes.orderLaptopSelected.toString(), 
    async (context: TurnContext, _state) => { 
      return new Promise(async (resolve) => { 
        await context.sendActivity({ 
          text: "Thank you for order laptop. I will keep you posted with updates.", 
        });   

        setTimeout(async () => { 
          await context.sendActivity({ 
            text: "Great! I have successfully placed your order #1292. I'll notify you when it's delivered.", 
            attachments: [ 
              { 
                contentType: "application/vnd.microsoft.card.adaptive", 
                content: deliveredCard, 
              }, 
            ], 
          }); 
          resolve(); 
        }, 10 * 1000); 
      }); 
    } 
  ); 

次の表は、非同期メッセージ プロセスをまとめたものです。

プロアクティブ メッセージ

プロアクティブ メッセージは、ユーザーではなくシステムによって開始されます。 これらのメッセージは、専用の会話スレッドを介して送信されます。

たとえば、エージェントは、イベントに関する通知をユーザーに送信したり、ユーザー クエリなしで更新したりできます。 次の例は、 createConversation API を使用して会話情報をフェッチし、専用スレッド経由でプロアクティブ メッセージを送信する方法を示しています。

export async function getToken() { 
  const url = 
    "https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token"; 
  const params = new URLSearchParams(); 
  params.append("grant_type", "client_credentials"); 
  params.append("client_id", config.MicrosoftAppId); 
  params.append("client_secret", config.MicrosoftAppPassword); 
  params.append("scope", "https://api.botframework.com/.default"); 

  const response = await fetch(url, { 
    method: "POST", 
    headers: { 
      "Content-Type": "application/x-www-form-urlencoded", 
    }, 
    body: params.toString(), 
  }); 

  if (!response.ok) { 
    throw new Error(`Error! status: ${response.status}`); 
  }

  const data = await response.json(); 
  return data; 
} 
  
  let accessToken; 
    try { 
      accessToken = getToken(); 
      if (!accessToken) { 
        console.log("No access token found, fetching a new one"); 
        const tokenResponse = await getToken(); 
        accessToken = tokenResponse.access_token; 
        if (!accessToken) { 
          throw new Error("Failed to obtain access token"); 
        } 
        setAccessToken(accessToken); 
      } 
    } catch (error) { 
      console.error("Error retrieving access token:", error); 
      await context.sendActivity( 
        "Failed to send proactive message due to authentication error" 
      ); 
      return; 
    }  

    const createConversationBody = { 
      members: [{ id: context.activity.from.aadObjectId }], 
      tenantId: context.activity.conversation.tenantId, 
      channelData: { 
        productContext: "Copilot", 
        conversation: { 
          conversationSubType: "AgentProactive", 
        }, 
      }, 
    }; 

    const createConversationResponse = await fetch( 
      "https://canary.botapi.skype.com/teams/v3/conversations", 
      { 
        method: "POST", 
        headers: { 
          "Content-Type": "application/json", 
          Authorization: `Bearer ${accessToken}`, 
        }, 
        body: JSON.stringify(createConversationBody), 
      } 
    );  

    const createConversationResponseData = 
      await createConversationResponse.json(); 
    console.log("Create conversation response", createConversationResponseData); 
    const body = { 
      text: "Hello proactive world", 
      type: "message", 
    }; 

    const response = await fetch( 
      `https://canary.botapi.skype.com/teams/v3/conversations/${createConversationResponseData.id}/activities`, 
      { 
        method: "POST", 
        headers: { 
          "Content-Type": "application/json", 
          Authorization: `Bearer ${accessToken}`, 
        }, 
        body: JSON.stringify(body), 
      } 
    ); 

次の表は、プロアクティブ メッセージ プロセスをまとめたものです。

関連コンテンツ

• カスタム エンジン エージェントのユーザー エクスペリエンス機能
• カスタム エンジン エージェントの概要