Compartilhar via


Conversas orientadas a eventos usando um manipulador de atividades

APLICA-SE A: SDK v4

Um manipulador de atividades é uma forma orientada a eventos de organizar a lógica para a conversação do bot. Cada tipo ou subtipo diferente de atividade representa um tipo diferente de evento de conversação. Em segundo plano, o manipulador de turnos do bot chama o manipulador de atividades específico para qualquer tipo de atividade recebida.

Por exemplo, se o bot receber uma atividade de mensagem, o manipulador de turnos analisará essa atividade recebida e a enviará para o manipulador de atividades de atividade de mensagem. Ao desenvolver o bot, a lógica do bot para tratar e responder às mensagens será encaminhada para este manipulador de atividade de mensagem. De forma semelhante, a lógica para tratar os membros adicionados à conversa será encaminhada para o manipulador de membros adicionados, que é chamado sempre que um membro é adicionado à conversa.

Para obter outras maneiras de organizar a lógica do bot, confira a seção Lógica do bot em Como funcionam os bots.

Observação

Os SDKs JavaScript, C# e Python do Bot Framework continuarão a ser compatíveis. No entanto, o SDK Java está sendo desativado, com o suporte final de longo prazo terminando em novembro de 2023.

Os bots existentes criados com o SDK para Java continuarão a funcionar.

Para a criação de novos bots, considere usar o Microsoft Copilot Studio e leia sobre como escolher a solução de copiloto certa.

Para obter mais informações, confira O futuro da criação de bots.

Para implementar a lógica para esses manipuladores, você realizará a substituição desses métodos no bot, como na seção de amostra de manipulador de atividades abaixo. Para cada um desses manipuladores, não há uma implementação de base, portanto, basta adicionar a lógica desejada em sua substituição.

Existem determinadas situações em que você desejará realizar a substituição do manipulador de turno de base, como salvar o estado no final de um turno. Ao fazer isso, chame primeiro await base.OnTurnAsync(turnContext, cancellationToken); para fazer com que a implementação base de OnTurnAsync seja executada antes do código adicional. A implementação base é, entre outras coisas, responsável por chamar o resto dos manipuladores de atividade, como OnMessageActivityAsync.

Tratamento de atividades

A lógica do bot processa as atividades de entrada de um ou mais canais e gera atividades de saída em resposta.

A lógica principal do bot é definida no código do bot. Para implementar um bot como um manipulador de atividades, derive a classe de bot de ActivityHandler, que implementa a interface IBot. ActivityHandler define vários manipuladores para diferentes tipos de atividades, como OnMessageActivityAsync e OnMembersAddedAsync. Esses métodos são protegidos, mas podem ser substituídos, já que são derivados de ActivityHandler.

Os manipuladores definidos em ActivityHandler são:

Evento Manipulador Descrição
Qualquer tipo de atividade recebido OnTurnAsync Chama um dos outros manipuladores com base no tipo de atividade recebido.
Atividade de mensagem recebida OnMessageActivityAsync Substitua-o para lidar com uma atividade message.
Atividade de atualização de conversa recebida OnConversationUpdateActivityAsync Em uma atividade conversationUpdate, chama um manipulador se algum membro que não seja o bot ingressa na conversa ou sai dela.
Membros que não são bot ingressaram na conversa OnMembersAddedAsync Substitua-o para lidar com membros que ingressam em uma conversa.
Membros que não são bot saíram da conversa OnMembersRemovedAsync Substitua-o para lidar com membros que saem de uma conversa.
Atividade de evento recebida OnEventActivityAsync Em uma atividade event, chama um manipulador específico ao tipo de evento.
Atividade de evento de resposta de token recebida OnTokenResponseEventAsync Substitua-o para manipular eventos de resposta de token.
Atividade de evento de resposta não token recebida OnEventAsync Substitua-o para lidar com outros tipos de eventos.
Atividade de reação de mensagem recebida OnMessageReactionActivityAsync Em uma atividade messageReaction, chamará um manipulador se uma ou mais reações forem adicionadas ou removidas de uma mensagem.
Reações de mensagem adicionadas a uma mensagem OnReactionsAddedAsync Substitua isso para manipular reações adicionadas a uma mensagem.
Reações de mensagem removidas de uma mensagem OnReactionsRemovedAsync Substitua isso para manipular reações removidas de uma mensagem.
Atividade de atualização de instalação recebida OnInstallationUpdateActivityAsync Em uma atividade installationUpdate, chame um manipulador com base no fato de o bot ter sido instalado ou desinstalado.
Bot instalado OnInstallationUpdateAddAsync Substitua isso para adicionar a lógica para quando o bot for instalado em uma unidade organizacional.
Bot desinstalado OnInstallationUpdateRemoveAsync Substitua isso para adicionar a lógica para quando o bot for desinstalado em uma unidade organizacional.
Outro tipo de atividade recebido OnUnrecognizedActivityTypeAsync Substitua-o para lidar com qualquer tipo de atividade sem tratamento.

Esses manipuladores diferentes têm um turnContext que fornece informações sobre a atividade de entrada, que corresponde à solicitação HTTP de entrada. As atividades podem ser de vários tipos e, portanto, cada manipulador fornece uma atividade fortemente tipada em seu parâmetro de contexto de turno; na maioria dos casos, OnMessageActivityAsync sempre será manipulado e é geralmente o mais comum.

Como nas versões 4.x anteriores desta estrutura, também existe a opção de implementar o método público OnTurnAsync. Atualmente, a implementação base desse método lida com a verificação de erros e, em seguida, chama cada um dos manipuladores específicos (como os dois que definimos neste exemplo) dependendo do tipo de atividade de entrada. Na maioria dos casos, é possível deixar esse método de lado e usar os manipuladores específicos, mas se a situação exigir uma implementação personalizada de OnTurnAsync, ele ainda será uma opção.

Importante

Se você substituir o método OnTurnAsync, precisará chamar base.OnTurnAsync para obter a implementação base e chamar todos os outros manipuladores On<activity>Async, ou chamar esses manipuladores por conta própria. Caso contrário, esses manipuladores não serão chamados e o código não será executado.

Amostra de manipulador de atividade

Por exemplo, é possível manipular os membros adicionados para dar as boas-vindas aos usuários em uma conversa e manipular as mensagens para ecoar as mensagens enviadas ao bot.

public class EchoBot : ActivityHandler
{
    protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
    {
        var replyText = $"Echo: {turnContext.Activity.Text}";
        await turnContext.SendActivityAsync(MessageFactory.Text(replyText, replyText), cancellationToken);
    }

    protected override async Task OnMembersAddedAsync(IList<ChannelAccount> membersAdded, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
    {
        var welcomeText = "Hello and welcome!";
        foreach (var member in membersAdded)
        {
            if (member.Id != turnContext.Activity.Recipient.Id)
            {
                await turnContext.SendActivityAsync(MessageFactory.Text(welcomeText, welcomeText), cancellationToken);
            }
        }
    }
}

Próximas etapas

  • O canal do Microsoft Teams apresenta algumas atividades específicas do Teams que o bot precisará oferecer suporte para funcionar adequadamente com o Teams. Para entender os principais conceitos de desenvolvimento de bots para o Microsoft Teams, confira Como os bots do Microsoft Teams funcionam
  • Um manipulador de atividades é uma boa maneira de projetar um bot que não precise acompanhar o estado de conversação entre os turnos. A biblioteca de diálogos fornece maneiras de gerenciar uma conversa de execução prolongada com o usuário.