Использование диалогов в навыке

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

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

В этой статье предполагается, что вы уже знакомы с созданием навыков. Сведения о создании бота навыка см. в статье о реализации навыка.

Примечание.

Пакеты SDK для JavaScript, C# и Python для Bot Framework по-прежнему будут поддерживаться, однако пакет SDK java отменяется с окончательной долгосрочной поддержкой, заканчивающейся в ноябре 2023 года.

Существующие боты, созданные с помощью пакета SDK для Java, будут продолжать функционировать.

Для создания нового бота рекомендуется использовать Microsoft Copilot Studio и ознакомиться с выбором подходящего решения copilot.

Дополнительные сведения см. в статье "Будущее создания бота".

Необходимые компоненты

• Понимание основ работы с ботами, принципа работы ботов с навыками и принципа реализации навыка.
• Подписка Azure (для развертывания навыка). Если у вас еще нет подписки Azure, создайте бесплатную учетную запись, прежде чем начать работу.
• Учетная запись LUIS (необязательно). (См. сведения о добавлении функции распознавания естественного языка в бота.)
• Копия примера навыка skillDialog в C#, JavaScript, JavaScript или Python.

Примечание.

Распознавание речи (LUIS) будет прекращен 1 октября 2025 года. Начиная с 1 апреля 2023 года вы не сможете создавать новые ресурсы LUIS. Новая версия распознавания речи теперь доступна как часть языка ИИ Azure.

Распознавание речи (CLU) — это обновленная версия LUIS. Дополнительные сведения о поддержке распознавания речи в пакете SDK Bot Framework см. в разделе "Распознавание естественного языка".

Об этом примере

В пример skills skillDialog включены проекты двух ботов:

• Корневой бот диалога, который использует диалог навыка для применения навыка.
• Бот навыка диалога, который использует диалог для обработки действий, поступающих от потребителей навыков. Этот навык является адаптацией примера core bot. (Сведения о примере core bot см. в статье о добавлении функции распознавания естественного языка в бота.)

В этой статье описывается, как использовать диалоговое окно в боте навыка для управления несколькими действиями.

C#

JavaScript

Java

Python

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

Ресурсы

Для развернутых ботов проверка подлинности "бот — бот" требует, чтобы каждый участвующий бот имеет допустимое удостоверение. Однако вы можете протестировать навыки и навыки потребителей локально с помощью эмулятора Bot Framework без сведений об удостоверениях.

Чтобы сделать навык доступным для пользователей ботов, зарегистрируйте навык в Azure. Дополнительные сведения см. в статье о регистрации бота с помощью Azure AI Служба Bot.

Кроме того, бот навыка может использовать модель LUIS для бронирования авиабилетов. Чтобы применить эту модель, с помощью файла CognitiveModels/FlightBooking.json создайте, обучите и опубликуйте модель LUIS.

Конфигурация приложений

1. При необходимости добавьте сведения об удостоверениях навыка в файл конфигурации навыка. (Если пользователь навыка или навыка указывает удостоверение, оба должны.)

2. Если вы используете модель LUIS, добавьте идентификатор приложения LUIS, ключ API и имя узла API.

C#

DialogSkillBot\appsettings.json

{
  "MicrosoftAppType": "",
  "MicrosoftAppId": "",
  "MicrosoftAppPassword": "",
  "MicrosoftAppTenantId": "",
  "ConnectionName": "",

  "LuisAppId": "",
  "LuisAPIKey": "",
  "LuisAPIHostName": "",

  // This is a comma separate list with the App IDs that will have access to the skill.
  // This setting is used in AllowedCallersClaimsValidator.
  // Examples: 
  //    [ "*" ] allows all callers.
  //    [ "AppId1", "AppId2" ] only allows access to parent bots with "AppId1" and "AppId2".
  "AllowedCallers": [ "*" ]
}

JavaScript

dialogSkillBot/.env

MicrosoftAppType=
MicrosoftAppId=
MicrosoftAppPassword=
MicrosoftAppTenantId=
AllowedCallers=*

LuisAppId=
LuisAPIKey=
LuisAPIHostName=

Java

application.properties

MicrosoftAppId=
MicrosoftAppPassword=
server.port=39783

LuisAppId=
LuisAPIKey=
LuisAPIHostName=
# This is a comma separate list with the App IDs that will have access to the skill.
# This setting is used in AllowedCallersClaimsValidator.
# Examples:
#    * allows all callers.
#    AppId1,AppId2 only allows access to parent bots with "AppId1" and "AppId2".
AllowedCallers=*

Python

dialog-skill-bot/config.py

PORT = 39783
APP_ID = os.environ.get("MicrosoftAppId", "")
APP_PASSWORD = os.environ.get("MicrosoftAppPassword", "")
APP_TYPE = os.environ.get("MicrosoftAppType", "MultiTenant")
APP_TENANTID = os.environ.get("MicrosoftAppTenantId", "")

# Callers to only those specified, '*' allows any caller.
# Example: os.environ.get("AllowedCallers", ["aaaaaaaa-1111-aaaa-aaaa-aaaaaaaa"])
ALLOWED_CALLERS = os.environ.get("AllowedCallers", ["*"])

LUIS_APP_ID = os.environ.get("LuisAppId", "")
LUIS_API_KEY = os.environ.get("LuisAPIKey", "")

Логика activity-routing

Этот навык поддерживает несколько разных функций. Он может забронировать авиабилет и получить прогноз погоды для города. Кроме того, если он получает сообщение за пределами одного из этих контекстов, он может использовать LUIS, чтобы попытаться интерпретировать сообщение. Манифест навыка описывает эти действия, входные и выходные параметры, а также конечные точки навыка. Обратите внимание, что навык умеет обрабатывать события BookFlight и GetWeather. Он также обрабатывает действия сообщений.

Навык определяет диалог activity-routing, который используется для выбора запускаемого действия в зависимости от исходного действия, полученного от потребителя навыков. Если предоставлена модель LUIS, она может распознавать в исходном сообщении намерения бронирования авиабилетов и получения прогноза погоды.

Действие book-flight — это многоэтапный процесс, который реализован в отдельном диалоге. Начавшись, это действие обрабатывает все входящие действия. Действие get-weather содержит логику заполнителя, которую для полноценной реализации бота нужно будет заменить.

Диалог activity-routing содержит код для выполнения следующих действий:

• инициализация диалога;
• обработка начального действия;
• обработка действий сообщения;
• запуск многошагового действия;
• возврат результата.

Используемые в этом навыке диалоги унаследованы от класса компонентного диалога. Дополнительные сведения о компонентных диалогах см. в статье об управлении сложностью диалогов.

инициализация диалога;

Диалог activity-routing включает дочерний диалог для бронирования авиабилетов. В главном каскадном диалоге есть один шаг, который запускает действие на основе полученного исходного действия.

Он также может принимать распознаватель LUIS. Если этот распознаватель инициализирован, диалог попытается применить его для оценки намерения в исходном действии сообщения.

C#

DialogSkillBot\Dialogs\ActivityRouterDialog.cs

private readonly DialogSkillBotRecognizer _luisRecognizer;

public ActivityRouterDialog(DialogSkillBotRecognizer luisRecognizer)
    : base(nameof(ActivityRouterDialog))
{
    _luisRecognizer = luisRecognizer;

    AddDialog(new BookingDialog());
    AddDialog(new WaterfallDialog(nameof(WaterfallDialog), new WaterfallStep[] { ProcessActivityAsync }));

    // The initial child Dialog to run.
    InitialDialogId = nameof(WaterfallDialog);
}

JavaScript

dialogSkillBot/dialogs/activityRouterDialog.js

constructor(conversationState, luisRecognizer = undefined) {
    super(ACTIVITY_ROUTER_DIALOG);

    if (!conversationState) throw new Error('[MainDialog]: Missing parameter \'conversationState\' is required');

    this.luisRecognizer = luisRecognizer;

    // Define the main dialog and its related components.
    // This is a sample "book a flight" dialog.
    this.addDialog(new BookingDialog())
        .addDialog(new WaterfallDialog(WATERFALL_DIALOG, [
            this.processActivity.bind(this)
        ]));

    this.initialDialogId = WATERFALL_DIALOG;
}

Java

DialogSkillBot\Dialogs\ActivityRouterDialog.java

private final DialogSkillBotRecognizer luisRecognizer;

public ActivityRouterDialog(DialogSkillBotRecognizer luisRecognizer) {
    super("ActivityRouterDialog");
    this.luisRecognizer = luisRecognizer;

    addDialog(new BookingDialog());
    List<WaterfallStep> stepList = new ArrayList<WaterfallStep>();
    stepList.add(this::processActivity);
    addDialog(new WaterfallDialog("WaterfallDialog", stepList));

    // The initial child Dialog to run.
    setInitialDialogId("WaterfallDialog");
}

Python

dialog-skill-bot/dialogs/activity_router_dialog.py

def __init__(self, luis_recognizer: DialogSkillBotRecognizer):
    super().__init__(ActivityRouterDialog.__name__)

    self._luis_recognizer = luis_recognizer

    self.add_dialog(BookingDialog())
    self.add_dialog(
        WaterfallDialog(WaterfallDialog.__name__, [self.process_activity])
    )

    self.initial_dialog_id = WaterfallDialog.__name__

обработка начального действия;

На первом (и только первом) шаге в главном каскадном диалоге навык проверяет тип входящего действия.

• Действия событий передаются обработчику действий события, который запускает соответствующее действие на основе имени события.
• Действия с сообщениями передаются обработчику действий сообщений, который выполняет дополнительную обработку, прежде чем решать, что делать дальше.

Если навык не может распознать тип входящего действия или имя события, он выдает сообщение об ошибке и завершает работу.

C#

DialogSkillBot\Dialogs\ActivityRouterDialog.cs

private async Task<DialogTurnResult> ProcessActivityAsync(WaterfallStepContext stepContext, CancellationToken cancellationToken)
{
    // A skill can send trace activities, if needed.
    await stepContext.Context.TraceActivityAsync($"{GetType().Name}.ProcessActivityAsync()", label: $"Got ActivityType: {stepContext.Context.Activity.Type}", cancellationToken: cancellationToken);

    switch (stepContext.Context.Activity.Type)
    {
        case ActivityTypes.Event:
            return await OnEventActivityAsync(stepContext, cancellationToken);

        case ActivityTypes.Message:
            return await OnMessageActivityAsync(stepContext, cancellationToken);

        default:
            // We didn't get an activity type we can handle.
            await stepContext.Context.SendActivityAsync(MessageFactory.Text($"Unrecognized ActivityType: \"{stepContext.Context.Activity.Type}\".", inputHint: InputHints.IgnoringInput), cancellationToken);
            return new DialogTurnResult(DialogTurnStatus.Complete);
    }
}

// This method performs different tasks based on the event name.
private async Task<DialogTurnResult> OnEventActivityAsync(WaterfallStepContext stepContext, CancellationToken cancellationToken)
{
    var activity = stepContext.Context.Activity;
    await stepContext.Context.TraceActivityAsync($"{GetType().Name}.OnEventActivityAsync()", label: $"Name: {activity.Name}. Value: {GetObjectAsJsonString(activity.Value)}", cancellationToken: cancellationToken);

    // Resolve what to execute based on the event name.
    switch (activity.Name)
    {
        case "BookFlight":
            return await BeginBookFlight(stepContext, cancellationToken);

        case "GetWeather":
            return await BeginGetWeather(stepContext, cancellationToken);

        default:
            // We didn't get an event name we can handle.
            await stepContext.Context.SendActivityAsync(MessageFactory.Text($"Unrecognized EventName: \"{activity.Name}\".", inputHint: InputHints.IgnoringInput), cancellationToken);
            return new DialogTurnResult(DialogTurnStatus.Complete);
    }
}

JavaScript

dialogSkillBot/dialogs/activityRouterDialog.js

async processActivity(stepContext) {
    // A skill can send trace activities, if needed.
    const traceActivity = {
        type: ActivityTypes.Trace,
        timestamp: new Date(),
        text: 'ActivityRouterDialog.processActivity()',
        label: `Got activityType: ${ stepContext.context.activity.type }`
    };
    await stepContext.context.sendActivity(traceActivity);

    switch (stepContext.context.activity.type) {
        case ActivityTypes.Event:
            return await this.onEventActivity(stepContext);
        case ActivityTypes.Message:
            return await this.onMessageActivity(stepContext);
        default:
            // Catch all for unhandled intents.
            await stepContext.context.sendActivity(
                `Unrecognized ActivityType: "${ stepContext.context.activity.type }".`,
                undefined,
                InputHints.IgnoringInput
            );
            return { status: DialogTurnStatus.complete };
    }
}

/**
 * This method performs different tasks based on event name.
 */
async onEventActivity(stepContext) {
    const activity = stepContext.context.activity;
    const traceActivity = {
        type: ActivityTypes.Trace,
        timestamp: new Date(),
        text: 'ActivityRouterDialog.onEventActivity()',
        label: `Name: ${ activity.name }, Value: ${ JSON.stringify(activity.value) }`
    };
    await stepContext.context.sendActivity(traceActivity);

    // Resolve what to execute based on the event name.
    switch (activity.name) {
        case 'BookFlight':
            return await this.beginBookFlight(stepContext);
        case 'GetWeather':
            return await this.beginGetWeather(stepContext);
        default:
            // We didn't get an event name we can handle.
            await stepContext.context.sendActivity(
                `Unrecognized EventName: "${ stepContext.context.activity.name }".`,
                undefined,
                InputHints.IgnoringInput
            );
            return { status: DialogTurnStatus.complete };
    }
}

Java

DialogSkillBot\Dialogs\ActivityRouterDialog.java

private CompletableFuture<DialogTurnResult> processActivity(WaterfallStepContext stepContext) {
    // A skill can send trace activities, if needed.
    TurnContext.traceActivity(
        stepContext.getContext(),
        String.format(
            "{%s}.processActivity() Got ActivityType: %s",
            this.getClass().getName(),
            stepContext.getContext().getActivity().getType()
        )
    );

    switch (stepContext.getContext().getActivity().getType()) {
        case ActivityTypes.EVENT:
            return onEventActivity(stepContext);

        case ActivityTypes.MESSAGE:
            return onMessageActivity(stepContext);

        default:
            String defaultMessage = String
                .format("Unrecognized ActivityType: \"%s\".", stepContext.getContext().getActivity().getType());
            // We didn't get an activity type we can handle.
            return stepContext.getContext()
                .sendActivity(MessageFactory.text(defaultMessage, defaultMessage, InputHints.IGNORING_INPUT))
                .thenCompose(result -> {
                    return CompletableFuture.completedFuture(new DialogTurnResult(DialogTurnStatus.COMPLETE));
                });

    }
}

// This method performs different tasks super. on the event name.
private CompletableFuture<DialogTurnResult> onEventActivity(WaterfallStepContext stepContext) {
    Activity activity = stepContext.getContext().getActivity();
    TurnContext.traceActivity(
        stepContext.getContext(),
        String.format(
            "%s.onEventActivity(), label: %s, Value: %s",
            this.getClass().getName(),
            activity.getName(),
            GetObjectAsJsonString(activity.getValue())
        )
    );

    // Resolve what to execute super. on the event name.
    switch (activity.getName()) {
        case "BookFlight":
            return beginBookFlight(stepContext);

        case "GetWeather":
            return beginGetWeather(stepContext);

        default:
            String message = String.format("Unrecognized EventName: \"%s\".", activity.getName());
            // We didn't get an event name we can handle.
            stepContext.getContext().sendActivity(MessageFactory.text(message, message, InputHints.IGNORING_INPUT));
            return CompletableFuture.completedFuture(new DialogTurnResult(DialogTurnStatus.COMPLETE));
    }
}

Python

dialog-skill-bot/dialogs/activity_router_dialog.py

async def process_activity(
    self, step_context: WaterfallStepContext
) -> DialogTurnResult:
    current_activity_type = step_context.context.activity.type

    # A skill can send trace activities, if needed.
    await step_context.context.send_trace_activity(
        f"{ActivityRouterDialog.__name__}.process_activity()",
        label=f"Got ActivityType: {current_activity_type}",
    )

    if current_activity_type == ActivityTypes.event:
        return await self._on_event_activity(step_context)
    if current_activity_type == ActivityTypes.message:
        return await self._on_message_activity(step_context)
    else:
        # We didn't get an activity type we can handle.
        await step_context.context.send_activity(
            MessageFactory.text(
                f'Unrecognized ActivityType: "{current_activity_type}".',
                input_hint=InputHints.ignoring_input,
            )
        )
        return DialogTurnResult(DialogTurnStatus.Complete)

async def _on_event_activity(
    self, step_context: WaterfallStepContext
) -> DialogTurnResult:
    """
    This method performs different tasks based on the event name.
    """

    activity = step_context.context.activity

    # Resolve what to execute based on the event name.
    if activity.name == "BookFlight":
        return await self._begin_book_flight(step_context)

    if activity.name == "GetWeather":
        return await self._begin_get_weather(step_context)

    # We didn't get an activity name we can handle.
    await step_context.context.send_activity(
        MessageFactory.text(
            f'Unrecognized ActivityName: "{activity.name}".',
            input_hint=InputHints.ignoring_input,
        )
    )
    return DialogTurnResult(DialogTurnStatus.Complete)

обработка действий сообщения;

Если настроен распознаватель LUIS, навык вызывает LUIS и запускает действие на основе намерения. Если распознаватель LUIS не настроен или намерение не поддерживается, навык отправляет сообщение об ошибке и заканчивается.

C#

DialogSkillBot\Dialogs\ActivityRouterDialog.cs

// This method just gets a message activity and runs it through LUIS. 
private async Task<DialogTurnResult> OnMessageActivityAsync(WaterfallStepContext stepContext, CancellationToken cancellationToken)
{
    var activity = stepContext.Context.Activity;
    await stepContext.Context.TraceActivityAsync($"{GetType().Name}.OnMessageActivityAsync()", label: $"Text: \"{activity.Text}\". Value: {GetObjectAsJsonString(activity.Value)}", cancellationToken: cancellationToken);

    if (!_luisRecognizer.IsConfigured)
    {
        await stepContext.Context.SendActivityAsync(MessageFactory.Text("NOTE: LUIS is not configured. To enable all capabilities, add 'LuisAppId', 'LuisAPIKey' and 'LuisAPIHostName' to the appsettings.json file.", inputHint: InputHints.IgnoringInput), cancellationToken);
    }
    else
    {
        // Call LUIS with the utterance.
        var luisResult = await _luisRecognizer.RecognizeAsync<FlightBooking>(stepContext.Context, cancellationToken);

        // Create a message showing the LUIS results.
        var sb = new StringBuilder();
        sb.AppendLine($"LUIS results for \"{activity.Text}\":");
        var (intent, intentScore) = luisResult.Intents.FirstOrDefault(x => x.Value.Equals(luisResult.Intents.Values.Max()));
        sb.AppendLine($"Intent: \"{intent}\" Score: {intentScore.Score}");

        await stepContext.Context.SendActivityAsync(MessageFactory.Text(sb.ToString(), inputHint: InputHints.IgnoringInput), cancellationToken);

        // Start a dialog if we recognize the intent.
        switch (luisResult.TopIntent().intent)
        {
            case FlightBooking.Intent.BookFlight:
                return await BeginBookFlight(stepContext, cancellationToken);

            case FlightBooking.Intent.GetWeather:
                return await BeginGetWeather(stepContext, cancellationToken);

            default:
                // Catch all for unhandled intents.
                var didntUnderstandMessageText = $"Sorry, I didn't get that. Please try asking in a different way (intent was {luisResult.TopIntent().intent})";
                var didntUnderstandMessage = MessageFactory.Text(didntUnderstandMessageText, didntUnderstandMessageText, InputHints.IgnoringInput);
                await stepContext.Context.SendActivityAsync(didntUnderstandMessage, cancellationToken);
                break;
        }
    }

    return new DialogTurnResult(DialogTurnStatus.Complete);
}

JavaScript

dialogSkillBot/dialogs/activityRouterDialog.js

/**
 * This method just gets a message activity and runs it through LUIS.
 */
async onMessageActivity(stepContext) {
    const activity = stepContext.context.activity;
    const traceActivity = {
        type: ActivityTypes.Trace,
        timestamp: new Date(),
        text: 'ActivityRouterDialog.onMessageActivity()',
        label: `Text: ${ activity.text }, Value: ${ JSON.stringify(activity.value) }`
    };
    await stepContext.context.sendActivity(traceActivity);

    if (!this.luisRecognizer || !this.luisRecognizer.isConfigured) {
        await stepContext.context.sendActivity(
            'NOTE: LUIS is not configured. To enable all capabilities, please add \'LuisAppId\', \'LuisAPIKey\' and \'LuisAPIHostName\' to the appsettings.json file.',
            undefined,
            InputHints.IgnoringInput
        );
    } else {
        // Call LUIS with the utterance.
        const luisResult = await this.luisRecognizer.executeLuisQuery(stepContext.context);
        const topIntent = LuisRecognizer.topIntent(luisResult);

        // Create a message showing the LUIS result.
        let resultString = '';
        resultString += `LUIS results for "${ activity.text }":\n`;
        resultString += `Intent: "${ topIntent }", Score: ${ luisResult.intents[topIntent].score }\n`;

        await stepContext.context.sendActivity(resultString, undefined, InputHints.IgnoringInput);

        switch (topIntent.intent) {
            case 'BookFlight':
                return await this.beginBookFlight(stepContext);
            case 'GetWeather':
                return await this.beginGetWeather(stepContext);
            default: {
                // Catch all for unhandled intents.
                const didntUnderstandMessageText = `Sorry, I didn't get that. Please try asking in a different way (intent was ${ topIntent.intent })`;
                await stepContext.context.sendActivity(didntUnderstandMessageText, didntUnderstandMessageText, InputHints.IgnoringInput);
                break;
            }
        }
    }

    return { status: DialogTurnStatus.complete };
}

Java

DialogSkillBot\Dialogs\ActivityRouterDialog.java

// This method just gets a message activity and runs it through LUS.
private CompletableFuture<DialogTurnResult> onMessageActivity(WaterfallStepContext stepContext) {
    Activity activity = stepContext.getContext().getActivity();
    TurnContext.traceActivity(
        stepContext.getContext(),
        String.format(
            "%s.onMessageActivity(), label: %s, Value: %s",
            this.getClass().getName(),
            activity.getName(),
            GetObjectAsJsonString(activity.getValue())
        )
    );

    if (!luisRecognizer.getIsConfigured()) {
        String message = "NOTE: LUIS instanceof not configured. To enable all capabilities, add 'LuisAppId',"
            + " 'LuisAPKey' and 'LuisAPHostName' to the appsettings.json file.";
        return stepContext.getContext()
            .sendActivity(MessageFactory.text(message, message, InputHints.IGNORING_INPUT))
            .thenCompose(
                result -> CompletableFuture.completedFuture(new DialogTurnResult(DialogTurnStatus.COMPLETE))
            );
    } else {
        // Call LUIS with the utterance.
        return luisRecognizer.recognize(stepContext.getContext(), RecognizerResult.class)
            .thenCompose(luisResult -> {
                // Create a message showing the LUS results.
                StringBuilder sb = new StringBuilder();
                sb.append(String.format("LUIS results for \"%s\":", activity.getText()));

                sb.append(
                    String.format(
                        "Intent: \"%s\" Score: %s",
                        luisResult.getTopScoringIntent().intent,
                        luisResult.getTopScoringIntent().score
                    )
                );

                return stepContext.getContext()
                    .sendActivity(MessageFactory.text(sb.toString(), sb.toString(), InputHints.IGNORING_INPUT))
                    .thenCompose(result -> {
                        switch (luisResult.getTopScoringIntent().intent.toLowerCase()) {
                            case "bookflight":
                                return beginBookFlight(stepContext);

                            case "getweather":
                                return beginGetWeather(stepContext);

                            default:
                                // Catch all for unhandled intents.
                                String didntUnderstandMessageText = String.format(
                                    "Sorry, I didn't get that. Please try asking in a different "
                                    + "way (intent was %s)",
                                    luisResult.getTopScoringIntent().intent
                                );
                                Activity didntUnderstandMessage = MessageFactory.text(
                                    didntUnderstandMessageText,
                                    didntUnderstandMessageText,
                                    InputHints.IGNORING_INPUT
                                );
                                return stepContext.getContext()
                                    .sendActivity(didntUnderstandMessage)
                                    .thenCompose(
                                        stepResult -> CompletableFuture
                                            .completedFuture(new DialogTurnResult(DialogTurnStatus.COMPLETE))
                                    );

                        }
                    });
                // Start a dialog if we recognize the intent.
            });
    }
}

Python

dialog-skill-bot/dialogs/activity_router_dialog.py

async def _on_message_activity(
    self, step_context: WaterfallStepContext
) -> DialogTurnResult:
    """
    This method just gets a message activity and runs it through LUIS.
    """

    activity = step_context.context.activity

    if not self._luis_recognizer.is_configured:
        await step_context.context.send_activity(
            MessageFactory.text(
                "NOTE: LUIS is not configured. To enable all capabilities, add 'LuisAppId', 'LuisAPIKey' and"
                " 'LuisAPIHostName' to the config.py file.",
                input_hint=InputHints.ignoring_input,
            )
        )
    else:
        # Call LUIS with the utterance.
        luis_result = await self._luis_recognizer.recognize(step_context.context)

        message = f'LUIS results for "{activity.Text}":\n'
        intent, intent_score = None, None
        if luis_result.intents:
            max_value_key = max(
                luis_result.intents, key=lambda key: luis_result.intents[key]
            )
            intent, intent_score = max_value_key, luis_result.intents[max_value_key]

        message += f'Intent: "{intent}" Score: {intent_score}\n'

        await step_context.context.send_activity(
            MessageFactory.text(message, input_hint=InputHints.ignoring_input,)
        )

        # Start a dialog if we recognize the intent.
        top_intent = luis_result.get_top_scoring_intent().intent

        if top_intent == "BookFlight":
            return await self._begin_book_flight(step_context)

        if top_intent == "GetWeather":
            return await self._begin_get_weather(step_context)

        # Catch all for unhandled intents.
        didnt_understand_message_text = f"Sorry, I didn't get that. Please try asking in a different way (intent was {top_intent})"
        await step_context.context.send_activity(
            MessageFactory.text(
                didnt_understand_message_text,
                didnt_understand_message_text,
                input_hint=InputHints.ignoring_input,
            )
        )

    return DialogTurnResult(DialogTurnStatus.Complete)

запуск многошагового действия;

Действие бронирования авиабилетов book-flight запускает многошаговый диалог для получения сведений о бронировании от пользователя.

Действие get-weather не реализовано. Сейчас оно возвращает заполнитель для сообщения и завершает работу.

C#

DialogSkillBot\Dialogs\ActivityRouterDialog.cs

private async Task<DialogTurnResult> BeginBookFlight(WaterfallStepContext stepContext, CancellationToken cancellationToken)
{
    var activity = stepContext.Context.Activity;
    var bookingDetails = new BookingDetails();
    if (activity.Value != null)
    {
        bookingDetails = JsonConvert.DeserializeObject<BookingDetails>(JsonConvert.SerializeObject(activity.Value));
    }

    // Start the booking dialog.
    var bookingDialog = FindDialog(nameof(BookingDialog));
    return await stepContext.BeginDialogAsync(bookingDialog.Id, bookingDetails, cancellationToken);
}

private static async Task<DialogTurnResult> BeginGetWeather(WaterfallStepContext stepContext, CancellationToken cancellationToken)
{
    var activity = stepContext.Context.Activity;
    var location = new Location();
    if (activity.Value != null)
    {
        location = JsonConvert.DeserializeObject<Location>(JsonConvert.SerializeObject(activity.Value));
    }

    // We haven't implemented the GetWeatherDialog so we just display a TODO message.
    var getWeatherMessageText = $"TODO: get weather for here (lat: {location.Latitude}, long: {location.Longitude}";
    var getWeatherMessage = MessageFactory.Text(getWeatherMessageText, getWeatherMessageText, InputHints.IgnoringInput);
    await stepContext.Context.SendActivityAsync(getWeatherMessage, cancellationToken);
    return new DialogTurnResult(DialogTurnStatus.Complete);
}

JavaScript

dialogSkillBot/dialogs/activityRouterDialog.js

async beginBookFlight(stepContext) {
    const activity = stepContext.context.activity;
    const bookingDetails = activity.value || {};

    // Start the booking dialog.
    const bookingDialog = this.findDialog(BOOKING_DIALOG);
    return await stepContext.beginDialog(bookingDialog.id, bookingDetails);
}

async beginGetWeather(stepContext) {
    const activity = stepContext.context.activity;
    const location = activity.value || {};

    // We haven't implemented the GetWeatherDialog so we just display a TODO message.
    const getWeatherMessageText = `TODO: get weather for here (lat: ${ location.latitude }, long: ${ location.longitude })`;
    await stepContext.context.sendActivity(getWeatherMessageText, getWeatherMessageText, InputHints.IgnoringInput);
    return { status: DialogTurnStatus.complete };
}

Java

DialogSkillBot\Dialogs\ActivityRouterDialog.java

private CompletableFuture<DialogTurnResult> beginBookFlight(WaterfallStepContext stepContext) {
    Activity activity = stepContext.getContext().getActivity();
    BookingDetails bookingDetails = new BookingDetails();
    if (activity.getValue() != null) {
        try {
            bookingDetails = Serialization.safeGetAs(activity.getValue(), BookingDetails.class);
        } catch (JsonProcessingException e) {
            // we already initialized bookingDetails above, so the flow will run as if
            // no details were sent.
        }
    }

    // Start the booking dialog.
    Dialog bookingDialog = findDialog("BookingDialog");
    return stepContext.beginDialog(bookingDialog.getId(), bookingDetails);
}

private static CompletableFuture<DialogTurnResult> beginGetWeather(WaterfallStepContext stepContext) {
    Activity activity = stepContext.getContext().getActivity();
    Location location = new Location();
    if (activity.getValue() != null) {
        try {
            location = Serialization.safeGetAs(activity.getValue(), Location.class);
        } catch (JsonProcessingException e) {
            // something went wrong, so we create an empty Location so we won't get a null
            // reference below when we acess location.
            location = new Location();
        }

    }

    // We haven't implemented the GetWeatherDialog so we just display a TODO
    // message.
    String getWeatherMessageText = String
        .format("TODO: get weather for here (lat: %s, long: %s)", location.getLatitude(), location.getLongitude());
    Activity getWeatherMessage =
        MessageFactory.text(getWeatherMessageText, getWeatherMessageText, InputHints.IGNORING_INPUT);
    return stepContext.getContext().sendActivity(getWeatherMessage).thenCompose(result -> {
        return CompletableFuture.completedFuture(new DialogTurnResult(DialogTurnStatus.COMPLETE));
    });

}

Python

dialog-skill-bot/dialogs/activity_router_dialog.py

async def _begin_book_flight(
    self, step_context: WaterfallStepContext
) -> DialogTurnResult:
    activity = step_context.context.activity
    booking_details = BookingDetails()
    if activity.value:
        booking_details.from_json(activity.value)

    # Start the booking dialog
    booking_dialog = await self.find_dialog(BookingDialog.__name__)
    return await step_context.begin_dialog(booking_dialog.id, booking_details)

async def _begin_get_weather(
    self, step_context: WaterfallStepContext
) -> DialogTurnResult:
    activity = step_context.context.activity
    location = Location()
    if activity.value:
        location.from_json(activity.value)

    # We haven't implemented the GetWeatherDialog so we just display a TODO message.
    get_weather_message = f"TODO: get weather for here (lat: {location.latitude}, long: {location.longitude}"
    await step_context.context.send_activity(
        MessageFactory.text(
            get_weather_message, get_weather_message, InputHints.ignoring_input,
        )
    )

    return DialogTurnResult(DialogTurnStatus.Complete)

возврат результата.

Навык запускает диалог бронирования для действия book-flight. Так как диалог activity-routing содержит только один шаг, при завершении диалога бронирования завершится и диалог activity-routing, а результат выполнения диалога бронирования автоматически становится результатом диалога activity-routing.

Действие get-weather просто завершается без возвращаемого значения.

Отмена многошагового действия

Диалог бронирования и его дочерний диалог date-resolver являются производными от базового диалога cancel-and-help, который проверяет получение сообщений от пользователя.

• При вводе help или ? он отображает справочную информацию и возвращается на следующем шаге в поток беседы.
• При вводе cancel или quit он завершает все диалоги, завершая работу навыка.

Дополнительные сведения см. в статье об обработке прерываний пользователя.

Регистрация службы

Для этого навыка нужны те же службы, что и для любого стандартного бота навыка. Требуемые службы обсуждаются в статье о реализации навыка.

Манифест навыка

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

C#

DialogSkillBot\wwwroot\manifest\dialogchildbot-manifest-1.0.json

{
  "$schema": "https://schemas.botframework.com/schemas/skills/skill-manifest-2.0.0.json",
  "$id": "DialogSkillBot",
  "name": "Skill bot with dialogs",
  "version": "1.0",
  "description": "This is a sample skill definition for multiple activity types.",
  "publisherName": "Microsoft",
  "privacyUrl": "https://dialogskillbot.contoso.com/privacy.html",
  "copyright": "Copyright (c) Microsoft Corporation. All rights reserved.",
  "license": "",
  "iconUrl": "https://dialogskillbot.contoso.com/icon.png",
  "tags": [
    "sample",
    "travel",
    "weather",
    "luis"
  ],
  "endpoints": [
    {
      "name": "default",
      "protocol": "BotFrameworkV3",
      "description": "Default endpoint for the skill.",
      "endpointUrl": "https://dialogskillbot.contoso.com/api/messages",
      "msAppId": "00000000-0000-0000-0000-000000000000"
    }
  ],
  "activities": {
    "bookFlight": {
      "description": "Books a flight (multi turn).",
      "type": "event",
      "name": "BookFlight",
      "value": {
        "$ref": "#/definitions/bookingInfo"
      },
      "resultValue": {
        "$ref": "#/definitions/bookingInfo"
      }
    },
    "getWeather": {
      "description": "Retrieves and returns the weather for the user's location.",
      "type": "event",
      "name": "GetWeather",
      "value": {
        "$ref": "#/definitions/location"
      },
      "resultValue": {
        "$ref": "#/definitions/weatherReport"
      }
    },
    "passthroughMessage": {
      "type": "message",
      "description": "Receives the user's utterance and attempts to resolve it using the skill's LUIS models.",
      "value": {
        "type": "object"
      }
    }
  },
  "definitions": {
    "bookingInfo": {
      "type": "object",
      "required": [
        "origin"
      ],
      "properties": {
        "origin": {
          "type": "string",
          "description": "This is the origin city for the flight."
        },
        "destination": {
          "type": "string",
          "description": "This is the destination city for the flight."
        },
        "travelDate": {
          "type": "string",
          "description": "The date for the flight in YYYY-MM-DD format."
        }
      }
    },
    "weatherReport": {
      "type": "array",
      "description": "Array of forecasts for the next week.",
      "items": [
        {
          "type": "string"
        }
      ]
    },
    "location": {
      "type": "object",
      "description": "Location metadata.",
      "properties": {
        "latitude": {
          "type": "number",
          "title": "Latitude"
        },
        "longitude": {
          "type": "number",
          "title": "Longitude"
        },
        "postalCode": {
          "type": "string",
          "title": "Postal code"
        }
      }
    }
  }
}

JavaScript

dialogSkillBot/manifest/dialogchildbot-manifest-1.0.json

{
  "$schema": "https://schemas.botframework.com/schemas/skills/skill-manifest-2.0.0.json",
  "$id": "dialogSkillBot",
  "name": "Skill bot with dialogs",
  "version": "1.0",
  "description": "This is a sample skill definition for multiple activity types.",
  "publisherName": "Microsoft",
  "privacyUrl": "https://dialogskillbot.contoso.com/privacy.html",
  "copyright": "Copyright (c) Microsoft Corporation. All rights reserved.",
  "license": "",
  "iconUrl": "https://dialogskillbot.contoso.com/icon.png",
  "tags": [
    "sample",
    "travel",
    "weather",
    "luis"
  ],
  "endpoints": [
    {
      "name": "default",
      "protocol": "BotFrameworkV3",
      "description": "Default endpoint for the skill.",
      "endpointUrl": "https://dialogskillbot.contoso.com/api/messages",
      "msAppId": "00000000-0000-0000-0000-000000000000"
    }
  ],
  "activities": {
    "bookFlight": {
      "description": "Books a flight (multi turn).",
      "type": "event",
      "name": "BookFlight",
      "value": {
        "$ref": "#/definitions/bookingInfo"
      },
      "resultValue": {
        "$ref": "#/definitions/bookingInfo"
      }
    },
    "getWeather": {
      "description": "Retrieves and returns the weather for the user's location.",
      "type": "event",
      "name": "GetWeather",
      "value": {
        "$ref": "#/definitions/location"
      },
      "resultValue": {
        "$ref": "#/definitions/weatherReport"
      }
    },
    "passthroughMessage": {
      "type": "message",
      "description": "Receives the user's utterance and attempts to resolve it using the skill's LUIS models.",
      "value": {
        "type": "object"
      }
    }
  },
  "definitions": {
    "bookingInfo": {
      "type": "object",
      "required": [
        "origin"
      ],
      "properties": {
        "origin": {
          "type": "string",
          "description": "This is the origin city for the flight."
        },
        "destination": {
          "type": "string",
          "description": "This is the destination city for the flight."
        },
        "travelDate": {
          "type": "string",
          "description": "The date for the flight in YYYY-MM-DD format."
        }
      }
    },
    "weatherReport": {
      "type": "array",
      "description": "Array of forecasts for the next week.",
      "items": [
        {
          "type": "string"
        }
      ]
    },
    "location": {
      "type": "object",
      "description": "Location metadata.",
      "properties": {
        "latitude": {
          "type": "number",
          "title": "Latitude"
        },
        "longitude": {
          "type": "number",
          "title": "Longitude"
        },
        "postalCode": {
          "type": "string",
          "title": "Postal code"
        }
      }
    }
  }
}

Java

dialog-skill-bot\webapp\manifest\dialogchildbot-manifest-1.0.json

{
  "$schema": "https://schemas.botframework.com/schemas/skills/skill-manifest-2.0.0.json",
  "$id": "DialogSkillBot",
  "name": "Skill bot with dialogs",
  "version": "1.0",
  "description": "This is a sample skill definition for multiple activity types.",
  "publisherName": "Microsoft",
  "privacyUrl": "https://dialogskillbot.contoso.com/privacy.html",
  "copyright": "Copyright (c) Microsoft Corporation. All rights reserved.",
  "license": "",
  "iconUrl": "https://dialogskillbot.contoso.com/icon.png",
  "tags": [
    "sample",
    "travel",
    "weather",
    "luis"
  ],
  "endpoints": [
    {
      "name": "default",
      "protocol": "BotFrameworkV3",
      "description": "Default endpoint for the skill.",
      "endpointUrl": "https://dialogskillbot.contoso.com/api/messages",
      "msAppId": "00000000-0000-0000-0000-000000000000"
    }
  ],
  "activities": {
    "bookFlight": {
      "description": "Books a flight (multi turn).",
      "type": "event",
      "name": "BookFlight",
      "value": {
        "$ref": "#/definitions/bookingInfo"
      },
      "resultValue": {
        "$ref": "#/definitions/bookingInfo"
      }
    },
    "getWeather": {
      "description": "Retrieves and returns the weather for the user's location.",
      "type": "event",
      "name": "GetWeather",
      "value": {
        "$ref": "#/definitions/location"
      },
      "resultValue": {
        "$ref": "#/definitions/weatherReport"
      }
    },
    "passthroughMessage": {
      "type": "message",
      "description": "Receives the user's utterance and attempts to resolve it using the skill's LUIS models.",
      "value": {
        "type": "object"
      }
    }
  },
  "definitions": {
    "bookingInfo": {
      "type": "object",
      "required": [
        "origin"
      ],
      "properties": {
        "origin": {
          "type": "string",
          "description": "This is the origin city for the flight."
        },
        "destination": {
          "type": "string",
          "description": "This is the destination city for the flight."
        },
        "travelDate": {
          "type": "string",
          "description": "The date for the flight in YYYY-MM-DD format."
        }
      }
    },
    "weatherReport": {
      "type": "array",
      "description": "Array of forecasts for the next week.",
      "items": [
        {
          "type": "string"
        }
      ]
    },
    "location": {
      "type": "object",
      "description": "Location metadata.",
      "properties": {
        "latitude": {
          "type": "number",
          "title": "Latitude"
        },
        "longitude": {
          "type": "number",
          "title": "Longitude"
        },
        "postalCode": {
          "type": "string",
          "title": "Postal code"
        }
      }
    }
  }
}

Python

dialog-skill-bot/wwwroot/manifest/dialogchildbot-manifest-1.0.json

{
  "$schema": "https://schemas.botframework.com/schemas/skills/skill-manifest-2.0.0.json",
  "$id": "DialogSkillBot",
  "name": "Skill bot with dialogs",
  "version": "1.0",
  "description": "This is a sample skill definition for multiple activity types.",
  "publisherName": "Microsoft",
  "privacyUrl": "https://dialogskillbot.contoso.com/privacy.html",
  "copyright": "Copyright (c) Microsoft Corporation. All rights reserved.",
  "license": "",
  "iconUrl": "https://dialogskillbot.contoso.com/icon.png",
  "tags": [
    "sample",
    "travel",
    "weather",
    "luis"
  ],
  "endpoints": [
    {
      "name": "default",
      "protocol": "BotFrameworkV3",
      "description": "Default endpoint for the skill.",
      "endpointUrl": "https://dialogskillbot.contoso.com/api/messages",
      "msAppId": "00000000-0000-0000-0000-000000000000"
    }
  ],
  "activities": {
    "bookFlight": {
      "description": "Books a flight (multi turn).",
      "type": "event",
      "name": "BookFlight",
      "value": {
        "$ref": "#/definitions/bookingInfo"
      },
      "resultValue": {
        "$ref": "#/definitions/bookingInfo"
      }
    },
    "getWeather": {
      "description": "Retrieves and returns the weather for the user's location.",
      "type": "event",
      "name": "GetWeather",
      "value": {
        "$ref": "#/definitions/location"
      },
      "resultValue": {
        "$ref": "#/definitions/weatherReport"
      }
    },
    "passthroughMessage": {
      "type": "message",
      "description": "Receives the user's utterance and attempts to resolve it using the skill's LUIS models.",
      "value": {
        "type": "object"
      }
    }
  },
  "definitions": {
    "bookingInfo": {
      "type": "object",
      "required": [
        "origin"
      ],
      "properties": {
        "origin": {
          "type": "string",
          "description": "This is the origin city for the flight."
        },
        "destination": {
          "type": "string",
          "description": "This is the destination city for the flight."
        },
        "travelDate": {
          "type": "string",
          "description": "The date for the flight in YYYY-MM-DD format."
        }
      }
    },
    "weatherReport": {
      "type": "array",
      "description": "Array of forecasts for the next week.",
      "items": [
        {
          "type": "string"
        }
      ]
    },
    "location": {
      "type": "object",
      "description": "Location metadata.",
      "properties": {
        "latitude": {
          "type": "number",
          "title": "Latitude"
        },
        "longitude": {
          "type": "number",
          "title": "Longitude"
        },
        "postalCode": {
          "type": "string",
          "title": "Postal code"
        }
      }
    }
  }
}

Схема манифеста навыка — это файл в формате JSON с описанием схемы манифеста навыков. Последняя версия схемы — версия 2.1.

Тестирование бота навыка

Вы можете проверить навык в эмуляторе с помощью потребителя навыков. Для этого одновременно запустите оба бота (навыка и потребителя навыка). Сведения о настройке навыка см. в статье об использовании навыков с помощью диалога.

Скачайте и установите последнюю версию Bot Framework Emulator.

1. Запустите бот навыка диалога и корневой бот диалога локально на компьютере. Если вам нужны инструкции, ознакомьтесь с файлом примера README для C#, JavaScript, JavaScript или Python.
2. Примените эмулятор для тестирования бота.
   • Когда вы впервые присоединяетесь к беседе, бот отображает приветственное сообщение и спрашивает, какой навык вы хотите вызвать. В нашем примере бота навыков есть всего один навык.
   • Выберите DialogSkillBot.
3. Затем бот просит выбрать действие для навыка. Выберите BookFlight.
   1. Навык начинает работу с действия book-flight, а вам нужно ответить на вопросы.
   2. Когда навык завершит работу, корневой бот отобразит сведения о резервировании и снова предложит вам вызвать навык.
4. Снова выберите DialogSkillBot и BookFlight.
   1. Ответьте на первый вопрос, а затем введите cancel, чтобы отменить действие.
   2. Бот навыка завершит работу, не завершив действие, а потребитель снова предложит вам вызвать навык.

Дополнительные сведения об отладке

Так как трафик между навыками и потребителями навыков проходит проверку подлинности, при отладке таких ботов выполняются дополнительные действия.

• Потребитель навыка и все навыки, которые он потребляет, прямо или косвенно, должны работать.
• Если боты работают локально и если у любого из ботов есть идентификатор приложения и пароль, все боты должны иметь действительные идентификаторы и пароли.
• Если боты развернуты, узнайте, как отладить бота из любого канала с помощью devtunnel.
• Если некоторые боты выполняются локально, а некоторые развертываются, см. инструкции по отладке навыка или потребителя навыков.

В противном случае можно отладить потребителя навыка или навыка, как отладить другие боты. Дополнительные сведения см. в статье отладка бота и отладка с помощью эмулятора Bot Framework.

Дополнительная информация:

• См. сведения в статье Использование навыка с помощью диалога.