Implementar mensagens assíncronas e proativas em agentes de motor personalizados

Este artigo descreve como implementar padrões de mensagens assíncronos e proativos em agentes de motor personalizados que cria com o Microsoft Bot Framework. Estes padrões permitem que os agentes respondam aos utilizadores após um atraso ou sem uma mensagem iniciada pelo utilizador.

Pode utilizar mensagens assíncronas e proativas para permitir que os agentes do motor personalizado:

• Responda após um atraso durante o processamento em segundo plano.
• Inicie mensagens sem a entrada do utilizador (por exemplo, atualizações acionadas pelo sistema).

Cada consulta de utilizador deve receber uma resposta inicial dentro de 15 segundos. Para tarefas de execução prolongada, os agentes podem enviar mensagens de seguimento. Um tempo limite de 45 segundos aplica-se entre as atualizações de transmissão em fluxo.

Mensagens assíncronas

As mensagens assíncronas são enviadas depois de o agente concluir uma tarefa em segundo plano iniciada pelo utilizador. Este padrão é útil para cenários como o controlo de encomendas ou atualizações de status.

Por exemplo, se um utilizador encomendar um portátil, o agente pode confirmar o pedido e, posteriormente, enviar uma mensagem de seguimento ao utilizador quando a encomenda for efetuada. O exemplo seguinte mostra como utilizar o Bot Framework para enviar uma mensagem assíncrona sobre a encomenda do portátil.

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 seguinte resume o processo de mensagem assíncrona.

Mensagens proativas

As mensagens proativas são iniciadas pelo sistema, não pelo utilizador. Estas mensagens são enviadas através de um tópico de conversação dedicado.

Por exemplo, o agente pode enviar uma notificação a um utilizador sobre um evento ou atualização sem uma consulta de utilizador. O exemplo seguinte mostra como utilizar a API createConversation para obter as informações de conversação e enviar mensagens proativas através 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 seguinte resume o processo de mensagem proativa.

Conteúdo relacionado

• Funcionalidades de experiência de utilizador do agente do motor personalizado
• Descrição geral do agente do motor personalizado