Conversaciones impulsadas por eventos usando un controlador de actividad

SE APLICA A: SDK v4

Un controlador de actividad es una manera controlada por eventos para organizar la lógica conversacional del bot. Cada tipo o subtipo de actividad diferente representa un tipo diferente de evento conversacional. De forma encubierta, el controlador de turnos del bot llama al controlador de actividad individual para el tipo de actividad que haya recibido.

Por ejemplo, si el bot recibe una actividad de mensaje, el controlador de turnos vería dicha actividad entrante y la enviaría al controlador de actividad de actividad en mensaje. Al crear el bot, la lógica del bot para controlar los mensajes y responderlos a mensajes se incluirá en este controlador en actividad de mensaje. Del mismo modo, la lógica para controlar la incorporación de miembros se incluirá en el controlador en miembros agregados, al que se llama cada vez que se agrega un miembro a la conversación.

Para conocer otras formas de organizar la lógica del bot, consulte la sección lógica del bot en cómo funcionan los bots.

Nota:

Los SDK de JavaScript, C# y Python de Bot Framework seguirán siendo compatibles, pero el SDK de Java se va a retirar con la finalización del soporte técnico a largo plazo en noviembre de 2023. Solo se realizarán correcciones de errores y seguridad críticos en este repositorio.

Los bots existentes creados con el SDK de Java seguirán funcionando.

Para la nueva compilación de bots, considere la posibilidad de usar Power Virtual Agents y lea sobre cómo elegir la solución de bot de chat adecuada.

Para obtener más información, consulte El futuro de la creación de bots.

C#

Para implementar la lógica de estos controladores, deberá reemplazar estos métodos en el bot como se muestra en la sección Controlador de actividad de ejemplo más adelante. En estos controladores no hay implementación base, por lo que se puede agregar la lógica que se desee en la invalidación.

Hay ciertas situaciones en las que puede desear invalidar el controlador de base, como por ejemplo cuando se guarda el estado al final de un turno. Al hacerlo, asegúrese de llamar en primer lugar a await base.OnTurnAsync(turnContext, cancellationToken); para asegurarse de que la implementación base de OnTurnAsync se ejecuta antes que el código adicional. Dicha implementación base es, entre otras cosas, la encargada de llamar al resto de los controladores de actividad como OnMessageActivityAsync.

JavaScript

ActivityHandler de JavaScript usa un emisor de eventos y un patrón de escucha. Por ejemplo, use el método onMessage para registrar un cliente de escucha de eventos para las actividades de mensaje. Puede registrar más de un cliente de escucha. Cuando el bot reciba una actividad de mensaje, el controlador de actividad verá esa actividad entrante y la enviará cada uno de los clientes de escucha de la actividad onMessage, en el orden en que se registraron.

Al crear el bot, la lógica del bot para controlar los mensajes y responderlos a mensajes se incluirá en los clientes de escucha onMessage. Del mismo modo, la lógica para controlar la incorporación de miembros se incluirá en los clientes de escucha onMembersAdded, a los que se llama cada vez que se agrega un miembro a la conversación. Para agregar estos clientes de escucha, se registran en el bot tal y como se muestra en la siguiente sección Lógica del bot. Incluya la lógica del bot de cada uno de estos clientes de escucha y, después, no olvide llamar a next() al final. Al llamar a next(), asegúrese de que se ejecuta el siguiente cliente de escucha.

Asegúrese de guardar el estado antes de que termine el turno. Para hacerlo, puede invalidar el método run del controlador de actividad y guardar el estado después de que se complete el método run del elemento primario.

No hay situaciones comunes en las que vaya a desear invalidar el controlador de turnos base, así que tenga cuidado si intenta hacerlo. Hay un controlador especial llamado onDialog. El controlador onDialog se ejecuta al final, después de que se hayan ejecutado el resto de los controladores, y no está asociado a un tipo de actividad determinado. Como con todos los controladores anteriores, asegúrese de llamar a next() para asegurarse de que concluye el resto del proceso.

Java

Para implementar la lógica de estos controladores, deberá reemplazar estos métodos en el bot como se muestra en la sección Controlador de actividad de ejemplo más adelante. Para todos estos controladores no hay implementación base, por lo que se puede agregar la lógica que se desee en la invalidación.

Hay ciertas situaciones en las que puede desear invalidar el controlador de base, como por ejemplo cuando se guarda el estado al final de un turno. Al hacerlo, asegúrese de, en primer lugar, llamar a super.onTurn(turnContext); para asegurarse de que la implementación base de onTurn se ejecuta antes que el código adicional. Dicha implementación base es, entre otras cosas, la encargada de llamar al resto de los controladores de actividad como onMessageActivity.

Python

Al crear el bot, la lógica del bot para controlar los mensajes y responderlos a mensajes se incluirá en dicho on_message_activitycontrolador. Del mismo modo, la lógica para controlar la incorporación de miembros se incluirá en el controlador on_members_added, al que se llama cada vez que se agrega un miembro a la conversación.

Por ejemplo, si el bot recibe una actividad de mensaje, el controlador de turnos vería dicha actividad entrante y la enviaría al controlador de actividad on_message_activity.

Para implementar la lógica de estos controladores, deberá reemplazar estos métodos en el bot como se muestra en la sección Controlador de actividad de ejemplo más adelante. En estos controladores no hay implementación base, por lo que se puede agregar la lógica que se desee en la invalidación.

Hay ciertas situaciones en las que puede desear invalidar el controlador de base, como por ejemplo cuando se guarda el estado al final de un turno. Al hacerlo, asegúrese de llamar en primer lugar a await super().on_turn(turnContext); para asegurarse de que la implementación base de on_turn se ejecuta antes que el código adicional. Dicha implementación base es, entre otras cosas, la encargada de llamar al resto de los controladores de actividad como on_message_activity.

Control de actividades

La lógica del bot procesa las actividades entrantes de uno o varios canales y genera actividades salientes como respuesta.

C#

La lógica principal del bot se define en el código del bot. Para implementar un bot como controlador de actividad, derive la clase de bot de ActivityHandler, que implementa la interfaz IBot. ActivityHandler define varios controladores para diferentes tipos de actividades, como OnMessageActivityAsync, y OnMembersAddedAsync. Estos métodos están protegidos, pero se pueden invalidar, ya que se derivan de ActivityHandler.

Los controladores definidos en ActivityHandler son:

Evento	Controlador	Descripción
Cualquier tipo de actividad recibida	OnTurnAsync	Llama a uno de los otros controladores, en función del tipo de actividad que reciba.
Actividad de mensaje recibida	OnMessageActivityAsync	Se invalida para controlar un actividad message.
Actividad de actualización de conversación recibida	OnConversationUpdateActivityAsync	En una actividad conversationUpdate, llama a un controlador si cualquiera de los miembros, que no sea el bot, se une a la conversación, o la abandona.
Miembros que no son el bot se han unido a la conversación	OnMembersAddedAsync	Se invalida para controlar a los miembros que se unen a una conversación.
Miembros que no son el bot ha abandonado la conversación	OnMembersRemovedAsync	Se invalida para controlar a los miembros que abandonan una conversación.
Actividad de evento recibida	OnEventActivityAsync	En una actividad event, llama a un controlador específico del tipo de evento.
Actividad de evento token-respuesta recibida	OnTokenResponseEventAsync	Se invalida para controlar los eventos de respuesta del token.
Actividad de evento no token-respuesta recibida	OnEventAsync	Se invalida para controlar otros tipos de eventos.
Actividad de reacción de mensajes recibida	OnMessageReactionActivityAsync	En una actividad messageReaction, llama a un controlador si se han agregado o quitado una o más reacciones de un mensaje.
Reacciones de mensajes agregadas a un mensaje	OnReactionsAddedAsync	Invalide esto para controlar las reacciones agregadas a un mensaje.
Reacciones de mensajes eliminadas de un mensaje	OnReactionsRemovedAsync	Invalide esto para controlar las reacciones eliminadas de un mensaje.
Actividad recibida de actualización de la instalación	OnInstallationUpdateActivityAsync	En una actividad installationUpdate, llama a un controlador en función de si el bot se instaló o desinstaló.
Bot instalado	OnInstallationUpdateAddAsync	Invalide esta opción para agregar lógica para cuando el bot esté instalado dentro de una unidad organizativa.
Bot desinstalado	OnInstallationUpdateRemoveAsync	Invalide esta opción para agregar lógica para cuando el bot esté desinstalado dentro de una unidad organizativa.
Otro tipo de actividad recibida	OnUnrecognizedActivityTypeAsync	Se invalida para controlar cualquier tipo de actividad que no se controle de otra forma.

Estos controladores tienen un objeto turnContext que proporciona información acerca de la actividad entrante, que corresponde a la solicitud HTTP entrante. Las actividades pueden ser de diversos tipos, por lo que cada controlador proporciona una actividad fuertemente tipada en su parámetro de contexto de turno; en la mayoría de los casos, OnMessageActivityAsync siempre se controlará y, por lo general, es el más común.

Al igual que en versiones anteriores de 4.x de este marco, también existe la opción de implementar el método público OnTurnAsync. Actualmente, la implementación base de este método controla la comprobación de errores y, después, llama a cada uno de los controladores específicos (por ejemplo, los dos que se definen en este ejemplo) en función del tipo de actividad entrante. En la mayoría de los casos, puede olvidar el método y usar los controladores individuales, pero si la situación requiere una implementación personalizada de OnTurnAsync, sigue siendo una opción.

Importante

Si invalida el método OnTurnAsync, deberá llamar a base.OnTurnAsync para obtener la implementación base para llamar a los restantes controladores de On<activity>Async, o bien llamar a los controladores personalmente. De lo contrario, no se llamará a dichos controladores y el código no se ejecutará.

JavaScript

La lógica principal del bot se define en el código del bot. Para implementar un bot como controlador de actividad, extienda ActivityHandler. ActivityHandler define varios eventos para diferentes tipos de actividades y se puede modificar el comportamiento del bot registrando clientes de escucha, como onMessage y onConversationUpdate.

Utilice estos métodos para registrar clientes de escucha para cada tipo de evento:

Evento	Método de registro	Descripción
Cualquier tipo de actividad recibida	onTurn	Registra un cliente de escucha para cuando se recibe cualquier actividad .
Actividad de mensaje recibida	onMessage	Registra un cliente de escucha para cuando se recibe una actividad message.
Actividad de actualización de conversación recibida	onConversationUpdate	Registra un cliente de escucha para cuando se recibe cualquier actividad conversationUpdate.
Miembros se unen a la conversación	onMembersAdded	Registra un cliente de escucha para cuando algún miembro se une a la conversación, incluido el bot.
Miembros abandonan la conversación	onMembersRemoved	Registra un cliente de escucha para cuando algún miembro sale de la conversación, incluido el bot.
Actividad de reacción de mensajes recibida	onMessageReaction	Registra un cliente de escucha para cuando se recibe cualquier actividad messageReaction.
Reacciones de mensajes agregadas a un mensaje	onReactionsAdded	Registra un cliente de escucha para cuando se agregan reacciones a un mensaje.
Reacciones de mensajes eliminadas de un mensaje	onReactionsRemoved	Registra un cliente de escucha para cuando se quitan reacciones de un mensaje.
Actividad de evento recibida	onEvent	Registra un cliente de escucha para cuando se recibe cualquier actividad event.
Actividad de evento token-respuesta recibida	onTokenResponseEvent	Registra un cliente de escucha para cuando se recibe cualquier evento tokens/response.
Actividad recibida de actualización de la instalación	onInstallationUpdate	Registra un cliente de escucha para cuando se recibe cualquier actividad installationUpdate.
Bot instalado	onInstallationUpdateAdd	Registra un agente de escucha para cuando el bot está instalado en una unidad organizativa.
Bot desinstalado	onInstallationUpdateRemove	Registra un agente de escucha para cuando el bot está desinstalado en una unidad organizativa.
Otro tipo de actividad recibida	onUnrecognizedActivityType	Registra un agente de escucha para cuando no hay definido un controlador para el tipo de actividad específico.
Los controladores de actividad se han completado	onDialog	Se llama después de que se hayan completado los controladores correspondientes.

Llame al parámetro de función next desde cada controlador para que el procesamiento continúe. Si no se llama a next, el procesamiento de la actividad finaliza.

Java

La lógica principal del bot se define en el código del bot. Para implementar un bot como controlador de actividad, derive la clase de bot de ActivityHandler, que implementa la interfaz Bot. ActivityHandler define varios controladores para diferentes tipos de actividades, como onMessageActivity, y onMembersAdded. Estos métodos están protegidos, pero se pueden invalidar, ya que se derivan de ActivityHandler.

Los controladores definidos en ActivityHandler son:

Evento	Controlador	Descripción
Cualquier tipo de actividad recibida	onTurn	Llama a uno de los otros controladores, en función del tipo de actividad que reciba.
Actividad de mensaje recibida	onMessageActivity	Se invalida para controlar un actividad message.
Actividad de actualización de conversación recibida	onConversationUpdateActivity	En una actividad conversationUpdate, llama a un controlador si cualquiera de los miembros, que no sea el bot, se une a la conversación, o la abandona.
Miembros que no son el bot se han unido a la conversación	onMembersAdded	Se invalida para controlar a los miembros que se unen a una conversación.
Miembros que no son el bot ha abandonado la conversación	onMembersRemoved	Se invalida para controlar a los miembros que abandonan una conversación.
Actividad de evento recibida	onEventActivity	En una actividad event, llama a un controlador específico del tipo de evento.
Actividad de evento token-respuesta recibida	onTokenResponseEvent	Se invalida para controlar los eventos de respuesta del token.
Actividad de evento no token-respuesta recibida	onEvent	Se invalida para controlar otros tipos de eventos.
Actividad de reacción de mensajes recibida	onMessageReactionActivity	En una actividad messageReaction, llama a un controlador si se han agregado o quitado una o más reacciones de un mensaje.
Reacciones de mensajes agregadas a un mensaje	onReactionsAdded	Invalide esto para controlar las reacciones agregadas a un mensaje.
Reacciones de mensajes eliminadas de un mensaje	onReactionsRemoved	Invalide esto para controlar las reacciones eliminadas de un mensaje.
Actividad recibida de actualización de la instalación	onInstallationUpdate	En una actividad installationUpdate, llama a un controlador en función de si el bot se instaló o desinstaló.
Bot instalado	onInstallationUpdateAdd	Invalide esta opción para agregar lógica para cuando el bot esté instalado dentro de una unidad organizativa.
Bot desinstalado	onInstallationUpdateRemove	Invalide esta opción para agregar lógica para cuando el bot esté desinstalado dentro de una unidad organizativa.
Otro tipo de actividad recibida	onUnrecognizedActivityType	Se invalida para controlar cualquier tipo de actividad que no se controle de otra forma.

Estos controladores tienen un objeto turnContext que proporciona información acerca de la actividad entrante, que corresponde a la solicitud HTTP entrante. Las actividades pueden ser de diversos tipos, por lo que cada controlador proporciona una actividad fuertemente tipada en su parámetro de contexto de turno; en la mayoría de los casos, onMessageActivity siempre se controlará y, por lo general, es el más común.

También existe la opción de implementar el método público onTurn. Actualmente, la implementación base de este método controla la comprobación de errores y, después, llama a cada uno de los controladores específicos (por ejemplo, los dos que se definen en este ejemplo) en función del tipo de actividad entrante. En la mayoría de los casos, puede olvidar el método y usar los controladores individuales, pero si la situación requiere una implementación personalizada de onTurn, sigue siendo una opción.

Importante

Si invalida el método onTurn, deberá llamar a super.onTurn para obtener la implementación base para llamar a los restantes controladores de on<activity>, o bien llamar a los controladores personalmente. De lo contrario, no se llamará a dichos controladores y el código no se ejecutará.

Python

La lógica principal del bot se define en el código del bot. Para implementar un bot como controlador de actividad, derive la clase bot de ActivityHandler, que a su vez deriva de la clase abstracta Bot. ActivityHandler define varios controladores para diferentes tipos de actividades, como on_message_activity y on_members_added. Estos métodos están protegidos, pero se pueden invalidar, ya que se derivan de ActivityHandler.

Los controladores definidos en ActivityHandler son:

Evento	Controlador	Descripción
Cualquier tipo de actividad recibida	on_turn	Llama a uno de los otros controladores, en función del tipo de actividad que reciba.
Actividad de mensaje recibida	on_message_activity	Se invalida para controlar un actividad message.
Actividad de actualización de conversación recibida	on_conversation_update_activity	En una actividad conversationUpdate, llama a un controlador si cualquiera de los miembros, que no sea el bot, se une a la conversación, o la abandona.
Miembros que no son el bot se han unido a la conversación	on_members_added_activity	Se invalida para controlar a los miembros que se unen a una conversación.
Miembros que no son el bot ha abandonado la conversación	on_members_removed_activity	Se invalida para controlar a los miembros que abandonan una conversación.
Actividad de evento recibida	on_event_activity	En una actividad event, llama a un controlador específico del tipo de evento.
Actividad de evento token-respuesta recibida	on_token_response_event	Se invalida para controlar los eventos de respuesta del token.
Actividad de evento no token-respuesta recibida	on_event_activity	Se invalida para controlar otros tipos de eventos.
Actividad de reacción de mensajes recibida	on_message_reaction_activity	En una actividad messageReaction, llama a un controlador si se han agregado o quitado una o más reacciones de un mensaje.
Reacciones de mensajes agregadas a un mensaje	on_reactions_added	Invalide esto para controlar las reacciones agregadas a un mensaje.
Reacciones de mensajes eliminadas de un mensaje	on_reactions_removed	Invalide esto para controlar las reacciones eliminadas de un mensaje.
Actividad recibida de actualización de la instalación	on_installation_update	En una actividad installationUpdate, llama a un controlador en función de si el bot se instaló o desinstaló.
Bot instalado	on_installation_update_add	Invalide esta opción para agregar lógica para cuando el bot esté instalado dentro de una unidad organizativa.
Bot desinstalado	on_installation_update_remove	Invalide esta opción para agregar lógica para cuando el bot esté desinstalado dentro de una unidad organizativa.
Otro tipo de actividad recibida	on_unrecognized_activity_type	Se invalida para controlar cualquier tipo de actividad que no se controle de otra forma.

Estos controladores tienen un objeto turn_context que proporciona información acerca de la actividad entrante, que corresponde a la solicitud HTTP entrante. Las actividades pueden ser de diversos tipos, por lo que cada controlador proporciona una actividad fuertemente tipada en su parámetro de contexto de turno; en la mayoría de los casos, on_message_activity siempre se controlará y, por lo general, es el más común.

Al igual que en versiones anteriores de 4.x de este marco, también existe la opción de implementar el método público on_turn. Actualmente, la implementación base de este método controla la comprobación de errores y, después, llama a cada uno de los controladores específicos (por ejemplo, los dos que se definen en este ejemplo) en función del tipo de actividad entrante. En la mayoría de los casos, puede olvidar el método y usar los controladores individuales, pero si la situación requiere una implementación personalizada de on_turn, sigue siendo una opción.

Importante

Si invalida el método on_turn, deberá llamar a super().on_turn para obtener la implementación base para llamar a los restantes controladores de on_<activity>, o bien llamar a los controladores personalmente. De lo contrario, no se llamará a dichos controladores y el código no se ejecutará.

Controlador de actividad de ejemplo

Por ejemplo, puede controlar en los miembros agregados para dar la bienvenida a los usuarios a una conversación y controlar en mensaje para devolver los mensajes que envían al 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}")
        )

Pasos siguientes

• El canal de Microsoft Teams presenta algunas actividades específicas de Teams que el bot tendrá que admitir para trabajar correctamente con Teams. Para comprender los conceptos clave del desarrollo de bots para Microsoft Teams, consulte Cómo funcionan los bots de Microsoft Teams.
• Un controlador de actividad es una buena manera de diseñar un bot que no necesita realizar un seguimiento del estado conversacional entre turnos. La biblioteca de diálogos proporciona maneras de administrar una conversación de larga duración con el usuario.