Conversaciones controladas por eventos mediante 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. En segundo plano, el controlador de turnos del bot llama al controlador de actividad individual para cualquier tipo de actividad que haya recibido.

Por ejemplo, si el bot recibe una actividad de mensaje, el controlador de turnos vería esa actividad entrante y la enviaría al controlador de actividad de actividad del mensaje . Al compilar el bot, la lógica del bot para controlar y responder a los mensajes se incluirá en el controlador de actividad del mensaje . Del mismo modo, la lógica para controlar los miembros que se agregan a la conversación irá en el controlador agregado de miembros , 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 Java y Python de Bot Framework se están retirando con la compatibilidad final a largo plazo que finaliza en noviembre de 2023. Solo se realizarán correcciones de errores y seguridad críticas en este repositorio. Los bots existentes creados con estos SDK seguirán funcionando.

Para el nuevo desarrollo de bots, considere la posibilidad de usar Power Virtual Agents. Para más información, consulte El futuro de la compilación de bots.

Para implementar la lógica de estos controladores, invalidará estos métodos en el bot, como en la sección controlador de actividad de ejemplo siguiente. Para cada uno de estos controladores, no hay ninguna implementación base, por lo que basta con agregar la lógica que desee en la invalidación.

Hay ciertas situaciones en las que querrá invalidar el controlador de turnos base, como guardar 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.

Control de actividades

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

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 IBot interfaz . ActivityHandler define varios controladores para distintos tipos de actividades, como OnMessageActivityAsync, y OnMembersAddedAsync. Estos métodos están protegidos, pero se pueden invalidar, ya que se deriva 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 de actualización de instalación recibida OnInstallationUpdateActivityAsync En una installationUpdate actividad, 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 se desinstale 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.

Como en las versiones anteriores de 4.x de este marco, también hay la opción de implementar el método OnTurnAsyncpúblico . 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 dejar ese método solo y usar los controladores individuales, pero si su 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á.

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 el mensaje para devolver mensajes que envían al 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);
            }
        }
    }
}

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.