Depuración de un bot con middleware de inspección

SE APLICA A: SDK v4

En este artículo se describe cómo depurar un bot mediante middleware de inspección. Esta característica permite a Bot Framework Emulator depurar el tráfico dentro y fuera del bot, además de examinar el estado actual de este. Puede usar un mensaje de seguimiento para enviar datos al emulador y, a continuación, inspeccionar el estado del bot en cualquier turno determinado de la conversación.

Se usa un EchoBot compilado localmente mediante Bot Framework v4 en el inicio rápido Crear un bot para mostrar cómo depurar e inspeccionar el estado del mensaje del bot. También puede depurar mediante IDE o con Bot Framework Emulator pero para depurar el estado necesitará agregar un middleware de inspección al bot. Los ejemplos de bots de inspección están disponibles para C#, JavaScript, Java y Python.

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 compatibilidad final a largo plazo que finaliza en noviembre de 2023.

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

Para la nueva compilación de bots, considere la posibilidad de usar Microsoft Copilot Studio y lea sobre cómo elegir la solución de copilot adecuada.

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

Requisitos previos

• Conocimientos de Middleware y de la administración del estado del bot.
• Conocimientos sobre cómo depurar un bot primero con el SDK y probar y depurar con Emulator
• Instalación de Bot Framework Emulator
• Una instalación de Dev Tunnel (si quiere depurar un bot configurado en Azure para usar otros canales)
• Una copia de la muestra de bot de inspección en C#, JavaScript, Java o Python.

Actualización del emulador a la versión más reciente

Antes de usar el middleware de inspección de bots para depurar el bot, actualice el emulador a la versión 4.15 o posterior. Compruebe la versión más reciente para buscar actualizaciones.

Para comprobar la versión del Emulator, seleccione Ayuda, y a continuación, Acerca de en el menú. Aparecerá la versión actual del Emulator.

Actualización del código del bot

C#

El estado de inspección y el middleware de inspección se configuran en el archivo Startup.cs y después son utilizados por el adaptador.

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");
            };
        }

Actualice la clase del bot en el archivo 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

Antes de actualizar el código del bot, debe actualizar sus paquetes a las versiones más recientes ejecutando el siguiente comando en el terminal:

npm install --save botbuilder@latest

Después, debe actualizar el código de su bot de JavaScript como se indica a continuación. Puede leer más aquí: Actualice el código del bot o consulte el ejemplo de middleware de inspección en GitHub.

index.js

Configure el estado de inspección y agregue el middleware de inspección al adaptador en el archivo 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

Actualice la clase del bot en el archivo 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

Configure el estado de inspección y añada el middleware de inspección al adaptador en el archivo Application.java. El estado de inspección se establece proporcionando un nuevo Spring @Bean para proporcionar el botFrameworkHttpAdapter establecido para @Primary que invalide el botFrameworkHttpAdapter predeterminado proporcionado por la clase base BotDependencyConfiguration. Vea la siguiente actualización del código o consulte esta muestra de middleware de inspección en 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 se implementa como parte del paquete com.microsoft.bot.integration y se puede revisar desde el código fuente del SDK de Java.

Actualice la clase del bot en el archivo 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

Antes de actualizar el código del bot, instale los paquetes de PyPI necesarios mediante la ejecución de los siguientes comandos en un terminal:

pip install aiohttp
pip install botbuilder-core>=4.7.0

Configure el estado de inspección en el archivo app.py mediante la adición de middleware al adaptador.

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)

Actualice la clase del bot en el archivo 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

Prueba local del bot

Después de actualizar el código, puede ejecutar el bot localmente y probar la característica de depuración con dos emuladores: uno para enviar y recibir mensajes, y el otro para inspeccionar el estado de los mensajes en el modo de depuración. Para realizar la prueba local del bot

1. Vaya al directorio del bot en un terminal y ejecute el siguiente comando para ejecutar el bot localmente:

   C#

   dotnet run
   

   JavaScript

   npm start
   

   Java

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

   Python

   python app.py
   

2. Abra el emulador. Seleccione Abrir bot. Rellene la URL del bot con http://localhost:3978/api/messages y los valores MicrosoftAppId y MicrosoftAppPassword. Si tiene un bot de JavaScript, puede encontrar estos valores en el archivo .env del bot. Si tiene un bot de C# , puede encontrar estos valores en el archivo appsettings.json. Para un bot de Java, puede encontrar estos valores en el archivo application.properties . Seleccione Conectar.

3. Ahora abra otra ventana de Emulator. Esta segunda ventana de Emulator funcionará como un depurador. Siga las instrucciones que se describen en el paso anterior. Seleccione Abrir en modo de depuración y haga clic en Conectar.

4. En este momento, verá un comando con un identificador único (/INSPECT attach <identifier>) en el Emulator de depuración. Copie el comando completo con el identificador del emulador de depuración y péguelo en el cuadro de chat del primer emulador.

   Nota:

   Se genera un identificador único cada vez que el emulador se inicia en modo de depuración después de agregar el middleware de inspección al código del bot.

5. Ahora puede enviar mensajes en el cuadro de chat del primer emulador e inspeccionar los mensajes en el emulador de depuración. Para inspeccionar el estado de los mensajes, haga clic en Bot State en el Emulator de depuración y despliegue los valores en la ventana JSON situada a la derecha. Verá el estado del bot en el Emulator de depuración:

   

Inspección del estado de un bot configurado en Azure

Si desea inspeccionar el estado del bot configurado en Azure y conectado a canales (como Teams), deberá instalar y ejecutar túneles de desarrollo.

Ejecución de devtunnel

En este punto, ha actualizado el Emulator a la versión más reciente y ha agregado el middleware de inspección al código del bot. El siguiente paso es ejecutar devtunnel y configurar el bot local. Antes de ejecutar devtunnel, debe ejecutar el bot localmente.

Para la ejecución local del bot:

1. Vaya a la carpeta del bot en un terminal y configure el registro npm para que utilice las versiones más recientes.

2. Ejecute el bot localmente. Verá que el bot expone un número de puerto como 3978.

3. Abra otro símbolo del sistema y vaya a la carpeta de proyecto del bot. Ejecute el siguiente comando:

   devtunnel host -a -p 3978
   

4. devtunnel ahora está conectado al bot en ejecución local. Copie la dirección URL pública segura (HTTPS).

   

Actualización de un recurso de bot

Ahora que el bot local está conectado a devtunnel, puede configurar el recurso de bot en Azure para usar la dirección URL de devtunnel.

1. Vaya al recurso de bot en Azure. Seleccione Configuración en Configuración en el menú de la izquierda.

   1. Establezca el punto de conexión de mensajería en la dirección URL devtunnel que copió. Si es necesario, agregue /api/messages después de la dirección IP. Por ejemplo, https://0qg12llz-3978.usw2.devtunnels.ms/api/messages.

   2. Seleccione Habilitar punto de conexión de streaming.

      

   3. Seleccione Aplicar para guardar los cambios.

      Sugerencia

      Si Aplicar no está habilitado, puede desactivar Habilitar punto de conexión de streaming y hacer clic en Aplicar y, a continuación, seleccionar Habilitar punto de conexión de streaming y hacer clic en Aplicar de nuevo. Asegúrese de que Enable Streaming Endpoint (Habilitar punto de conexión de streaming) está seleccionado y se guardará la configuración del punto de conexión.

2. Vaya al grupo de recursos de bot.

   1. Seleccione Implementación y, a continuación, seleccione el recurso de bot que se implementó correctamente. Seleccione Plantilla en el menú de la izquierda para obtener MicrosoftAppId y MicrosoftAppPassword para la aplicación web asociada al bot.

      

   2. Actualice el archivo de configuración del bot (appsettings.json para C#, o .env para JavaScript) con MicrosoftAppId y MicrosoftAppPassword.

3. Inicie el Emulator, haga clic en Abrir bot e introduzca http://localhost:3978/api/messages en la dirección URL del bot. Rellene el identificador de aplicación de Microsoft y la contraseña de la aplicación de Microsoft con el mismo MicrosoftAppId y MicrosoftAppPassword que agregó al archivo de configuración del bot. A continuación, seleccione Conectar.

4. El bot en ejecución está ahora conectado a su recurso de bot en Azure. Para probar el bot en Azure en Chat en web, vaya a los recursos del bot, seleccione Probar en Chat en web y envíe mensajes al bot.

Habilite el modo de depuración

1. En el Emulator, seleccione Depurar, y después Iniciar depuración.

2. Escriba la dirección URL devtunnel (no olvide agregar /api/messages) para la dirección URL del bot (por ejemplo, https://4jj51x75-51865.usw2.devtunnels.ms/api/messages).

   1. Para el identificador de aplicación de Microsoft, introduzca el identificador de aplicación del bot.
   2. En Contraseña de aplicación de Microsoft, escriba el secreto de la aplicación del bot.
   3. Asegúrese de que Open in debug mode (Abrir en modo de depuración) también está seleccionado.
   4. Seleccione Conectar.

3. Con el modo de depuración habilitado, el emulador genera un UUID. Un UUID es un identificador único que se genera cada vez que se inicia el modo de depuración en el emulador.

4. Copie y pegue el UUID en el cuadro de chat Probar en chat en web del cuadro de chat del canal. Verá el mensaje "Attached to session, all traffic is being replicated for inspection" (Conectado a la sesión, todo el tráfico se replicará para su inspección) en el cuadro de chat.

Puede empezar a depurar el bot enviando mensajes en el cuadro de chat del canal configurado. El emulador local actualizará automáticamente los mensajes con todos los detalles de la depuración. Para inspeccionar el estado de los mensajes del bot, haga clic en Bot State y despliegue los valores en la ventana JSON correcta.

Pasos siguientes

• Información sobre la Depuración del bot mediante archivos de transcripción.
• Información sobre cómo Depurar una capacidad o un consumidor de capacidades.