Conversations basées sur les événements à l'aide d'un gestionnaire d'activités

S'APPLIQUE À : (SDK) v4

Un gestionnaire d'activités est un moyen basé sur les événements d'organiser la logique conversationnelle pour votre bot. Chaque type ou sous-type d'activité représente un type différent d'événement conversationnel. Sous couvert, le gestionnaire de tour du bot appelle le gestionnaire d'activité individuel pour le type d'activité qu'il a reçu.

Par exemple, si le bot reçoit une activité de message, le gestionnaire de tour verra cette activité entrante et l'enverra au gestionnaire d'activité sur activité de message. Lors de la construction de votre bot, la logique de gestion et de réponse aux messages sera placée dans ce gestionnaire d'activité sur activité de message. De même, votre logique de gestion des membres ajoutés à la conversation sera intégrée à votre gestionnaire sur les membres ajoutés, qui est appelé chaque fois qu'un membre est ajouté à la conversation.

Pour d'autres façons d'organiser la logique du bot, consultez la section Logique du bot dans la rubrique Fonctionnement des bots.

Remarque

Les kits de développement logiciel (SDK) JavaScript, C# et Python bot Framework continueront d'être pris en charge. Toutefois, le kit de développement logiciel (SDK) Java est mis hors service avec une prise en charge finale à long terme se terminant en novembre 2023. Seuls les correctifs de sécurité et de bogues critiques au sein de ce référentiel seront entrepris.

Les bots existants créés avec le kit de développement logiciel (SDK) Java continueront de fonctionner.

Pour la nouvelle génération de bots, envisagez d'utiliser Power Virtual Agents et découvrez comment choisir la solution de chatbot appropriée.

Pour plus d'informations, consultez L'avenir de la construction de bots.

C#

Pour implémenter votre logique pour ces gestionnaires, vous allez remplacer ces méthodes dans votre bot, comme dans l'exemple de gestionnaire d'activité ci-dessous. Comme aucun de ces gestionnaires ne dispose d'une implémentation de base, ajoutez simplement la logique que vous voulez dans votre remplacement.

Il peut arriver que vous souhaitiez remplacer le gestionnaire de tours standard, comme l'enregistrement de l'état à la fin d'un tour. Lors de cette opération, veillez à appeler en premier await base.OnTurnAsync(turnContext, cancellationToken); pour vous assurer que l’implémentation de base de OnTurnAsync est exécutée avant votre code supplémentaire. Cette implémentation de base est, entre autres choses, chargée d’appeler le reste des gestionnaires d’activités, tels que OnMessageActivityAsync.

JavaScript

Le ActivityHandler JavaScript utilise un émetteur d’événement et un modèle d’écouteur. Par exemple, utilisez la méthode onMessage afin d’inscrire un écouteur d’événements pour les activités de message. Vous pouvez inscrire plusieurs écouteurs. Lorsque le bot reçoit une activité de message, le gestionnaire d’activités voit cette activité entrante et l’envoie à chacun des écouteurs d’activités onMessage, dans l’ordre dans lequel ils ont été inscrits.

Lors de la création du bot, votre logique de bot pour la gestion des messages et la réponse à ceux-ci est insérée dans les écouteurs onMessage. De la même façon, votre logique pour la gestion des membres ajoutés à la conversation est insérée dans vos écouteurs onMembersAdded, qui sont appelés chaque fois qu’un membre est ajouté à la conversation. Pour ajouter ces écouteurs, vous devez les inscrire dans votre bot comme indiqué dans la section Logique du bot ci-dessous. Pour chaque écouteur, ajoutez votre logique de bot, puis veillez à appeler next() à la fin. En appelant next(), vous êtes certain que l'écouteur suivant est exécuté.

Veillez à enregistrer l’état avant la fin du tour. Pour ce faire, vous pouvez remplacer la méthode run du gestionnaire d’activités et enregistrer l’état une fois que l’exécution de la méthode run du parent est terminée.

Généralement, il n'existe pas de situation qui justifie de vouloir remplacer le gestionnaire de tours standard, alors faites preuve de prudence si vous tentez de le faire. Il existe un gestionnaire spécial appelé onDialog. Le gestionnaire onDialog s'exécute à la fin, après l'exécution des autres gestionnaires, et n'est pas lié à un certain type d'activité. Comme pour tous les gestionnaires ci-dessus, veillez à appeler next() pour garantir la clôture du reste du processus.

Java

Pour implémenter votre logique pour ces gestionnaires, vous allez remplacer ces méthodes dans votre bot, comme dans l'exemple de gestionnaire d'activité ci-dessous. Il n'y a pas d'implémentation de base pour chacun de ces gestionnaires, donc ajoutez la logique que vous voulez dans votre remplacement.

Il peut arriver que vous souhaitiez remplacer le gestionnaire de tours standard, comme l'enregistrement de l'état à la fin d'un tour. Lors de cette opération, veillez à appeler en premier super.onTurn(turnContext); pour vous assurer que l'implémentation de base de onTurn est exécutée avant votre code supplémentaire. Cette implémentation de base est, entre autres choses, chargée d’appeler le reste des gestionnaires d’activités, tels que onMessageActivity.

Python

Lors de la création du bot, votre logique de bot pour la gestion des messages et leur réponse passe dans ce gestionnaire on_message_activity. De la même façon, votre logique pour la gestion des membres ajoutés à la conversation va dans votre gestionnaire on_members_added, qui est appelé chaque fois qu’un membre est ajouté à la conversation.

Par exemple, si le bot reçoit une activité de message, le gestionnaire de tours voit cette activité entrante et l’envoie au gestionnaire d’activités on_message_activity.

Pour implémenter votre logique pour ces gestionnaires, vous allez remplacer ces méthodes dans votre bot, comme dans l'exemple de gestionnaire d'activité ci-dessous. Comme aucun de ces gestionnaires ne dispose d'une implémentation de base, ajoutez simplement la logique que vous voulez dans votre remplacement.

Il peut arriver que vous souhaitiez remplacer le gestionnaire de tours standard, comme l'enregistrement de l'état à la fin d'un tour. Lors de cette opération, veillez à appeler en premier await super().on_turn(turnContext); pour vous assurer que l’implémentation de base de on_turn est exécutée avant votre code supplémentaire. Cette implémentation de base est, entre autres choses, chargée d’appeler le reste des gestionnaires d’activités, tels que on_message_activity.

Gestion des activités

La logique du bot traite les activités entrantes à partir d’un ou de plusieurs canaux, et génère des activités sortantes en réponse.

C#

La logique principale du bot est définie dans le code du bot. Pour implémenter un bot en tant que gestionnaire d'activités, dérivez votre classe de bot à partir de ActivityHandlerlaquelle implémente l'interface IBot. ActivityHandler définit divers gestionnaires pour différents types d'activités, comme OnMessageActivityAsync et OnMembersAddedAsync. Ces méthodes sont protégées, mais peuvent être remplacées dans la mesure où nous dérivons de ActivityHandler.

Les gestionnaires définis dans ActivityHandler sont :

Événement	Handler	Description
Tout type d’activité reçu	OnTurnAsync	Appelle l’un des autres gestionnaires, selon le type d’activité reçu.
Activité de message reçue	OnMessageActivityAsync	Remplacer celui-ci pour gérer une activité message.
Activité reçue de mise à jour de conversation	OnConversationUpdateActivityAsync	Sur une activité conversationUpdate, appelle un gestionnaire si des membres autres que le bot ont rejoint ou quitté la conversation.
Des membres autres que le bot ont rejoint la conversation	OnMembersAddedAsync	Substituer celui-ci pour gérer les membres se joignant à une conversation.
Des membres autres que le bot ont quitté la conversation	OnMembersRemovedAsync	Substituer celui-ci pour gérer les membres quittant une conversation.
Activité d’événement reçue	OnEventActivityAsync	Sur une activité event, appelle un gestionnaire spécifique au type d’événement.
Activité reçue d’événement de réponse de jeton	OnTokenResponseEventAsync	Substituer celui-ci pour gérer les événements de réponse de jeton.
Activité reçue d’événement de réponse autre que celle du jeton	OnEventAsync	Substituer celui-ci pour gérer d’autres types d’événements.
Activité de réaction à un message reçue	OnMessageReactionActivityAsync	Sur une activité messageReaction, appelle un gestionnaire si une ou plusieurs réactions ont été ajoutées ou supprimées d’un message.
Réactions de message ajoutées à un message	OnReactionsAddedAsync	Remplacez ceci pour gérer les réactions ajoutées à un message.
Réactions de message supprimées d’un message	OnReactionsRemovedAsync	Remplacez ceci pour gérer les réactions supprimées d’un message.
Activité de mise à jour de l'installation reçue	OnInstallationUpdateActivityAsync	Sur une activité installationUpdate, appelle un gestionnaire selon que le bot a été installé ou désinstallé.
Bot installé	OnInstallationUpdateAddAsync	Remplacez cette option pour ajouter une logique lorsque le bot est installé dans une unité d'organisation.
Bot désinstallé	OnInstallationUpdateRemoveAsync	Remplacez cette option pour ajouter une logique lorsque le bot est désinstallé dans une unité d'organisation.
Autre type d’activité reçu	OnUnrecognizedActivityTypeAsync	Substituer celui-ci pour gérer tout type d’activité non géré autrement.

Ces différents gestionnaires disposent de turnContext qui fournit des informations sur l’activité entrante ; celle-ci correspond à la requête HTTP entrante. Les activités pouvant être de différents types, chaque gestionnaire fournit donc une activité fortement typée dans son paramètre de contexte de tour ; dans la plupart des cas, OnMessageActivityAsync est toujours géré, et il est généralement le plus courant.

Comme dans les précédentes versions 4.x de ce framework, il existe également la possibilité d'implémenter la méthode publique OnTurnAsync. Actuellement, l’implémentation de base de cette méthode gère la vérification des erreurs, et appelle ensuite chacun des gestionnaires spécifiques (par exemple, les deux que nous définissons dans cet exemple) selon le type d’activité entrante. Bien souvent, vous pouvez ignorer cette méthode et utiliser les gestionnaires individuels, mais si votre situation nécessite une implémentation personnalisée de OnTurnAsync, elle demeure une alternative.

Important

Si jamais vous substituez la méthode OnTurnAsync, vous devez appeler base.OnTurnAsync pour obtenir que l’implémentation de base appelle tous les autres gestionnaires On<activity>Async, ou appeler ces gestionnaires vous-même. Sinon, ces gestionnaires ne sont pas appelés, et ce code n’est pas exécuté.

JavaScript

La logique principale du bot est définie dans le code du bot. Pour implémenter un bot en tant que gestionnaire d'activités, étendez ActivityHandler. ActivityHandler définit divers événements pour différents types d'activités, sachant que vous pouvez modifier le comportement de votre bot en inscrivant des écouteurs d'événements, par exemple avec onMessage et onConversationUpdate.

Utilisez ces méthodes pour inscrire des écouteurs pour chaque type d’événement :

Événement	Méthode d’inscription	Description
Tout type d’activité reçu	onTurn	Inscrit un écouteur pour toutes les fois où toute activité est reçue.
Activité de message reçue	onMessage	Inscrit un écouteur pour toutes les fois où une activité message est reçue.
Activité reçue de mise à jour de conversation	onConversationUpdate	Inscrit un écouteur pour toutes les fois où toute activité conversationUpdate est reçue.
Des membres ont rejoint la conversation	onMembersAdded	Inscrit un écouteur pour toutes les fois où des membres ont rejoint la conversation, notamment le bot.
Des membres ont quitté la conversation	onMembersRemoved	Inscrit un écouteur pour toutes les fois où des membres ont quitté la conversation, notamment le bot.
Activité de réaction à un message reçue	onMessageReaction	Inscrit un écouteur pour toutes les fois où toute activité messageReaction est reçue.
Réactions de message ajoutées à un message	onReactionsAdded	Inscrit un écouteur pour toutes les fois où des réactions sont ajoutées à un message.
Réactions de message supprimées d’un message	onReactionsRemoved	Inscrit un écouteur pour toutes les fois où des réactions sont supprimées d’un message.
Activité d’événement reçue	onEvent	Inscrit un écouteur pour toutes les fois où toute activité event est reçue.
Activité reçue d’événement de réponse de jeton	onTokenResponseEvent	Inscrit un écouteur pour toutes les fois où un événement tokens/response est reçu.
Activité de mise à jour de l'installation reçue	onInstallationUpdate	Inscrit un écouteur pour toutes les fois où toute activité installationUpdate est reçue.
Bot installé	onInstallationUpdateAdd	Inscrit un écouteur lorsque le bot est installé dans une unité d'organisation.
Bot désinstallé	onInstallationUpdateRemove	Inscrit un écouteur lorsque le bot est désinstallé dans une unité d'organisation.
Autre type d’activité reçu	onUnrecognizedActivityType	Inscrit un écouteur pour toutes les fois où un gestionnaire pour le type d'activité spécifique n'est pas défini.
Les gestionnaires d’activités ont terminé	onDialog	Appelé après que les gestionnaires applicables ont terminé.

Appelez la fonction de continuation next de chaque gestionnaire pour permettre la poursuite du traitement. Si next n'est pas appelé, le traitement de l'activité se termine.

Java

La logique principale du bot est définie dans le code du bot. Pour implémenter un bot en tant que gestionnaire d'activités, dérivez votre classe de bot à partir de ActivityHandlerlaquelle implémente l'interface Bot. ActivityHandler définit divers gestionnaires pour différents types d'activités, comme onMessageActivity et onMembersAdded. Ces méthodes sont protégées, mais peuvent être remplacées dans la mesure où nous dérivons de ActivityHandler.

Les gestionnaires définis dans ActivityHandler sont :

Événement	Handler	Description
Tout type d’activité reçu	onTurn	Appelle l’un des autres gestionnaires, selon le type d’activité reçu.
Activité de message reçue	onMessageActivity	Remplacer celui-ci pour gérer une activité message.
Activité reçue de mise à jour de conversation	onConversationUpdateActivity	Sur une activité conversationUpdate, appelle un gestionnaire si des membres autres que le bot ont rejoint ou quitté la conversation.
Des membres autres que le bot ont rejoint la conversation	onMembersAdded	Substituer celui-ci pour gérer les membres se joignant à une conversation.
Des membres autres que le bot ont quitté la conversation	onMembersRemoved	Substituer celui-ci pour gérer les membres quittant une conversation.
Activité d’événement reçue	onEventActivity	Sur une activité event, appelle un gestionnaire spécifique au type d’événement.
Activité reçue d’événement de réponse de jeton	onTokenResponseEvent	Substituer celui-ci pour gérer les événements de réponse de jeton.
Activité reçue d’événement de réponse autre que celle du jeton	onEvent	Substituer celui-ci pour gérer d’autres types d’événements.
Activité de réaction à un message reçue	onMessageReactionActivity	Sur une activité messageReaction, appelle un gestionnaire si une ou plusieurs réactions ont été ajoutées ou supprimées d’un message.
Réactions de message ajoutées à un message	onReactionsAdded	Remplacez ceci pour gérer les réactions ajoutées à un message.
Réactions de message supprimées d’un message	onReactionsRemoved	Remplacez ceci pour gérer les réactions supprimées d’un message.
Activité de mise à jour de l'installation reçue	onInstallationUpdate	Sur une activité installationUpdate, appelle un gestionnaire selon que le bot a été installé ou désinstallé.
Bot installé	onInstallationUpdateAdd	Remplacez cette option pour ajouter une logique lorsque le bot est installé dans une unité d'organisation.
Bot désinstallé	onInstallationUpdateRemove	Remplacez cette option pour ajouter une logique lorsque le bot est désinstallé dans une unité d'organisation.
Autre type d’activité reçu	onUnrecognizedActivityType	Substituer celui-ci pour gérer tout type d’activité non géré autrement.

Ces différents gestionnaires disposent de turnContext qui fournit des informations sur l’activité entrante ; celle-ci correspond à la requête HTTP entrante. Les activités pouvant être de différents types, chaque gestionnaire fournit donc une activité fortement typée dans son paramètre de contexte de tour ; dans la plupart des cas, onMessageActivity est toujours géré, et il est généralement le plus courant.

Il existe également la possibilité d'implémenter la méthode publique onTurn. Actuellement, l’implémentation de base de cette méthode gère la vérification des erreurs, et appelle ensuite chacun des gestionnaires spécifiques (par exemple, les deux que nous définissons dans cet exemple) selon le type d’activité entrante. Bien souvent, vous pouvez ignorer cette méthode et utiliser les gestionnaires individuels, mais si votre situation nécessite une implémentation personnalisée de onTurn, elle demeure une alternative.

Important

Si jamais vous substituez la méthode onTurn, vous devez appeler super.onTurn pour obtenir que l’implémentation de base appelle tous les autres gestionnaires on<activity>, ou appeler ces gestionnaires vous-même. Sinon, ces gestionnaires ne sont pas appelés, et ce code n’est pas exécuté.

Python

La logique principale du bot est définie dans le code du bot. Pour implémenter un bot en tant que gestionnaire d'activité, vous devez dériver votre classe de bot ActivityHandler, qui dérive à son tour de la classe abstraite Bot. ActivityHandler définit divers gestionnaires pour différents types d'activités, comme on_message_activity et on_members_added. Ces méthodes sont protégées, mais peuvent être remplacées dans la mesure où nous dérivons de ActivityHandler.

Les gestionnaires définis dans ActivityHandler sont :

Événement	Handler	Description
Tout type d’activité reçu	on_turn	Appelle l’un des autres gestionnaires, selon le type d’activité reçu.
Activité de message reçue	on_message_activity	Remplacer celui-ci pour gérer une activité message.
Activité reçue de mise à jour de conversation	on_conversation_update_activity	Sur une activité conversationUpdate, appelle un gestionnaire si des membres autres que le bot ont rejoint ou quitté la conversation.
Des membres autres que le bot ont rejoint la conversation	on_members_added_activity	Substituer celui-ci pour gérer les membres se joignant à une conversation.
Des membres autres que le bot ont quitté la conversation	on_members_removed_activity	Substituer celui-ci pour gérer les membres quittant une conversation.
Activité d’événement reçue	on_event_activity	Sur une activité event, appelle un gestionnaire spécifique au type d’événement.
Activité reçue d’événement de réponse de jeton	on_token_response_event	Substituer celui-ci pour gérer les événements de réponse de jeton.
Activité reçue d’événement de réponse autre que celle du jeton	on_event_activity	Substituer celui-ci pour gérer d’autres types d’événements.
Activité de réaction à un message reçue	on_message_reaction_activity	Sur une activité messageReaction, appelle un gestionnaire si une ou plusieurs réactions ont été ajoutées ou supprimées d’un message.
Réactions de message ajoutées à un message	on_reactions_added	Remplacez ceci pour gérer les réactions ajoutées à un message.
Réactions de message supprimées d’un message	on_reactions_removed	Remplacez ceci pour gérer les réactions supprimées d’un message.
Activité de mise à jour de l'installation reçue	on_installation_update	Sur une activité installationUpdate, appelle un gestionnaire selon que le bot a été installé ou désinstallé.
Bot installé	on_installation_update_add	Remplacez cette option pour ajouter une logique lorsque le bot est installé dans une unité d'organisation.
Bot désinstallé	on_installation_update_remove	Remplacez cette option pour ajouter une logique lorsque le bot est désinstallé dans une unité d'organisation.
Autre type d’activité reçu	on_unrecognized_activity_type	Substituer celui-ci pour gérer tout type d’activité non géré autrement.

Ces différents gestionnaires disposent de turn_context qui fournit des informations sur l’activité entrante ; celle-ci correspond à la requête HTTP entrante. Les activités pouvant être de différents types, chaque gestionnaire fournit donc une activité fortement typée dans son paramètre de contexte de tour ; dans la plupart des cas, on_message_activity est toujours géré, et il est généralement le plus courant.

Comme dans les précédentes versions 4.x de ce framework, il existe également la possibilité d'implémenter la méthode publique on_turn. Actuellement, l’implémentation de base de cette méthode gère la vérification des erreurs, et appelle ensuite chacun des gestionnaires spécifiques (par exemple, les deux que nous définissons dans cet exemple) selon le type d’activité entrante. Bien souvent, vous pouvez ignorer cette méthode et utiliser les gestionnaires individuels, mais si votre situation nécessite une implémentation personnalisée de on_turn, elle demeure une alternative.

Important

Si jamais vous substituez la méthode on_turn, vous devez appeler super().on_turn pour obtenir que l’implémentation de base appelle tous les autres gestionnaires on_<activity>, ou appeler ces gestionnaires vous-même. Sinon, ces gestionnaires ne sont pas appelés, et ce code n’est pas exécuté.

Exemple de gestionnaire d'activités

Par exemple, vous pouvez gérer sur membres ajoutés pour accueillir les utilisateurs dans une conversation et gérer sur message pour renvoyer les messages qu'ils envoient au 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}")
        )

Étapes suivantes

• Le canal Microsoft Teams présente certaines activités spécifiques à Teams que votre bot devra prendre en charge pour bien fonctionner avec Teams. Pour comprendre les concepts clés du développement de bots pour Microsoft Teams, consultez Fonctionnement des bots Microsoft Teams.
• Un gestionnaire d'activités est un bon moyen de concevoir un bot qui n'a pas besoin de suivre l'état conversationnel entre les tours. La bibliothèque des dialogues permet de gérer une conversation de longue durée avec l'utilisateur.