Depurar um bot com middleware de inspeção

APLICA-SE A: SDK v4

Este artigo descreve como depurar um bot usando middleware de inspeção. Esse recurso permite que o Bot Framework Emulator depure o tráfego de entrada e saída do bot e veja o estado atual do bot. Você pode usar uma mensagem de rastreamento para enviar dados para o emulador e, em seguida, inspecionar o estado do seu bot em qualquer turno da conversa.

Usamos um EchoBot construído localmente usando o Bot Framework v4 no guia de 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 IDE ou Depurar com o Bot Framework Emulator, mas para depurar o estado você precisa adicionar middleware de inspeção ao seu bot. Os exemplos do bot de inspeção estão disponíveis para C#, JavaScript, Java e Python.

Nota

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

Os bots existentes construídos com o Java SDK 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 copilot certa.

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

Pré-requisitos

• Conhecimento de middleware de bot e gerenciamento de estado
• Conhecimento de como depurar um bot SDK-first e testar e depurar com o emulador
• Uma instalação do 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 do exemplo de bot de inspeção para C#, JavaScript, Java ou Python

Atualize seu emulador para a versão mais recente

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 se há atualizações na versão mais recente.

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

Atualize o código do bot

C#

O estado de inspeção e o middleware de inspeção são configurados no arquivo de 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 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 seus pacotes para as versões mais recentes executando o seguinte comando no terminal:

npm install --save botbuilder@latest

Em seguida, você precisa atualizar o código do seu bot JavaScript da seguinte maneira. Você pode ler mais aqui: Atualize o código do seu bot ou consulte o exemplo 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 fornecer o BotFrameworkHttpAdapter definido para que @Primary ele substitua o padrão BotFrameworkHttpAdapter fornecido pela classe base BotDependencyConfiguration. Consulte a atualização de código abaixo ou consulte o exemplo de 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
    );
}

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 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 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

Teste seu bot localmente

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

1. Vá para o diretório do bot em um terminal e execute o seguinte comando para executar o 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 emulador. Selecione Abrir Bot. Preencha a URL do Bot com http://localhost:3978/api/messages e os valores MicrosoftAppId e MicrosoftAppPassword. Se você tiver um bot JavaScript, poderá encontrar esses valores no arquivo .env do seu bot. Se você 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 Ligar.

3. Agora abra outra janela do emulador. Esta segunda janela do emulador funcionará como um depurador. Siga as instruções conforme descrito 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 emulador de depuração. Copie todo o comando com o identificador do emulador de depuração e cole-o na caixa de chat do primeiro emulador.

   Nota

   Um identificador exclusivo é gerado sempre que o emulador é 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 emulador e inspecionar as mensagens no emulador de depuração. Para inspecionar o estado das mensagens, selecione Estado do Bot no Emulador de depuração e desdobre os valores na janela JSON direita. Você verá o estado do seu bot no emulador de depuração:

   

Inspecionar o estado de um bot configurado no Azure

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

Executar devtunnel

Neste ponto, você atualizou seu emulador para a versão mais recente 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. Vá para a pasta do seu bot em um terminal e defina seu registro npm para usar as compilações mais recentes

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

3. Abra outro prompt de comando e vá para a pasta de projeto do bot. Execute o seguinte comando:

   devtunnel host -a -p 3978
   

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

   

Atualize seu recurso de bot

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

1. Vá para seu recurso de bot no Azure. No menu à esquerda, em Configurações, selecione Configuração.

   1. Defina o ponto de extremidade de mensagens para o endereço URL devtunnel copiado. Se necessário, adicione /api/messages após o endereço IP. Por exemplo, https://0qg12llz-3978.usw2.devtunnels.ms/api/messages.

   2. Selecione Ativar ponto de extremidade de streaming.

      

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

      Gorjeta

      Se Aplicar não estiver habilitado, você poderá desmarcar Ativar ponto de extremidade de streaming e selecionar Aplicar, depois marcar Habilitar ponto de extremidade de streaming e selecionar Aplicar novamente. Você precisa certificar-se de que Ativar ponto de extremidade de streaming está marcado e a configuração do ponto de extremidade é salva.

2. Vá para 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 esquerdo para obter o MicrosoftAppId e o MicrosoftAppPassword para o aplicativo Web associado ao seu 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 emulador, selecione Abrir Bot e insira http://localhost:3978/api/messages o URL do Bot. Preencha a ID do Aplicativo Microsoft e a senha do Aplicativo Microsoft com o mesmo MicrosoftAppId e MicrosoftAppPassword que você adicionou ao arquivo de configuração do nosso bot. Em seguida, selecione Conectar.

4. Seu bot em execução agora está conectado ao seu recurso de bot no Azure. Para testar seu bot no Azure no Bate-papo da Web, vá para os recursos do bot, selecione Testar no Bate-papo da Web e envie mensagens para seu bot.

Ativar o modo de depuração

1. No emulador, selecione Depurar e, em seguida, Iniciar Depuração.

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

   1. Para a ID do Aplicativo Microsoft, insira a ID do aplicativo do bot.
   2. Para obter a senha do aplicativo Microsoft, insira o segredo do aplicativo do bot.
   3. Certifique-se de que Abrir no modo de depuração também está marcado.
   4. Selecione Ligar.

3. Com o modo de depuração ativado, o emulador gera um UUID. Um UUID é um ID exclusivo gerado sempre que você inicia o modo de depuração no seu emulador.

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

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

Próximos passos

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