Отладка бота с помощью проинспектирующего промежуточного программного обеспечения

ОБЛАСТЬ ПРИМЕНЕНИЯ: ПАКЕТ SDK версии 4

В этой статье описывается, как отлаживать бота с помощью промежуточного ПО для инспекции. Эта функция позволяет эмулятору Bot Framework отлаживать трафик в бот и из него и просматривать текущее состояние бота. Вы можете использовать сообщение трассировки для отправки данных в эмулятор, а затем проверить состояние бота в любой момент беседы.

Мы используем EchoBot, созданный локально с помощью Bot Framework версии 4 в кратком руководстве по созданию бота, чтобы показать, как отлаживать и проверять состояние сообщения бота. Отладку бота также можно выполнять с помощью IDE или Bot Framework Emulator, но для отладки состояния в бота нужно добавить проверяющее ПО промежуточного слоя. Примеры бота проверки доступны для C#, JavaScript, JavaScript и Python.

Это важно

Пакет SDK Bot Framework и эмулятор Bot Framework были архивированы на GitHub. Проект больше не обновляется или не поддерживается. Запросы на поддержку пакета SDK Bot Framework больше не будут обслуживаться с 31 декабря 2025 г.

Чтобы создавать агенты с помощью выбранной службы ИИ, оркестрации и знаний, рекомендуется использовать пакет SDK для агентов Microsoft 365. Пакет SDK для агентов поддерживает язык C#, JavaScript или Python. Дополнительные сведения о пакете SDK для агентов см. в aka.ms/agents. Если у вас есть существующий бот, созданный с помощью пакета SDK Bot Framework, вы можете обновить бота до пакета SDK для агентов. Ознакомьтесь с основными изменениями и обновлениями в руководстве по миграции с Bot Framework SDK на Agents SDK.

Если вы создаете агент для совместной работы в Microsoft Teams, рассмотрите возможность использования пакета SDK Teams. Он предоставляет интерфейсы API, поддержку адаптивных карт и встроенную оркестрацию ИИ для агентов, работающих в среде Teams. Дополнительные сведения см. в пакете SDK Teams (библиотека ИИ Teams).

Если вы ищете платформу агента на основе SaaS, рассмотрите microsoft Copilot Studio.

Предварительные условия

• Знание о промежуточном слое бота и об управлении состоянием
• Знание о том, как отлаживать бота, основанного на SDK, и тестировать и отлаживать с помощью эмулятора
• Установка эмулятора Bot Framework
• Установка Dev Tunnel (если вы хотите выполнить отладку бота, настроенного в Azure для использования других каналов)
• Копия примера бота проверки для C#, JavaScript, Java или Python

Обновление эмулятора до последней версии

Перед использованием промежуточного ПО для отладки бота обновите эмулятор до версии 4.15 или более поздней. Проверьте последнюю версию на наличие обновлений.

Чтобы проверить версию эмулятора, выберите "Справка", а затем "Сведения " в меню. Вы увидите текущую версию эмулятора.

Изменение кода бота

C#

Состояние проверки и промежуточное программное обеспечение для проверки настраиваются в файле Startup.cs, а затем используется адаптером.

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

Обновите класс бота в файле 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

Перед обновлением кода бота обновите свои пакеты до последних версий, выполнив следующую команду в терминале:

npm install --save botbuilder@latest

Затем нужно обновить код бота JavaScript следующим образом. Дополнительные сведения см. здесь: обновите код вашего бота или ознакомьтесь с примером с промежуточным программным обеспечением для проверки на GitHub.

index.js

Настройте состояние проверки и добавьте проверяющее ПО промежуточного слоя в адаптер в файле index.js.

const restify = require('restify');

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

bot.js

Обновите класс бота в файле bot.js.

this.userStateAccessor = this.userState.createProperty('test-user-state');

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.

Java

Настройте состояние проверки и добавьте промежуточное программное обеспечение для проверки в адаптер в файле Application.java. Состояние проверки устанавливается путем передачи нового Spring @Bean, чтобы обеспечить BotFrameworkHttpAdapter, установленный как @Primary, таким образом, чтобы переопределить стандартный BotFrameworkHttpAdapter, предоставляемый базовым классом BotDependencyConfiguration. Посмотрите обновление кода ниже или пример использования промежуточного слоя проверки на 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 реализован в составе пакета com.microsoft.bot.integration и может быть проверен из исходного кода пакета SDK для Java.

Обновите класс бота в файле 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);
}

Питон

Перед обновлением кода бота установите необходимые пакеты PyPI, выполнив следующие команды в терминале:

pip install aiohttp
pip install botbuilder-core>=4.7.0

Настройте состояние проверки в файле app.py, добавив ПО промежуточного слоя в адаптер.

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)

Обновите класс бота в файле 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

Локальное тестирование бота

После обновления кода можно локально запустить бота и проверить функцию отладки с помощью двух эмуляторов: один для отправки и получения сообщений, а другой — для проверки состояния сообщений в режиме отладки. Чтобы протестировать бот локально, выполните следующее:

1. Перейдите в каталог бота в терминале и выполните следующую команду, чтобы запустить бот локально:

   C#

   dotnet run
   

   JavaScript

   npm start
   

   Java

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

   Питон

   python app.py
   

2. Откройте эмулятор. Выберите "Открыть бот". Заполните URL-адрес бота значениями http://localhost:3978/api/messages и MicrosoftAppPassword. Если у вас имеется JavaScript-бот, вы можете найти эти значения в файле .env вашего бота. Если у вас есть бот C#, эти значения можно найти в файле appsettings.json . Для бота Java эти значения можно найти в файле application.properties . Нажмите Подключиться.

3. Теперь откройте другое окно эмулятора. Второе окно эмулятора будет работать в качестве отладчика. Следуйте инструкциям, описанным выше. Установите флажок "Открыть в режиме отладки" и нажмите кнопку "Подключить".

4. На этом этапе вы увидите команду с уникальным идентификатором (/INSPECT attach <identifier>) в отладчике эмулятора. Скопируйте всю команду с идентификатором из эмулятора отладки и вставьте ее в окно чата первого эмулятора.

   Примечание.

   Уникальный идентификатор создается каждый раз, когда эмулятор запускается в режиме отладки после добавления посредующего программного обеспечения проверки в код бота.

5. Теперь вы можете отправлять сообщения в поле чата первого эмулятора и проверять сообщения в эмуляторе отладки. Чтобы проверить состояние сообщений, выберите "Состояние бота" в эмуляторе отладки и разверните значения в правом окне JSON. Вы увидите состояние бота в эмуляторе отладки:

   

Проверка состояния бота, настроенного в Azure

Если вы хотите проверить состояние бота, настроенного в Azure, и подключиться к каналам (например, Teams), необходимо установить и запустить туннели разработки.

Запуск devtunnel

На этом этапе вы обновили эмулятор до самой последней версии и добавили посредника для инспекции в код бота. Следующим шагом является запуск devtunnel и настройка локального бота. Перед запуском devtunnel необходимо локально запустить бот.

Чтобы запустить бот локально, выполните следующее:

1. Перейдите в папку бота в терминале и задайте регистрацию npm, чтобы использовать последние сборки

2. Запустите бот на локальном компьютере. Вы увидите, что бот предоставляет номер порта, например 3978.

3. Откройте другую командную строку и перейдите в папку проекта бота. Выполните следующую команду:

   devtunnel host -a -p 3978
   

4. Devtunnel теперь подключен к локально работающему боту. Скопируйте общедоступный URL-адрес безопасности (HTTPS).

   

Обновление ресурса бота

Теперь, когда локальный бот подключен к devtunnel, вы можете настроить ресурс бота в Azure для использования URL-адреса devtunnel.

1. Перейдите к ресурсу бота в Azure. В меню слева в разделе "Параметры" выберите "Конфигурация".

   1. Задайте для конечной точки обмена сообщениями URL-адрес devtunnel, скопированный вами. При необходимости добавьте /api/messages после IP-адреса. Например, https://0qg12llz-3978.usw2.devtunnels.ms/api/messages.

   2. Выберите Включить потоковую конечную точку.

      

   3. Щелкните Применить, чтобы сохранить изменения.

      Совет

      Если Применить не активно, снимите флажок с Включить конечную точку потоковой передачи и выберите Применить. Затем снова установите флажок на Включить конечную точку потоковой передачи и снова выберите Применить. Убедитесь, что флажок Включить конечную точку потоковой передачи установлен, а конфигурация конечной точки сохранена.

2. Перейдите в группу ресурсов бота.

   1. Выберите Развертывание и выберите ресурс бота, который ранее успешно развернут. Выберите шаблон из меню слева, чтобы получить MicrosoftAppId и MicrosoftAppPassword для веб-приложения, связанного с ботом.

      

   2. Обновите файл конфигурации бота (appsettings.json для C#или .env для JavaScript) с помощью MicrosoftAppId и MicrosoftAppPassword.

3. Запустите эмулятор, выберите "Открыть бот" и введите http://localhost:3978/api/messages URL-адрес бота. Заполните идентификатор приложения Майкрософт и пароль приложения Майкрософт тем же microsoftAppId и MicrosoftAppPassword , которые вы добавили в файл конфигурации нашего бота. В этом случае выберите Подключиться.

4. Запущенный бот теперь подключен к ресурсу бота в Azure. Чтобы протестировать бота в Azure в Веб-чат, перейдите в ресурсы бота, выберите "Тест в Веб-чат" и отправьте сообщения боту.

Включение режима отладки

1. В эмуляторе выберите "Отладка" и "Начать отладку".

2. Введите URL-адрес devtunnel (не забудьте добавить /api/messages) для URL-адреса бота (например, https://4jj51x75-51865.usw2.devtunnels.ms/api/messages).

   1. Для идентификатора приложения Майкрософт введите идентификатор приложения бота.
   2. Для пароля приложения Microsoft App введите секрет приложения бота.
   3. Также убедитесь, что флажок Открыть в режиме отладки установлен.
   4. Нажмите Подключиться.

3. С включенным режимом отладки эмулятор создает идентификатор UUID. UUID — это уникальный идентификатор, создаваемый при каждом запуске режима отладки в эмуляторе.

4. Скопируйте и вставьте UUID в поле чата Веб-чат, чтобы протестировать поле чата вашего канала. Вы увидите сообщение "Присоединено к сеансу, весь трафик реплицируется для проверки" в поле чата.

Чтобы начать отладку бота, отправьте сообщения в настроенное поле чата канала. Локальный эмулятор автоматически обновит сообщения со всеми сведениями об отладке. Чтобы проверить состояние сообщений бота, выберите "Состояние бота" и разверните значения в правом окне JSON.

Следующие шаги

• Узнайте, как дебаггировать вашего бота, используя файлы транскриптов.
• Узнайте, как выполнить отладку навыка или использователя навыков.