Implemente mensagens assíncronas e proativas em agentes de mecanismo personalizados

Este artigo descreve como implementar padrões de mensagens assíncronos e proativos em agentes de mecanismo personalizados que você cria com o Microsoft Bot Framework. Esses padrões permitem que seus agentes respondam aos usuários após um atraso ou sem uma mensagem iniciada pelo usuário.

É possível usar mensagens assíncronas e proativas para permitir que os agentes de mecanismo personalizados:

• Responda após um atraso enquanto continua o processamento em segundo plano.
• Iniciar mensagens sem a entrada do usuário (por exemplo, atualizações disparadas pelo sistema).

Cada consulta de usuário deve receber uma resposta inicial em até 15 segundos. Para tarefas de longa duração, os agentes podem enviar mensagens de acompanhamento. Um tempo limite de 45 segundos se aplica entre as atualizações de streaming.

Mensagens assíncronas

Mensagens assíncronas são enviadas depois que o agente conclui uma tarefa em segundo plano iniciada pelo usuário. Esse padrão é útil para cenários como acompanhamento de pedidos ou atualizações de status.

Por exemplo, se um usuário solicitar um laptop, seu agente poderá confirmar a solicitação e enviar uma mensagem de acompanhamento ao usuário quando o pedido for feito. O exemplo a seguir mostra como usar o Bot Framework para enviar uma mensagem assíncrona referente ao pedido de laptop.

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

A tabela a seguir resume o processo de mensagem assíncrona.

Mensagens proativas

As mensagens proativas são iniciadas pelo sistema, não pelo usuário. Essas mensagens são enviadas por meio de um thread de conversa dedicado.

Por exemplo, seu agente pode enviar uma notificação a um usuário sobre um evento ou atualização sem uma consulta do usuário. O exemplo a seguir mostra como usar a API createConversation para buscar as informações da conversa e enviar mensagens proativas por meio de um thread dedicado.

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

A tabela a seguir resume o processo de mensagem proativa.

Conteúdo relacionado

• Recursos de experiência do usuário do agente de mecanismo personalizado
• Visão geral do agente de mecanismo personalizado