Implementieren von asynchronem und proaktivem Messaging in benutzerdefinierten Engine-Agents

Dieser Artikel beschreibt, wie Sie asynchrone und proaktive Messagingmuster in benutzerdefinierten Modul-Agents implementieren, die Sie mit dem Microsoft Bot Framework erstellen. Diese Muster ermöglichen es Ihren Agents, Benutzern mit einer Verzögerung oder ohne eine vom Benutzer initiierte Nachricht zu antworten.

Sie können asynchrones und proaktives Messaging verwenden, um Ihren benutzerdefinierten Modul-Agents Folgendes zu ermöglichen:

• Antworten Sie nach einer Verzögerung, während die Hintergrundverarbeitung fortgesetzt wird.
• Initiieren von Nachrichten ohne Benutzereingabe (z. B. vom System ausgelöste Updates).

Jede Benutzeranfrage sollte innerhalb von 15 Sekunden eine erste Antwort erhalten. Bei langwierigen Aufgaben können Agents Folgenachrichten senden. Zwischen Streamingupdates gilt ein Timeout von 45 Sekunden.

Asynchrone Nachrichten

Asynchrone Nachrichten werden gesendet, nachdem der Agent eine vom Benutzer initiierte Hintergrundaufgabe abgeschlossen hat. Dieses Muster ist nützlich für Szenarien wie die Nachverfolgung von Bestellungen oder status Aktualisierungen.

Wenn ein Benutzer beispielsweise einen Laptop bestellt, kann Ihr Agent die Anforderung bestätigen und später eine Folgenachricht an den Benutzer senden, wenn die Bestellung aufgegeben wurde. Im folgenden Beispiel wird gezeigt, wie Sie das Bot Framework verwenden, um eine asynchrone Nachricht bezüglich der Laptopbestellung zu senden.

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

In der folgenden Tabelle ist der asynchrone Nachrichtenvorgang zusammengefasst.

Proaktive Nachrichten

Proaktive Nachrichten werden vom System initiiert, nicht vom Benutzer. Diese Nachrichten werden über einen dedizierten Unterhaltungsthread gesendet.

Beispielsweise kann Ihr Agent eine Benachrichtigung über ein Ereignis oder eine Aktualisierung ohne Benutzerabfrage an einen Benutzer senden. Im folgenden Beispiel wird gezeigt, wie Sie die createConversation-API verwenden, um die Unterhaltungsinformationen abzurufen und proaktive Nachrichten über einen dedizierten Thread zu senden.

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

In der folgenden Tabelle ist eine Zusammenfassung des proaktiven Nachrichtenprozesses enthalten.

Verwandte Inhalte

• Benutzeroberflächenfeatures des benutzerdefinierten Engine-Agents
• Übersicht über den benutzerdefinierten Engine Agent