Depurar um bot com middleware de inspeção

APLICA-SE A: SDK v4

Este artigo descreve como depurar um bot usando o middleware de inspeção. Este recurso permite que o Bot Framework Emulator depure o tráfego dentro e fora do bot, além de examinar o estado atual dele. Você pode usar uma mensagem de rastreamento para enviar dados para o Emulator e, em seguida, inspecionar o estado do bot em qualquer determinada rodada da conversa.

Usamos um EchoBot criado localmente por meio do Bot Framework v4 no início rápido Criar um bot para mostrar como depurar e inspecionar o estado da mensagem do bot. Você também pode Depurar um bot usando o IDE ou Depurar com o Bot Framework Emulator, mas, para depurar o estado, você precisa adicionar o middleware de inspeção ao bot. Os exemplos de bot de inspeção estão disponíveis para C#, JavaScript, Java e Python.

Observação

Os SDKs JavaScript, C# e Python do Bot Framework continuarão a ser compatíveis. No entanto, o SDK Java está sendo desativado, com o suporte final de longo prazo terminando em novembro de 2023.

Os bots existentes criados com o SDK para Java continuarão a funcionar.

Para a criação de novos bots, considere usar o Microsoft Copilot Studio e leia sobre como escolher a solução de copiloto certa.

Para obter mais informações, confira O futuro da criação de bots.

Pré-requisitos

• Conhecimento de bots Middleware e do Estado de gerenciamento
• Conhecimento de como depurar um bot com SDK primeiro e testar e depurar com o Emulator
• Instalar Bot Framework Emulator
• Um Túnel de Desenvolvimento de instalação (se você quiser depurar um bot configurado no Azure para usar outros canais)
• Uma cópia da amostra do bot de inspeção em C#, Java ou Python

Atualizar o Emulator para a última versão

Antes de usar o middleware de inspeção de bot para depurar seu bot, atualize seu emulador para a versão 4.15 ou posterior. Verifique a última versão para obter atualizações.

Para verificar a versão do seu Emulator, selecione Ajuda e Sobre no menu. Você verá a versão atual do Emulator.

Atualizar o código do bot

C#

O estado de inspeção e o middleware de inspeção são configurados no arquivo Startup.cs e, em seguida, usados pelo 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");
            };
        }

Atualize a classe do bot no arquivo 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 atualizar o código do bot, atualize os pacotes dele para as últimas versões executando o seguinte comando no terminal:

npm install --save botbuilder@latest

Em seguida, você precisa atualizar o código do bot JavaScript conforme descrito a seguir. Você pode ler mais aqui: Atualizar o código do seu bot ou confira a amostra de middleware de inspeção no GitHub.

index.js

Configure o estado de inspeção e adicione o middleware de inspeção ao adaptador no arquivo 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

Atualize a classe bot no arquivo 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 o estado de inspeção e adicione o middleware de inspeção ao adaptador no arquivo Application.java. O estado de inspeção é definido fornecendo um novo Spring @Bean para o BotFrameworkHttpAdapter que está definido como @Primary para que ele substitua o BotFrameworkHttpAdapter padrão fornecido pela classe base BotDependencyConfiguration. Veja a atualização do código abaixo ou confira a amostra middleware de inspeção no 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
    );
}

O AdapterWithInspection é implementado como parte do pacote com.microsoft.bot.integration e pode ser revisado a partir do código-fonte do Java SDK.

Atualize a classe do bot no arquivo 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 atualizar o código do seu bot, instale os pacotes PyPI necessários executando os seguintes comandos em um terminal:

pip install aiohttp
pip install botbuilder-core>=4.7.0

Configure o estado de inspeção no arquivo app.py adicionando um middleware ao 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)

Atualize a classe do bot no arquivo 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

Testar o bot localmente

Depois de atualizar o código, você pode executar o bot localmente e testar o recurso de depuração usando dois emuladores: um para enviar e receber mensagens e o outro para inspecionar o estado das mensagens no modo de depuração. Para testar seu bot localmente:

1. Navegue até o diretório do bot em um terminal e execute o seguinte comando para executar o seu bot localmente:

   C#

   dotnet run
   

   JavaScript

   npm start
   

   Java

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

   Python

   python app.py
   

2. Abra seu Emulator. Selecione Abrir bot. Preencha a URL do bot com http://localhost:3978/api/messages e os valores de MicrosoftAppId e de MicrosoftAppPassword. Se tiver um bot JavaScript, poderá encontrar esses valores no arquivo .env do seu bot. Se tiver um bot C#, poderá encontrar esses valores no arquivo appsettings.json. Para um bot Java, você pode encontrar esses valores no arquivo application.properties. Selecione Conectar.

3. Agora, abra outra janela do Emulator. Essa segunda janela do Emulator funcionará como um depurador. Siga as instruções descritas na etapa anterior. Marque Abrir no modo de depuração e selecione Conectar.

4. Neste ponto, você verá um comando com um identificador exclusivo (/INSPECT attach <identifier>) em seu Emulator de depuração. Copie o comando inteiro com o identificador do Emulator de depuração e cole-o na caixa de chat do primeiro Emulator.

   Observação

   Um identificador exclusivo é gerado toda vez que o Emulator é iniciado no modo de depuração depois que você adiciona o middleware de inspeção no código do bot.

5. Agora você pode enviar mensagens na caixa de chat do seu primeiro Emulator e inspecionar as mensagens no Emulator de depuração. Para inspecionar o estado das mensagens, selecione Estado do Bot no Emulator de depuração e desdobre os valores na janela à direita JSON. Você verá o estado do bot no Emulator de depuração:

   

Inspecionar o estado de um bot configurado no Azure

Se você quiser inspecionar o estado do bot configurado no Azure e conectado a canais (como o Teams), precisará instalar e executar os Túneis de Desenvolvimento.

Executar devtunnel

Neste ponto, você atualizou o Emulator para a última versão e adicionou o middleware de inspeção no código do bot. A próxima etapa é executar devtunnel e configurar seu bot local. Antes de executar o devtunnel, você precisa executar seu bot localmente.

Para executar seu bot localmente:

1. Navegue até a pasta do bot em um terminal e defina o registro do npm para usar os builds mais recentes

2. Execute o bot localmente. Você verá o bot expor um número da porta como 3978.

3. Abra outro prompt de comando e navegue até a pasta do projeto do seu bot. Execute o comando a seguir:

   devtunnel host -a -p 3978
   

4. O devtunnel agora está conectado ao bot em execução localmente. Copie a URL pública segura (HTTPS).

   

Atualize o recurso de seu bot

Agora que o bot local está conectado ao devtunnel, você pode configurar o recurso de bot no Azure para usar a URL do devtunnel.

1. Acesse o recurso do seu bot no portal do Azure. No menu à esquerda, em Configurações selecione Configuração.

   1. Defina o endpoint de mensagens como o endereço de URL do devtunnel que você copiou. Se necessário, adicione /api/messages após o endereço IP. Por exemplo, https://0qg12llz-3978.usw2.devtunnels.ms/api/messages.

   2. Selecione Habilitar ponto de extremidade de streaming.

      

   3. Selecione Aplicar para salvar as alterações.

      Dica

      Se a opção Aplicar não estiver habilitada, você poderá desmarcar Habilitar ponto de extremidade de streaming e selecionar Aplicar, depois marcar Habilitar ponto de extremidade de streaming e selecionar Aplicar novamente. Você precisa verificar se Habilitar Ponto de Extremidade de Streaming está marcado e a configuração do ponto de extremidade foi salva.

2. Vá até o grupo de recursos do seu bot.

   1. Selecione Implantação e, em seguida, selecione o recurso de bot que foi implantado anteriormente com êxito. Selecione Modelo no menu à esquerda para obter o MicrosoftAppId e o MicrosoftAppPassword para o aplicativo Web associado ao bot.

      

   2. Atualize o arquivo de configuração do bot (appsettings.json para C# ou .env para JavaScript) com o MicrosoftAppId e o MicrosoftAppPassword.

3. Inicie o Emulator, selecione Abrir Bot e insira http://localhost:3978/api/messages na URL do Bot. Preencha a ID do Aplicativo da Microsoft e a senha do Aplicativo da Microsoft com o mesmo MicrosoftAppId e MicrosoftAppPassword que você adicionou ao arquivo de configuração do nosso bot. Depois, selecione Conectar.

4. O bot em execução agora está conectado ao recurso de bot no Azure. Para testar seu bot no Azure usando o Webchat, acesse os recursos do bot, selecione Testar no Web Chat e envie mensagens para o bot.

Habilitar o modo de depuração

1. Em seu Emulator, selecione Depurar e Iniciar Depuração.

2. Insira a URL do devtunnel (não se esqueça de adicionar /api/messages) para a URL do Bot (por exemplo, https://4jj51x75-51865.usw2.devtunnels.ms/api/messages).

   1. Em ID do ID do aplicativo da Microsoft, insira a ID do aplicativo do bot.
   2. Em senha do Aplicativo da Microsoft, insira o segredo do aplicativo do bot.
   3. Verifique se a opção Abrir no modo de depuração também está marcada.
   4. Selecione Conectar.

3. Com o modo de depuração habilitado, o Emulator gera um UUID. Um UUID é uma ID exclusiva gerada toda vez que você inicia o modo de depuração no Emulator.

4. Copie e cole o UUID na caixa de chat Testar no Webchat do canal. Você verá na mensagem "Anexado à sessão, que todo o tráfego está sendo replicado para inspeção" na caixa de chat.

Você pode iniciar a depuração do bot enviando mensagens na caixa de chat do canal configurado. Seu Emulator local atualizará automaticamente as mensagens com todos os detalhes para depuração. Para inspecionar o estado de mensagens do bot, selecione Estado do Bot e desdobre os valores na janela JSON à direita.

Próximas etapas

• Saiba como Depurar seu bot usando arquivos de transcrição.
• Saiba como Depurar uma habilidade ou um consumidor de habilidades.