Déboguer un bot avec un intergiciel d’inspection

S’APPLIQUE À : SDK v4

Cet article explique comment déboguer un bot à l’aide d’un intergiciel d’inspection. Cette fonctionnalité permet à l’émulateur Bot Framework Emulator de déboguer le trafic transitant par le bot, et d’inspecter l’état actuel du bot. Vous pouvez utiliser un message de suivi pour envoyer des données à Emulator, puis inspecter l’état de votre bot dans n’importe quel tour de la conversation.

Nous utilisons un EchoBot généré localement à l’aide de Bot Framework v4 dans l’Aide au démarrage Créer un bot pour montrer comment déboguer et inspecter l’état du message du bot. Vous pouvez aussi Déboguer un bot à l’aide de l’IDE ou le Déboguer avec Bot Framework Emulator, mais pour déboguer l’état, vous devez ajouter l’intergiciel d’inspection à votre bot. Les exemples de bot d’inspection sont disponibles pour C#, JavaScript, Java et Python.

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 progressivement 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 appliqués.

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 Les futures versions de bot.

Prérequis

• Connaissance des intergiciels de bots et de la gestion de l’état
• Connaissance de la façon de déboguer un bot de kit de développement logiciel et tester et déboguer avec Emulator
• Une installation de Bot Framework Emulator
• Une installation de ngrok (si vous souhaitez déboguer un bot configuré dans Azure pour utiliser des canaux supplémentaires)
• Une copie de l'échantillon d’inspection du bot pour C#, JavaScript, Java ou Python

Mettre à jour Emulator vers la dernière version

Avant d’utiliser l’intergiciel d’inspection du bot pour déboguer votre bot, mettez à jour Emulator vers la version 4.5 ou ultérieure. Vérifiez la dernière version des mises à jour.

Pour vérifier la version de votre Emulator, sélectionnez Aide, puis À propos de dans le menu. La version actuelle de votre Emulator s’affiche alors.

Mettre à jour le code de votre bot

C#

L’état d’inspection et l’intergiciel d’inspection sont configurés dans le fichier Startup.cs puis utilisés par l’adaptateur.

Startup.cs

});

services.AddSingleton<ConversationState>();

// Create the Bot Framework Authentication to be used with the Bot Adapter.

AdapterWithInspection.cs

{
    public class AdapterWithInspection : CloudAdapter
    {
        public AdapterWithInspection(BotFrameworkAuthentication auth, IConfiguration configuration, InspectionState inspectionState, UserState userState, ConversationState conversationState, ILogger<IBotFrameworkHttpAdapter> logger)
            : base(auth, logger)
        {
            // Inspection needs credentials because it will be sending the Activities and User and Conversation State to the emulator
            var credentials = new MicrosoftAppCredentials(configuration["MicrosoftAppId"], configuration["MicrosoftAppPassword"]);

            Use(new InspectionMiddleware(inspectionState, userState, conversationState, credentials));

            OnTurnError = async (turnContext, exception) =>
            {
                // Log any leaked exception from the application.
                logger.LogError(exception, $"[OnTurnError] unhandled error : {exception.Message}");

                // Send a message to the user
                await turnContext.SendActivityAsync("The bot encountered an error or bug.");
                await turnContext.SendActivityAsync("To continue to run this bot, please fix the bot source code.");

                // Send a trace activity, which will be displayed in the Bot Framework Emulator
                await turnContext.TraceActivityAsync("OnTurnError Trace", exception.Message, "https://www.botframework.com/schemas/error", "TurnError");
            };
        }

Mettez à jour la classe de bot dans le fichier EchoBot.cs.

EchoBot.cs

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    var conversationStateProp = _conversationState.CreateProperty<CustomState>("customState");
    var convProp = await conversationStateProp.GetAsync(turnContext, () => new CustomState { Value = 0 }, cancellationToken);

    var userStateProp = _userState.CreateProperty<CustomState>("customState");
    var userProp = await userStateProp.GetAsync(turnContext, () => new CustomState { Value = 0 }, cancellationToken);

    await turnContext.SendActivityAsync(MessageFactory.Text($"Echo: {turnContext.Activity.Text} conversation state: {convProp.Value} user state: {userProp.Value}"), cancellationToken);

    convProp.Value++;
    userProp.Value++;
}

JavaScript

Avant de mettre à jour le code de votre bot, mettez à jour ses packages vers les versions les plus récentes en exécutant la commande suivante dans votre terminal :

npm install --save botbuilder@latest

Vous devez ensuite mettre à jour le code de votre bot JavaScript comme suit. Vous pouvez obtenir plus d’informations ici : Mettre à jour le code de votre bot ou reportez-vous à l’échantillon Inspection d’intergiciel sur GitHub.

index.js

Configurez l’état d’inspection et ajoutez l’intergiciel d’inspection à l’adaptateur dans le fichier index.js.

// Import required bot services.
// See https://aka.ms/bot-services to learn more about the different parts of a bot.
const {
    CloudAdapter,
    ConversationState,
    InspectionMiddleware,
    InspectionState,
    MemoryStorage,
    UserState,
    ConfigurationBotFrameworkAuthentication
} = require('botbuilder');

const { MicrosoftAppCredentials } = require('botframework-connector');

const botFrameworkAuthentication = new ConfigurationBotFrameworkAuthentication(process.env);

// Create adapter.
// See https://aka.ms/about-bot-adapter to learn more about how bots work.
const adapter = new CloudAdapter(botFrameworkAuthentication);

// Create the Storage provider and the various types of BotState.
const memoryStorage = new MemoryStorage();
const inspectionState = new InspectionState(memoryStorage);
const userState = new UserState(memoryStorage);
const conversationState = new ConversationState(memoryStorage);

// Create and add the InspectionMiddleware to the adapter.
adapter.use(new InspectionMiddleware(inspectionState, userState, conversationState, new MicrosoftAppCredentials(process.env.MicrosoftAppId, process.env.MicrosoftAppPassword)));

// Catch-all for errors.
adapter.onTurnError = async (context, error) => {
    // This check writes out errors to console log .vs. app insights.
    // NOTE: In production environment, you should consider logging this to Azure
    //       application insights. See https://aka.ms/bottelemetry for telemetry
    //       configuration instructions.
    console.error(`\n [onTurnError] unhandled error: ${ error }`);

bot.js

Mettez à jour la classe de bot dans le fichier bot.js.

this.onMessage(async (context, next) => {
    // get the state objects
    const testConversationState = await this.conversationStateAccessor.get(context, { count: 0 });
    const testUserState = await this.userStateAccessor.get(context, { count: 0 });

    // print the current state to the reply to show we are incrementing it
    await context.sendActivity(`You said '${ context.activity.text }' conversation-state: ${ testConversationState.count } user-state: ${ testUserState.count }`);

    // do the actual increment
    testConversationState.count++;
    testUserState.count++;

    // By calling next() you ensure that the next BotHandler is run.
    await next();
});

Java

Configurez l’état d’inspection et ajoutez l’intergiciel d’inspection à l’adaptateur dans le fichier Application.java. L’état d’inspection est défini en fournissant un nouveau Spring @Bean pour fournir le BotFrameworkHttpAdapter défini pour être @Primary afin qu’il remplace le BotFrameworkHttpAdapter par défaut fourni par la classe de base BotDependencyConfiguration. Consultez la mise à jour du code ci-dessous ou reportez-vous à l’échantillon intergiciel d’inspection sur GitHub.

Application.java

/**
 * Create an adapter with InspectionMiddleware.
 *
 * <p>
 * NOTE: This is marked as @Primary to override the default Bean.
 * </p>
 *
 * @param configuration     The configuration.
 *                          {@link BotDependencyConfiguration#getConfiguration()}
 * @param inspectionState   The InspectionState.
 *                          {@link BotDependencyConfiguration#getInspectionState(Storage)}
 * @param userState         The UserState.
 *                          {@link BotDependencyConfiguration#getUserState(Storage)}
 * @param conversationState The ConversationState.
 *                          {@link BotDependencyConfiguration#getConversationState(Storage)}
 * @return An AdapterWithInspection object.
 */
@Bean
@Primary
public BotFrameworkHttpAdapter getInspectionBotFrameworkHttpAdapter(
    Configuration configuration,
    InspectionState inspectionState,
    UserState userState,
    ConversationState conversationState
) {
    return new AdapterWithInspection(
        configuration,
        inspectionState,
        userState,
        conversationState
    );
}

AdapterWithInspection est implémenté dans le cadre du package com.microsoft.bot.integration et peut être examiné à partir du code source du Kit de développement logiciel (SDK) Java.

Mettez à jour la classe de bot dans le fichier EchoBot.java.

EchoBot.java

@Override
protected CompletableFuture<Void> onMessageActivity(TurnContext turnContext) {
    // Get state data from ConversationState.
    StatePropertyAccessor<CustomState> dataAccessor =
        conversationState.createProperty("customState");
    CompletableFuture<CustomState> convStateFuture =
        dataAccessor.get(turnContext, CustomState::new);

    // Get profile from UserState.
    StatePropertyAccessor<CustomState> profileAccessor =
        userState.createProperty("customState");
    CompletableFuture<CustomState> userStateFuture =
        profileAccessor.get(turnContext, CustomState::new);

    return convStateFuture.thenCombine(userStateFuture, (convProp, userProp) -> {
        convProp.setValue(convProp.getValue() + 1);
        userProp.setValue(userProp.getValue() + 1);

        return turnContext.sendActivity(
            MessageFactory.text(
                String.format(
                    "Echo: %s conversation state %d user state %d",
                    turnContext.getActivity().getText(), convProp.getValue(),
                    userProp.getValue()
                )
            )
        );
    }).thenApply(resourceResponse -> null);
}

Python

Avant de mettre à jour le code de votre bot, installez les packages PyPI nécessaires en exécutant les commandes suivantes dans un terminal :

pip install aiohttp
pip install botbuilder-core>=4.7.0

Configurez l’état d’inspection dans le fichier app.py en ajoutant un intergiciel (middleware) à l’adaptateur.

app.py

from botbuilder.core import (
    ConversationState,
    MemoryStorage,
    TurnContext,
    UserState,
)
from botbuilder.core.inspection import InspectionMiddleware, InspectionState
from botbuilder.core.integration import aiohttp_error_middleware
from botbuilder.integration.aiohttp import CloudAdapter, ConfigurationBotFrameworkAuthentication
from botbuilder.schema import Activity, ActivityTypes
from botframework.connector.auth import MicrosoftAppCredentials

# Create adapter.
# See https://aka.ms/about-bot-adapter to learn more about how bots work.
ADAPTER = CloudAdapter(ConfigurationBotFrameworkAuthentication(CONFIG))

# Catch-all for errors.
USER_STATE = UserState(MEMORY)
CONVERSATION_STATE = ConversationState(MEMORY)

# Create InspectionMiddleware
INSPECTION_MIDDLEWARE = InspectionMiddleware(
    inspection_state=InspectionState(MEMORY),
    user_state=USER_STATE,
    conversation_state=CONVERSATION_STATE,
    credentials=MicrosoftAppCredentials(
        app_id=CONFIG.APP_ID, password=CONFIG.APP_PASSWORD
    ),
)
ADAPTER.use(INSPECTION_MIDDLEWARE)

# Create Bot
BOT = EchoBot(CONVERSATION_STATE, USER_STATE)

Mettez à jour la classe de bot dans le fichier echo_bot.py.

bots/echo_bot.py

async def on_message_activity(self, turn_context: TurnContext):
    # Get the state properties from the turn context.
    user_data = await self.user_state_accessor.get(turn_context, CustomState)
    conversation_data = await self.conversation_state_accessor.get(
        turn_context, CustomState
    )

    await turn_context.send_activity(
        MessageFactory.text(
            f"Echo: {turn_context.activity.text}, "
            f"conversation state: {conversation_data.value}, "
            f"user state: {user_data.value}"
        )
    )

    user_data.value = user_data.value + 1
    conversation_data.value = conversation_data.value + 1

Tester votre bot localement

Après la mise à jour du code, vous pouvez exécuter votre bot localement et tester la fonctionnalité de débogage à l’aide de deux émulateurs : un pour envoyer et recevoir des messages et l’autre pour inspecter l’état des messages en mode débogage. Tester votre bot localement :

1. Accédez au répertoire de votre bot dans un terminal et exécutez la commande suivante pour exécuter votre bot localement :

   C#

   dotnet run
   

   JavaScript

   npm start
   

   Java

   mvn package
   java -jar .\target\bot-inspection-sample.jar 
   

   Python

   python app.py
   

2. Ouvrez votre Emulator. Sélectionnez Ouvrir le bot. Renseignez l’URL du bot avec http://localhost:3978/api/messages et les valeurs MicrosoftAppId et MicrosoftAppPassword. Si vous avez un bot JavaScript, vous pouvez trouver ces valeurs dans le fichier .env de votre bot. Si vous avez un bot C#, vous pouvez trouver ces valeurs dans le fichier appSettings.json. Pour un bot Java, vous pouvez trouver ces valeurs dans le fichier application.properties. Sélectionnez Se connecter.

3. Ouvrez maintenant une autre fenêtre Emulator. Cette deuxième fenêtre Emulator fonctionnera comme un débogueur. Suivez les instructions décrites à l’étape précédente. Cochez Ouvrir en mode débogage et cliquez sur Se connecter.

4. À ce stade, vous allez voir une commande avec un identificateur unique (/INSPECT attach <identifier>) dans votre Emulator de débogage. Copiez la commande entière avec l’identificateur depuis l’émulateur de débogage et collez-la dans la zone de conversation du premier émulateur.

   Remarque

   Un identificateur unique est généré chaque fois qu’Emulator est lancé en mode débogage après l’ajout de l’intergiciel d’inspection dans le code de votre bot.

5. Vous pouvez désormais envoyer des messages dans la zone de discussion de votre premier Emulator et inspecter les messages dans Emulator de débogage. Pour inspecter l’état des messages, cliquez sur État du bot dans l’Emulator de débogage et dépliez les valeurs dans la fenêtre JSON appropriée. Vous allez voir l’état de votre bot dans l’Emulator de débogage :

   

Inspecter l’état d’un bot configuré dans Azure

Si vous souhaitez inspecter l’état de votre bot configuré dans Azure et connecté à des canaux (comme Teams), vous devez installer et exécuterngrok.

Exécuter ngrok

À ce stade, vous avez mis à jour votre Emulator vers la dernière version et ajouté l’intergiciel d’inspection dans le code de votre bot. L’étape suivante consiste à exécuter ngrok et à configurer votre bot local. Avant d’exécuter ngrok, vous devez exécuter votre bot localement.

Pour exécuter votre bot localement :

1. Accédez au dossier de votre bot dans un terminal et définissez votre inscription npm pour utiliser les builds les plus récents

2. Exécutez votre bot en local. Vous verrez que votre bot expose un numéro de port comme 3978.

3. Ouvrez une autre invite de commandes et accédez au dossier du projet de votre bot. Exécutez la commande suivante :

   ngrok http 3978
   

4. ngrok est maintenant connecté à votre bot s’exécutant localement. Copiez l’adresse IP publique sécurisée (HTTPS).

   

Mettez à jour votre ressource de bot

Maintenant que votre bot local est connecté à ngrok, vous pouvez configurer votre ressource de bot dans Azure pour utiliser l’URL ngrok.

1. Accédez à votre ressource de bot dans Azure. Dans le menu de gauche, sélectionnez Configuration sous Paramètres.

   1. Définissez le point de terminaison de messagerie sur l’adresse IP ngrok que vous avez copiée. Si nécessaire, ajoutez /api/messages à la suite de votre adresse IP. Par exemple : https://e58549b6.ngrok.io/api/messages.

   2. Sélectionnez Activer le point de terminaison de streaming.

      

   3. Cliquez sur Appliquer pour enregistrer vos modifications.

      Conseil

      Si Appliquer n’est pas coché, vous pouvez décocher Activer le point de terminaison de streaming et sélectionner Appliquer, puis cocher Activer le point de terminaison de streaming et sélectionner Appliquer à nouveau. Vous devez vérifier que l’option Activer le point de terminaison de streaming est cochée et que la configuration du point de terminaison est enregistrée.

2. Accédez à votre groupe de ressources de bot.

   1. Sélectionnez Déploiement, puis sélectionnez la ressource de bot qui a été déployée précédemment. Sélectionnez Modèle dans le menu de gauche pour obtenir le MicrosoftAppId et le MicrosoftAppPassword pour l’application Web associée à votre bot.

      

   2. Mettez à jour le fichier de configuration de votre bot (appsettings.json pour C#, ou .env pour JavaScript) avec le MicrosoftAppId et le MicrosoftAppPassword.

3. Démarrez votre Emulator, cliquez sur Ouvrir le bot, puis placez http://localhost:3978/api/messages dans l’URL du bot. Remplissez l’ID d’application Microsoft et le mot de passe de l’application Microsoft avec les mêmes MicrosoftAppId et MicrosoftAppPassword que vous avez ajoutés au fichier de configuration de notre bot. Sélectionnez Connecter.

4. Votre bot en cours d’exécution est maintenant connecté à votre ressource de bot dans Azure. Pour tester votre bot dans Azure dans Chat Web, accédez à vos ressources de bot, sélectionnez Tester dans Chat Web et envoyez des messages à votre bot.

Activer le mode débogage

1. Dans votre Emulator, sélectionnez Déboguer, puis Démarrer le débogage.

2. Saisissez l’adresse IP ngrok (n’oubliez pas d'ajouter /api/messages) dans l'URL du bot (par exemple, https://e58549b6.ngrok.io/api/messages).

   1. Pour l’ID d’application Microsoft, saisissez l’ID d’application de votre bot.
   2. Pour le mot de passe de l’application Microsoft, saisissez le secret d’application de votre bot.
   3. Assurez-vous que la case Ouvrir en mode débogage est également cochée.
   4. Sélectionnez Se connecter.

3. Une fois le mode débogage activé, Emulator génère un UUID. Un UUID est un ID unique généré chaque fois que vous démarrez le mode débogage dans votre Emulator.

4. Copiez et collez l’UUID dans la zone de discussion Tester dans Chat Web pour la zone de discussion de votre canal. Le message « joint à la session, tout le trafic est répliqué pour inspection » s’affiche dans la zone de discussion.

Vous pouvez démarrer le débogage de votre bot en envoyant des messages dans la zone de discussion du canal configuré. Votre Emulator local met automatiquement à jour les messages avec tous les détails pour le débogage. Pour inspecter l’état des messages de votre bot, cliquez sur Bot State (État du bot) et déroulez les valeurs dans la fenêtre JSON appropriée.

Étapes suivantes

• Comment déboguer votre bot à l’aide de fichiers de transcription.
• Comment déboguer une compétence ou un consommateur de compétences.