Conversas orientadas a eventos usando um manipulador de atividades

APLICA-SE A: SDK v4

Um manipulador de atividades é uma maneira orientada a eventos de organizar a lógica de conversação para seu bot. Cada tipo ou subtipo diferente de atividade representa um tipo diferente de evento de conversação. Sob as cobertas, o manipulador de turnos do bot chama o manipulador de atividades individuais para qualquer tipo de atividade recebida.

Por exemplo, se o bot receber uma atividade de mensagem, o manipulador de turnos verá essa atividade de entrada e a enviará para o manipulador de atividade na mensagem. Ao criar seu bot, sua lógica de bot para lidar e responder a mensagens irá para isso no manipulador de atividade de mensagens. Da mesma forma, sua lógica para lidar com membros que estão sendo adicionados à conversa irá em seu manipulador de membros adicionados , que é chamado sempre que um membro é adicionado à conversa.

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

Nota

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

Os bots existentes construídos com o Java SDK 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 copilot certa.

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

C#

Para implementar sua lógica para esses manipuladores, você substituirá esses métodos em seu bot, como na seção manipulador de atividades de exemplo abaixo. Para cada um desses manipuladores, não há implementação básica, então basta adicionar a lógica desejada em sua substituição.

Há certas situações em que você vai querer substituir o manipulador de giro de base, como salvar o estado no final de uma curva. Ao fazer isso, certifique-se de chamar primeiro await base.OnTurnAsync(turnContext, cancellationToken); para garantir que a implementação base do seja executada antes do OnTurnAsync código adicional. Essa implementação base é, entre outras coisas, responsável por chamar o restante dos manipuladores de atividade, como OnMessageActivityAsync.

JavaScript

O JavaScript ActivityHandler usa um emissor de eventos e um padrão de ouvinte. Por exemplo, use o método para registrar um ouvinte de eventos para atividades de onMessage mensagem. Você pode registrar mais de um ouvinte. Quando o bot recebe uma atividade de mensagem, o manipulador de atividades vê essa atividade de entrada e a envia para cada um dos ouvintes de onMessage atividade, na ordem em que foram registrados.

Ao criar seu bot, sua lógica de bot para lidar e responder a mensagens irá para os onMessage ouvintes. Da mesma forma, sua lógica para lidar com membros que estão sendo adicionados à conversa irá para seus onMembersAdded ouvintes, que são chamados sempre que um membro é adicionado à conversa. Para adicionar esses ouvintes, você os registrará em seu bot, conforme visto na seção Lógica do bot abaixo. Para cada ouvinte, inclua a lógica do bot e, em seguida , certifique-se de ligar next() no final. Ao chamar next()o , você garante que o próximo ouvinte seja executado.

Certifique-se de salvar o estado antes que a curva termine. Você pode fazer isso substituindo o método do manipulador run de atividades e salvando o estado após a conclusão do run método pai.

Não há situações comuns em que você queira substituir o manipulador de giro de base, então tenha cuidado se tentar fazê-lo. Há um manipulador especial chamado onDialog. O onDialog manipulador é executado no final, depois que o restante dos manipuladores é executado, e não está vinculado a um determinado tipo de atividade. Como acontece com todos os manipuladores acima, certifique-se de ligar next() para garantir que o resto do processo seja concluído.

Java

Para implementar sua lógica para esses manipuladores, você substituirá esses métodos em seu bot, como na seção manipulador de atividades de exemplo abaixo. Não há implementação base para cada um desses manipuladores, portanto, adicione a lógica desejada em sua substituição.

Há certas situações em que você vai querer substituir o manipulador de giro de base, como salvar o estado no final de uma curva. Ao fazer isso, certifique-se de ligar super.onTurn(turnContext); primeiro para garantir que a implementação base do seja executada antes do onTurn código adicional. Essa implementação base é, entre outras coisas, responsável por chamar o restante dos manipuladores de atividade, como onMessageActivity.

Python

Ao criar seu bot, sua lógica de bot para lidar e responder a mensagens irá para esse on_message_activity manipulador. Da mesma forma, sua lógica para lidar com membros que estão sendo adicionados à conversa irá para seu on_members_added manipulador, que é chamado sempre que um membro é adicionado à conversa.

Por exemplo, se o bot receber uma atividade de mensagem, o manipulador de turnos verá essa atividade de entrada e a enviará para o manipulador de on_message_activity atividades.

Para implementar sua lógica para esses manipuladores, você substituirá esses métodos em seu bot, como na seção manipulador de atividades de exemplo abaixo. Para cada um desses manipuladores, não há implementação básica, então basta adicionar a lógica desejada em sua substituição.

Há certas situações em que você vai querer substituir o manipulador de giro de base, como salvar o estado no final de uma curva. Ao fazer isso, certifique-se de chamar primeiro await super().on_turn(turnContext); para garantir que a implementação base do seja executada antes do on_turn código adicional. Essa implementação base é, entre outras coisas, responsável por chamar o restante dos manipuladores de atividade, como on_message_activity.

Manuseamento de atividades

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

C#

A lógica principal do bot é definida no código do bot. Para implementar um bot como um manipulador de atividades, derive sua classe de bot de ActivityHandler, que implementa a IBot interface. 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, uma vez que estamos derivando de ActivityHandler.

Os manipuladores definidos são ActivityHandler :

Evento	Processador	Description
Qualquer tipo de atividade recebida	OnTurnAsync	Chama um dos outros manipuladores, com base no tipo de atividade recebida.
Atividade da mensagem recebida	OnMessageActivityAsync	Substitua isso para lidar com uma message atividade.
Atividade de atualização de conversação recebida	OnConversationUpdateActivityAsync	Em uma conversationUpdate atividade, chama um manipulador se outros membros além do bot entraram ou saíram da conversa.
Membros que não são bots se juntaram à conversa	OnMembersAddedAsync	Substitua isso para lidar com os membros que participam de uma conversa.
Membros que não são bots deixaram a conversa	OnMembersRemovedAsync	Substitua isso para lidar com os membros que saem de uma conversa.
Atividade do evento recebida	OnEventActivityAsync	Em uma event atividade, chama um manipulador específico para o tipo de evento.
Atividade de evento de resposta de token recebida	OnTokenResponseEventAsync	Substitua isso para manipular eventos de resposta de token.
Atividade de evento de resposta não tokenizada recebida	OnEventAsync	Substitua isso para lidar com outros tipos de eventos.
Atividade de reação de mensagem recebida	OnMessageReactionActivityAsync	Em uma messageReaction atividade, chama um manipulador se uma ou mais reações foram adicionadas ou removidas de uma mensagem.
Reações de mensagem adicionadas a uma mensagem	OnReactionsAddedAsync	Substitua isso para lidar com as reações adicionadas a uma mensagem.
Reações de mensagem removidas de uma mensagem	OnReactionsRemovedAsync	Substitua isso para lidar com reações removidas de uma mensagem.
Atividade de atualização de instalação recebida	OnInstallationUpdateActivityAsync	Em uma installationUpdate atividade, chama um manipulador com base em se o bot foi instalado ou desinstalado.
Bot instalado	OnInstallationUpdateAddAsync	Substitua isso para adicionar lógica para quando o bot estiver instalado em uma unidade organizacional.
Bot desinstalado	OnInstallationUpdateRemoveAsync	Substitua isso para adicionar lógica para quando o bot for desinstalado em uma unidade organizacional.
Outro tipo de atividade recebida	OnUnrecognizedActivityTypeAsync	Substitua isso para lidar com qualquer tipo de atividade que, de outra forma, não seria tratada.

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, de modo que cada manipulador fornece uma atividade fortemente tipada em seu parâmetro de contexto por turno; na maioria dos casos, OnMessageActivityAsync será sempre manuseado, sendo geralmente o mais comum.

Como nas versões 4.x anteriores desta estrutura, há também a opção de implementar o método OnTurnAsyncpúblico . 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, você pode deixar esse método sozinho e usar os manipuladores individuais, mas se sua situação exigir uma implementação personalizada do OnTurnAsync, ainda é uma opção.

Importante

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

JavaScript

A lógica principal do bot é definida no código do bot. Para implementar um bot como um manipulador de atividades, estenda ActivityHandlero . ActivityHandler define vários eventos para diferentes tipos de atividades e você pode modificar o comportamento do bot registrando ouvintes de eventos, como com onMessage e onConversationUpdate.

Use estes métodos para registrar ouvintes para cada tipo de evento:

Evento	Método de registo	Description
Qualquer tipo de atividade recebida	onTurn	Registra um ouvinte para quando qualquer atividade é recebida.
Atividade da mensagem recebida	onMessage	Registra um ouvinte para quando uma message atividade é recebida.
Atividade de atualização de conversação recebida	onConversationUpdate	Registra um ouvinte para quando qualquer conversationUpdate atividade é recebida.
Os membros juntaram-se à conversa	onMembersAdded	Registra um ouvinte para saber quando os membros entraram na conversa, incluindo o bot.
Os membros abandonaram a conversa	onMembersRemoved	Registra um ouvinte para quando os membros saíram da conversa, incluindo o bot.
Atividade de reação de mensagem recebida	onMessageReaction	Registra um ouvinte para quando qualquer messageReaction atividade é recebida.
Reações de mensagem adicionadas a uma mensagem	onReactionsAdded	Registra um ouvinte para quando as reações são adicionadas a uma mensagem.
Reações de mensagem removidas de uma mensagem	onReactionsRemoved	Registra um ouvinte para quando as reações são removidas de uma mensagem.
Atividade do evento recebida	onEvent	Registra um ouvinte para quando qualquer event atividade é recebida.
Atividade de evento de resposta de token recebida	onTokenResponseEvent	Registra um ouvinte para quando um tokens/response evento é recebido.
Atividade de atualização de instalação recebida	onInstallationUpdate	Registra um ouvinte para quando qualquer installationUpdate atividade é recebida.
Bot instalado	onInstallationUpdateAdd	Registra um ouvinte para quando o bot é instalado em uma unidade organizacional.
Bot desinstalado	onInstallationUpdateRemove	Registra um ouvinte para quando o bot é desinstalado dentro de uma unidade organizacional.
Outro tipo de atividade recebida	onUnrecognizedActivityType	Registra um ouvinte para quando um manipulador para o tipo específico de atividade não está definido.
Os manipuladores de atividades foram concluídos	onDialog	Chamado após a conclusão de todos os manipuladores aplicáveis.

Chame a função de continuação de cada manipulador para permitir que o next processamento continue. Se next não for chamado, o processamento da atividade termina.

Java

A lógica principal do bot é definida no código do bot. Para implementar um bot como um manipulador de atividades, derive sua classe de bot de ActivityHandler, que implementa a Bot interface. ActivityHandler define vários manipuladores para diferentes tipos de atividades, como onMessageActivity, e onMembersAdded. Esses métodos são protegidos, mas podem ser substituídos, uma vez que estamos derivando de ActivityHandler.

Os manipuladores definidos são ActivityHandler :

Evento	Processador	Description
Qualquer tipo de atividade recebida	onTurn	Chama um dos outros manipuladores, com base no tipo de atividade recebida.
Atividade da mensagem recebida	onMessageActivity	Substitua isso para lidar com uma message atividade.
Atividade de atualização de conversação recebida	onConversationUpdateActivity	Em uma conversationUpdate atividade, chama um manipulador se outros membros além do bot entraram ou saíram da conversa.
Membros que não são bots se juntaram à conversa	onMembersAdded	Substitua isso para lidar com os membros que participam de uma conversa.
Membros que não são bots deixaram a conversa	onMembersRemoved	Substitua isso para lidar com os membros que saem de uma conversa.
Atividade do evento recebida	onEventActivity	Em uma event atividade, chama um manipulador específico para o tipo de evento.
Atividade de evento de resposta de token recebida	onTokenResponseEvent	Substitua isso para manipular eventos de resposta de token.
Atividade de evento de resposta não tokenizada recebida	onEvent	Substitua isso para lidar com outros tipos de eventos.
Atividade de reação de mensagem recebida	onMessageReactionActivity	Em uma messageReaction atividade, chama um manipulador se uma ou mais reações foram adicionadas ou removidas de uma mensagem.
Reações de mensagem adicionadas a uma mensagem	onReactionsAdded	Substitua isso para lidar com as reações adicionadas a uma mensagem.
Reações de mensagem removidas de uma mensagem	onReactionsRemoved	Substitua isso para lidar com reações removidas de uma mensagem.
Atividade de atualização de instalação recebida	onInstallationUpdate	Em uma installationUpdate atividade, chama um manipulador com base em se o bot foi instalado ou desinstalado.
Bot instalado	onInstallationUpdateAdd	Substitua isso para adicionar lógica para quando o bot estiver instalado em uma unidade organizacional.
Bot desinstalado	onInstallationUpdateRemove	Substitua isso para adicionar lógica para quando o bot for desinstalado em uma unidade organizacional.
Outro tipo de atividade recebida	onUnrecognizedActivityType	Substitua isso para lidar com qualquer tipo de atividade que, de outra forma, não seria tratada.

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, de modo que cada manipulador fornece uma atividade fortemente tipada em seu parâmetro de contexto por turno; na maioria dos casos, onMessageActivity será sempre manuseado, sendo geralmente o mais comum.

Há também a opção de implementar o método onTurnpúblico. 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, você pode deixar esse método sozinho e usar os manipuladores individuais, mas se sua situação exigir uma implementação personalizada do onTurn, ainda é uma opção.

Importante

Se você substituir o onTurn método, precisará chamar super.onTurn para obter a implementação base para chamar todos os outros on<activity> manipuladores ou chamar esses manipuladores você mesmo. Caso contrário, esses manipuladores não serão chamados e esse código não será executado.

Python

A lógica principal do bot é definida no código do bot. Para implementar um bot como um manipulador de atividades, derive sua classe de bot de ActivityHandler, que, por sua vez, deriva da classe abstrata Bot . ActivityHandler define vários manipuladores para diferentes tipos de atividades, como on_message_activity e on_members_added. Esses métodos são protegidos, mas podem ser substituídos, uma vez que estamos derivando de ActivityHandler.

Os manipuladores definidos são ActivityHandler :

Evento	Processador	Description
Qualquer tipo de atividade recebida	on_turn	Chama um dos outros manipuladores, com base no tipo de atividade recebida.
Atividade da mensagem recebida	on_message_activity	Substitua isso para lidar com uma message atividade.
Atividade de atualização de conversação recebida	on_conversation_update_activity	Em uma conversationUpdate atividade, chama um manipulador se outros membros além do bot entraram ou saíram da conversa.
Membros que não são bots se juntaram à conversa	on_members_added_activity	Substitua isso para lidar com os membros que participam de uma conversa.
Membros que não são bots deixaram a conversa	on_members_removed_activity	Substitua isso para lidar com os membros que saem de uma conversa.
Atividade do evento recebida	on_event_activity	Em uma event atividade, chama um manipulador específico para o tipo de evento.
Atividade de evento de resposta de token recebida	on_token_response_event	Substitua isso para manipular eventos de resposta de token.
Atividade de evento de resposta não tokenizada recebida	on_event_activity	Substitua isso para lidar com outros tipos de eventos.
Atividade de reação de mensagem recebida	on_message_reaction_activity	Em uma messageReaction atividade, chama um manipulador se uma ou mais reações foram adicionadas ou removidas de uma mensagem.
Reações de mensagem adicionadas a uma mensagem	on_reactions_added	Substitua isso para lidar com as reações adicionadas a uma mensagem.
Reações de mensagem removidas de uma mensagem	on_reactions_removed	Substitua isso para lidar com reações removidas de uma mensagem.
Atividade de atualização de instalação recebida	on_installation_update	Em uma installationUpdate atividade, chama um manipulador com base em se o bot foi instalado ou desinstalado.
Bot instalado	on_installation_update_add	Substitua isso para adicionar lógica para quando o bot estiver instalado em uma unidade organizacional.
Bot desinstalado	on_installation_update_remove	Substitua isso para adicionar lógica para quando o bot for desinstalado em uma unidade organizacional.
Outro tipo de atividade recebida	on_unrecognized_activity_type	Substitua isso para lidar com qualquer tipo de atividade que, de outra forma, não seria tratada.

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

Como nas versões 4.x anteriores desta estrutura, há também a opção de implementar o método on_turnpúblico . 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, você pode deixar esse método sozinho e usar os manipuladores individuais, mas se sua situação exigir uma implementação personalizada do on_turn, ainda é uma opção.

Importante

Se você substituir o on_turn método, precisará chamar super().on_turn para obter a implementação base para chamar todos os outros on_<activity> manipuladores ou chamar esses manipuladores você mesmo. Caso contrário, esses manipuladores não serão chamados e esse código não será executado.

Manipulador de atividade de amostra

Por exemplo, você pode lidar com membros adicionados para dar as boas-vindas aos usuários em uma conversa e lidar com mensagens para ecoar mensagens enviadas ao bot.

C#

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

JavaScript

class EchoBot extends ActivityHandler {
    constructor() {
        super();
        // See https://aka.ms/about-bot-activity-message to learn more about the message and other activity types.
        this.onMessage(async (context, next) => {
            const replyText = `Echo: ${ context.activity.text }`;
            await context.sendActivity(MessageFactory.text(replyText, replyText));
            // By calling next() you ensure that the next BotHandler is run.
            await next();
        });

        this.onMembersAdded(async (context, next) => {
            const membersAdded = context.activity.membersAdded;
            const welcomeText = 'Hello and welcome!';
            for (let cnt = 0; cnt < membersAdded.length; ++cnt) {
                if (membersAdded[cnt].id !== context.activity.recipient.id) {
                    await context.sendActivity(MessageFactory.text(welcomeText, welcomeText));
                }
            }
            // By calling next() you ensure that the next BotHandler is run.
            await next();
        });
    }
}

Java

public class EchoBot extends ActivityHandler {

    @Override
    protected CompletableFuture<Void> onMessageActivity(TurnContext turnContext) {
        return turnContext.sendActivity(
            MessageFactory.text("Echo: " + turnContext.getActivity().getText())
        ).thenApply(sendResult -> null);
    }

    @Override
    protected CompletableFuture<Void> onMembersAdded(
        List<ChannelAccount> membersAdded,
        TurnContext turnContext
    ) {
        String welcomeText = "Hello and welcome!";
        return membersAdded.stream()
            .filter(
                member -> !StringUtils
                    .equals(member.getId(), turnContext.getActivity().getRecipient().getId())
            ).map(channel -> turnContext.sendActivity(MessageFactory.text(welcomeText, welcomeText, null)))
            .collect(CompletableFutures.toFutureList()).thenApply(resourceResponses -> null);
    }
}

Python

class EchoBot(ActivityHandler):
    async def on_members_added_activity(
        self, members_added: [ChannelAccount], turn_context: TurnContext
    ):
        for member in members_added:
            if member.id != turn_context.activity.recipient.id:
                await turn_context.send_activity("Hello and welcome!")

    async def on_message_activity(self, turn_context: TurnContext):
        return await turn_context.send_activity(
            MessageFactory.text(f"Echo: {turn_context.activity.text}")
        )

Próximos passos

• O canal do Microsoft Teams apresenta algumas atividades específicas do Teams que seu bot precisará oferecer suporte para funcionar corretamente com o Teams. Para entender os principais conceitos de desenvolvimento de bots para o Microsoft Teams, consulte Como os bots do Microsoft Teams funcionam
• Um manipulador de atividades é uma boa maneira de projetar um bot que não precisa rastrear o estado de conversação entre turnos. A biblioteca de caixas de diálogo fornece maneiras de gerenciar uma conversa de longa duração com o usuário.