共用方式為

使用技能內的對話框

  • 發行項

適用於： SDK v4

本文示範如何建立支援多個動作的技能。 它支援使用對話框的這些動作。 主要對話框會接收技能取用者的初始輸入，然後啟動適當的動作。 如需了解如何為相關範例程式中的技能消費者進行實作的資訊，請參閱如何使用對話框使用技能。

本文假設您已熟悉開發技能。 如需了解如何大致建立一個技能機器人，請參閱如何 實作技能。

注意

Bot Framework JavaScript、C# 和 Python SDK 將會繼續受到支援，不過，Java SDK 即將淘汰，最終長期支援將於 2023 年 11 月結束。

使用 Java SDK 建置的現有 Bot 將繼續運作。

針對新的 Bot 建置，請考慮使用 Microsoft Copilot Studio ，並閱讀 選擇正確的 Copilot 解決方案。

如需詳細資訊，請參閱 Bot 建置的未來。

必要條件

注意

Language Understanding （LUIS） 將於 2025 年 10 月 1 日淘汰。 從 2023 年 4 月 1 日起，您將無法建立新的 LUIS 資源。 新版的語言理解現在已提供作為 Azure AI 語言的一部分。

對話式語言理解（CLU）是 Azure AI 語言的一項功能，是 LUIS 的更新版本。 如需 Bot Framework SDK 中語言理解支援的詳細資訊，請參閱 自然語言理解。

關於此範例

技能技能Dialog 範例包含兩個 Bot 的專案：

  • 使用對話根機器人，它會使用技能對話類別來消耗技能。
  • 對話 技能 Bot，它會使用對話來處理來自技能取用者的活動。 此技能是對核心 bot範例的改編。 （如需核心 Bot 的詳細資訊，請參閱如何將 自然語言理解新增至 Bot。

本文著重於如何使用技能 Bot 內的對話框來管理多個動作。

如需技能消費者 bot 的相關信息，請參閱如何透過對話框來取用技能。

資源

對於已部署的 Bot，Bot 對 Bot 驗證會要求每個參與的 Bot 都有有效的身分識別。 不過，您可以使用 Bot Framework 模擬器在本機測試技能和技能取用者，而不需要身分識別資訊。

若要讓技能可供使用者面向的 Bot 使用，請向 Azure 註冊技能。 如需詳細資訊，請參閱如何使用 Azure AI Bot Service 註冊 Bot。

可選擇性地，技能 Bot 可以使用飛行預訂的 LUIS 模型。 若要使用此模型，請使用 CognitiveModels/FlightBooking.json 檔案來建立、定型及發佈 LUIS 模型。

應用程式設定

  1. 或者，將技能的身分識別資訊新增至技能的組態檔。 （如果技能或技能取用者指定身分識別，則兩者都必須。

  2. 如果您使用 LUIS 模型，請新增 LUIS 應用程式識別碼、API 金鑰和 API 主機名。

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": [ "*" ]
}

活動路由邏輯

技能支援幾個不同的功能。 它可以預訂航班或取得城市的天氣。 此外，如果它收到上述任一內容以外的訊息，則可以使用 LUIS 嘗試解譯訊息。 技能的指令清單會描述這些動作、其輸入和輸出參數，以及技能的端點。 請注意，技能可以處理 「BookFlight」 或 「GetWeather」 事件。 它也可以處理訊息活動。

技能會定義活動路由對話框，其會根據技能取用者的初始傳入活動，選取要起始的動作。 如果提供，LUIS 模型可以在初始訊息中辨識預訂航班和查詢天氣的意圖類型。

機票預訂操作屬於一個多步驟過程，並實作為單獨的對話框。 動作開始后，該對話框會處理傳入的活動。 get-weather 動作具有將在完全實作的 Bot 中取代的佔位符邏輯。

活動路由對話框包含下列項目的程式代碼：

技能中使用的對話會繼承自 元件對話 類別。 如需元件對話的詳細資訊，請參閱如何 管理對話複雜度。

初始化對話框

活動路由對話框包含用於預訂航班的子對話。 主要瀑布式對話有一個步驟，會根據收到的初始活動啟動動作。

它也接受 LUIS 辨識器。 如果初始化此辨識器，對話框會使用它來解譯初始訊息活動的意圖。

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

處理初始活動

在主要瀑布對話的第一個步驟中，技能會檢查傳入的活動類型。

  • 事件活動會轉送至 事件活動 處理程式上的 ，此處理程式會根據事件的名稱啟動適當的動作。
  • 訊息活動會轉送至 訊息活動 處理程式，此處理程式會在決定行動之前執行其他處理。

如果技能無法辨識傳入活動的類型或事件的名稱，則會傳送錯誤訊息並結束。

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

處理訊息活動

如果已設定 LUIS 辨識器，技能會呼叫 LUIS，然後根據意圖啟動動作。 如果未設定 LUIS 辨識器或不支援意圖，則技能會傳送錯誤訊息並結束。

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

開始多步驟動作

預訂航班動作會啟動一個多步驟對話，以從使用者取得預訂詳細資訊。

未實作 get-weather 動作。 目前，它會傳送佔位訊息，然後結束。

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

傳回結果

技能會啟動預訂對話框，以進行預訂班機動作。 由於活動路由對話只有一個步驟，所以當預約對話結束時，活動路由對話框也會結束，而預約對話中的對話框結果會變成活動路由對話框的對話結果。

「get-weather」動作會直接結束，而不設定傳回值。

取消多步驟動作

預訂對話框及其子日期解析器對話框都衍生自基底取消與說明對話框，該對話框會檢查來自使用者的訊息。

  • 在 [說明] 或 [？“] 上，它會顯示說明訊息，然後在下列回合繼續對話流程。
  • 在按下「取消」或「結束」時，將會取消所有對話框，並結束該技能。

如需詳細資訊，請參閱如何處理 用戶中斷。

服務註冊

此技能所需的服務與一般技能 Bot 所需的服務相同。 請參閱如何實作技能，以了解所需服務的討論。

技能清單

技能指令清單是 JSON 檔案，描述技能可執行的活動、其輸入和輸出參數，以及技能的端點。 清單包含從另一個機器人存取技能所需的資訊。

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

技能指令清單架構是描述技能指令清單架構的 JSON 檔案。 最新的架構版本是 v2.1。

測試技能機器人

您可以在模擬器中使用技能消費者來測試技能。 若要這樣做，您必須同時執行技能與技能取用者 Bot。 如需如何設定技能的相關信息，請參閱如何使用 對話框來取用技能 。

下載並安裝最新的 Bot Framework 模擬器。

  1. 在本機計算機上執行對話技能 Bot 和對話根 Bot。 如果您需要指示，請參閱範例的 READMEC#、JavaScript、Java 或 Python 檔案。
  2. 使用模擬器來測試 Bot。
    • 當您第一次加入交談時，Bot 會顯示歡迎訊息，並詢問您想要呼叫的技能。 此範例的技能 Bot 只有一個技能。
    • 選取 DialogSkillBot。
  3. 接下來，Bot 會要求您選擇技能的動作。 選擇 [BookFlight]。
    1. 技能開始進行預訂航班的操作，請回答提示。
    2. 技能完成時，主控機器人會顯示預約詳細資訊，然後再次提示您選擇要呼叫的技能。
  4. 再次選取 DialogSkillBot 和 “BookFlight”。
    1. 回答第一個提示，然後輸入 「cancel」 以取消動作。
    2. 技能機器人在未完成動作時結束，而使用者會提示您呼叫想要的技能。

更多偵錯相關內容

由於技能與技能取用者之間的流量已經過驗證，因此偵錯這類 Bot 時會有額外的步驟。

  • 技能消耗者及其直接或間接消耗的所有技能都必須在運行中。
  • 如果 Bot 在本機執行，且任何 Bot 都有應用程式識別碼和密碼，則所有 Bot 都必須具有有效的標識碼和密碼。
  • 如果所有 Bot 已部署，查看如何使用 devtunnel 從任何通道偵錯 Bot。
  • 如果某些 Bot 在本機執行，而有些 Bot 已部署，請參閱如何偵錯技能或技能使用者。

否則，您可以偵錯技能取用者或技能，就像偵錯其他 Bot 一樣。 如需詳細資訊，請參閱偵錯 Bot和使用 Bot Framework 模擬器進行偵錯。

其他資訊