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.

C#

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.

JavaScript

O JavaScript ActivityHandler usa um emissor de eventos e um padrão de ouvinte. Por exemplo, use o método onMessage para registrar um ouvinte de eventos para atividades de 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 a cada um dos ouvintes de atividade onMessage, na ordem em que elas foram registradas.

Ao criar seu bot, a lógica do bot para tratar das mensagens e respondê-las entrará nos ouvintes onMessage. Da mesma forma, a lógica de tratamento de membros que estão sendo adicionados à conversa vai entrar nos ouvintes onMembersAdded, 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 de bot e, em seguida, não se esqueça de chamar next() no final. Ao chamar next(), você garante que o próximo ouvinte seja executado.

Lembre-se de salvar o estado antes que o ciclo seja concluído. Você pode fazer isso substituindo o método run do manipulador de atividade e salvando o estado após a conclusão do método run do pai.

Não existem situações comuns em que você deseje realizar a substituição do manipulador de turno de base, portanto, tenha cuidado ao tentar fazer isso. Existe um manipulador especial chamado onDialog. O manipulador onDialog é executado no final, após a execução do restante dos manipuladores, e não está vinculado a um determinado tipo de atividade. Assim como com todos os manipuladores acima, não deixe de chamar next() para garantir a conclusão do processo.

Java

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. Não há implementação de base para cada um desses manipuladores, portanto, adicione 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, certifique-se primeiro de chamar super.onTurn(turnContext); para garantir que a implementação de base de onTurn 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 onMessageActivity.

Python

Ao criar seu bot, sua lógica do bot para tratar das mensagens e respondê-las entrará nesse manipulador on_message_activity. Da mesma forma, sua lógica de tratamento de membros que estão sendo adicionados à conversa vai entrar no manipulador on_members_added, que é chamado sempre que um membro é adicionado à conversa.

Por exemplo, se o bot recebe uma atividade de mensagem, o manipulador de turno vê a atividade de entrada a envia para o manipulador de atividade on_message_activity.

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 super().on_turn(turnContext); para fazer com que a implementação base de on_turn 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 on_message_activity.

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.

C#

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.

JavaScript

A lógica principal do bot é definida no código do bot. Para implementar um bot como um manipulador de atividades, estenda o ActivityHandler. O ActivityHandler define vários eventos para diferentes tipos de atividades, e é possível modificar o comportamento do seu bot ao registrar ouvintes de eventos, como onMessage e onConversationUpdate.

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

Evento	Método de registro	Descrição
Qualquer tipo de atividade recebido	onTurn	Registra um ouvinte para quando qualquer atividade for recebida.
Atividade de mensagem recebida	onMessage	Registra um ouvinte para quando uma atividade message for recebida.
Atividade de atualização de conversa recebida	onConversationUpdate	Registra um ouvinte para quando qualquer atividade conversationUpdate for recebida.
Membros ingressaram na conversa	onMembersAdded	Registra um ouvinte para quando os membros ingressarem na conversa, incluindo o bot.
Membros saíram da conversa	onMembersRemoved	Registra um ouvinte para quando os membros saírem da conversa, incluindo o bot.
Atividade de reação de mensagem recebida	onMessageReaction	Registra um ouvinte para quando qualquer atividade messageReaction for recebida.
Reações de mensagem adicionadas a uma mensagem	onReactionsAdded	Registra um ouvinte para quando as reações forem adicionadas a uma mensagem.
Reações de mensagem removidas de uma mensagem	onReactionsRemoved	Registra um ouvinte para quando as reações forem removidas de uma mensagem.
Atividade de evento recebida	onEvent	Registra um ouvinte para quando qualquer atividade event for recebida.
Atividade de evento de resposta de token recebida	onTokenResponseEvent	Registra um ouvinte para quando um evento tokens/response for recebido.
Atividade de atualização de instalação recebida	onInstallationUpdate	Registra um ouvinte para quando qualquer atividade installationUpdate for 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 em uma unidade organizacional.
Outro tipo de atividade recebido	onUnrecognizedActivityType	Registra um ouvinte para quando um manipulador para o tipo específico de atividade não estiver definido.
Manipuladores de atividade concluídos	onDialog	Chamado após a conclusão de qualquer manipulador aplicável.

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

Java

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 Bot. 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, já que são derivados de ActivityHandler.

Os manipuladores definidos em ActivityHandler são:

Evento	Manipulador	Descrição
Qualquer tipo de atividade recebido	onTurn	Chama um dos outros manipuladores com base no tipo de atividade recebido.
Atividade de mensagem recebida	onMessageActivity	Substitua-o para lidar com uma atividade message.
Atividade de atualização de conversa recebida	onConversationUpdateActivity	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	onMembersAdded	Substitua-o para lidar com membros que ingressam em uma conversa.
Membros que não são bot saíram da conversa	onMembersRemoved	Substitua-o para lidar com membros que saem de uma conversa.
Atividade de evento recebida	onEventActivity	Em uma atividade event, chama um manipulador específico ao tipo de evento.
Atividade de evento de resposta de token recebida	onTokenResponseEvent	Substitua-o para manipular eventos de resposta de token.
Atividade de evento de resposta não token recebida	onEvent	Substitua-o para lidar com outros tipos de eventos.
Atividade de reação de mensagem recebida	onMessageReactionActivity	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	onReactionsAdded	Substitua isso para manipular reações adicionadas a uma mensagem.
Reações de mensagem removidas de uma mensagem	onReactionsRemoved	Substitua isso para manipular reações removidas de uma mensagem.
Atividade de atualização de instalação recebida	onInstallationUpdate	Em uma atividade installationUpdate, chame um manipulador com base no fato de o bot ter sido instalado ou desinstalado.
Bot instalado	onInstallationUpdateAdd	Substitua isso para adicionar a lógica para quando o bot for instalado em uma unidade organizacional.
Bot desinstalado	onInstallationUpdateRemove	Substitua isso para adicionar a lógica para quando o bot for desinstalado em uma unidade organizacional.
Outro tipo de atividade recebido	onUnrecognizedActivityType	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, onMessageActivity sempre será manipulado e é geralmente o mais comum.

Também existe a opção de implementar o método público onTurn. 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 onTurn, ele ainda será uma opção.

Importante

Se você substituir o método onTurn, precisará chamar super.onTurn para obter a implementação base e chamar todos os outros manipuladores on<activity>, 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.

Python

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, 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, já que são derivados de ActivityHandler.

Os manipuladores definidos em ActivityHandler são:

Evento	Manipulador	Descrição
Qualquer tipo de atividade recebido	on_turn	Chama um dos outros manipuladores com base no tipo de atividade recebido.
Atividade de mensagem recebida	on_message_activity	Substitua-o para lidar com uma atividade message.
Atividade de atualização de conversa recebida	on_conversation_update_activity	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	on_members_added_activity	Substitua-o para lidar com membros que ingressam em uma conversa.
Membros que não são bot saíram da conversa	on_members_removed_activity	Substitua-o para lidar com membros que saem de uma conversa.
Atividade de evento recebida	on_event_activity	Em uma atividade event, chama um manipulador específico ao tipo de evento.
Atividade de evento de resposta de token recebida	on_token_response_event	Substitua-o para manipular eventos de resposta de token.
Atividade de evento de resposta não token recebida	on_event_activity	Substitua-o para lidar com outros tipos de eventos.
Atividade de reação de mensagem recebida	on_message_reaction_activity	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	on_reactions_added	Substitua isso para manipular reações adicionadas a uma mensagem.
Reações de mensagem removidas de uma mensagem	on_reactions_removed	Substitua isso para manipular reações removidas de uma mensagem.
Atividade de atualização de instalação recebida	on_installation_update	Em uma atividade installationUpdate, chame um manipulador com base no fato de o bot ter sido instalado ou desinstalado.
Bot instalado	on_installation_update_add	Substitua isso para adicionar a lógica para quando o bot for instalado em uma unidade organizacional.
Bot desinstalado	on_installation_update_remove	Substitua isso para adicionar a lógica para quando o bot for desinstalado em uma unidade organizacional.
Outro tipo de atividade recebido	on_unrecognized_activity_type	Substitua-o para lidar com qualquer tipo de atividade sem tratamento.

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 e, portanto, cada manipulador fornece uma atividade fortemente tipada em seu parâmetro de contexto de turno; na maioria dos casos, on_message_activity 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 on_turn. 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 on_turn, ele ainda será uma opção.

Importante

Se você substituir o método on_turn, precisará chamar super().on_turn para obter a implementação base e chamar todos os outros manipuladores on_<activity>, 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.

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ó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.