ダイアログを使用してスキルを利用する

適用対象: SDK v4

この記事では、スキル コンシューマー内で "スキル ダイアログ" を使用する方法について説明します。 スキル ダイアログでは、親ボットからスキル ボットにアクティビティがポストされ、スキルの応答がユーザーに返されます。 このコンシューマーによってアクセスされるスキル ボットでは、メッセージ アクティビティとイベント アクティビティの両方を処理できます。 スキル マニフェストのサンプルおよびスキルの実装に関する情報については、スキル内でダイアログを使用する方法を参照してください。

ダイアログ外でスキル ボットを使用する方法については、スキル コンシューマーを実装する方法を参照してください。

Important

Bot Framework SDK と Bot Framework Emulator は GitHub にアーカイブされています。 プロジェクトが更新または保守されなくなりました。 Bot Framework SDK のサポート チケットは、2025 年 12 月 31 日の時点で提供されなくなります。

AI サービス、オーケストレーション、知識を選択してエージェントを構築するには、Microsoft 365 Agents SDK の使用を検討してください。 Agents SDK には、C#、JavaScript、または Python の言語サポートがあります。 Agents SDK の詳細については、 aka.ms/agents を参照してください。 Bot Framework SDK を使用して構築された既存のボットがある場合は、ボットを Agents SDK に更新できます。 Bot Framework SDK から Agents SDK への移行ガイダンスで、主要な変更と更新を確認します。

Microsoft Teams内で動作するように設計されたコラボレーション エージェントを構築する場合は、Teams SDK の使用を検討してください。 Teams 環境で実行されるエージェントに対して、Teams 固有の API、アダプティブ カードのサポート、組み込みの AI オーケストレーションが提供されます。 詳細については、 Teams SDK (Teams AI ライブラリ) を参照してください。

SaaS ベースのエージェント プラットフォームをお探しの場合は、 Microsoft Copilot Studio を検討してください。

前提条件

このサンプルについて

skills skillDialog サンプルには、次の 2 つのボットのプロジェクトが含まれています。

  • ダイアログ ルート ボットは、スキル ダイアログクラスを使用してスキルを利用します。
  • "ダイアログ スキル ボット"。ダイアログを使用して、スキル コンシューマーからのアクティビティを処理します。

この記事では、ルート ボットで "スキル ダイアログ" クラスを使用してスキルを管理する方法、メッセージ アクティビティとイベント アクティビティを送信する方法、およびスキルをキャンセルする方法について説明します。

スキル コンシューマーの作成に関するその他の側面については、スキル コンシューマーを実装する方法を参照してください。

ダイアログ スキル ボットについては、スキル内でダイアログを使用する方法を参照してください。

リソース

デプロイ済みのボットの場合、ボット間認証では、参加している各ボットが有効な ID を保持している必要があります。 ただし、ID 情報なしで Bot Framework Emulator を使用して、ローカルでスキルとスキル コンシューマーをテストできます。

アプリケーション構成

  1. 必要に応じて、ルート ボットの ID 情報を構成ファイルに追加します。
  2. スキルがスキル コンシューマーに応答するスキル ホスト エンドポイント (サービスまたはコールバックURL) を追加します。
  3. スキル コンシューマーが使用するスキルごとにエントリを追加します。 各エントリには次のものが含まれます。
    • スキルコンシューマーが各スキルを識別するために使用するID。
    • 必要に応じて、スキル ボットのアプリ ID またはクライアント ID。
    • スキルのメッセージング エンドポイント。

メモ

スキルまたはスキル コンシューマーのいずれかが ID を指定している場合は、両方を指定する必要があります。

DialogRootBot\appsettings.js作動中

必要に応じて、ルート ボットの ID 情報を追加し、エコー スキル ボット用のアプリ ID またはクライアント ID を BotFrameworkSkills 配列に追加します。

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

  "SkillHostEndpoint": "http://localhost:3978/api/skills/",
  "BotFrameworkSkills": [
    {
      "Id": "DialogSkillBot",
      "AppId": "",
      "SkillEndpoint": "http://localhost:39783/api/messages"
    }
  ]
}

ダイアログ ロジック

ボットのメイン ダイアログには、このボットで使用する各スキルの "スキル ダイアログ" が含まれています。 スキル ダイアログでは、スキルに関連するさまざまなオブジェクト ("スキル クライアント" オブジェクトや "スキル会話 ID ファクトリ" オブジェクトなど) を通じてスキルが自動的に管理されます。 メイン ダイアログでは、ユーザー入力に基づいて (スキル ダイアログを通じて) スキルをキャンセルする方法も示します。

このボットで使用されるスキルでは、いくつかの異なる機能がサポートされています。 フライトを予約したり、都市の天気を取得したりできます。 また、これらのいずれかのコンテキストの外部でメッセージを受信し、LUIS 認識エンジンが構成されている場合、ユーザーの意図の解釈が試行されます。

メモ

Language Understanding (LUIS) は、2025 年 10 月 1 日に廃止されます。 2023 年 4 月 1 日以降は、新しい LUIS リソースを作成することはできません。 より新しいバージョンの言語理解が、現在、Azure AI Language の一部として提供されています。

Azure AI Language の機能である会話言語理解 (CLU) は、LUIS の更新バージョンです。 Bot Framework SDK での言語理解のサポートの詳細については、「自然言語の理解」を参照してください。

スキル マニフェスト (C#、JavaScript、Java、Python) は、スキルが実行できるアクション、その入出力パラメーター、およびスキルのエンドポイントを記述したものです。 注目すべき点として、このスキルでは "BookFlight" イベントや "GetWeather" イベントを処理できます。 また、メッセージを処理することもできます。

メイン ダイアログには、次のことを行うコードが含まれています。

メイン ダイアログは、"コンポーネント ダイアログ" クラスから継承されます。 コンポーネント ダイアログの詳細については、ダイアログの複雑さを管理する方法を参照してください。

メイン ダイアログを初期化する

メイン ダイアログには、ダイアログ (スキルの外部にある会話フローの管理用) とスキル ダイアログ (スキルの管理用) が含まれています。 ウォーターフォールには、次の手順が含まれています。詳細については、次のいくつかのセクションで説明します。

  1. 使用するスキルを選択するようユーザーに要求します ルートボットは1つのスキルを消費します。
  2. そのスキルに使用するアクションを選択するよう、ユーザーに要求します (スキル ボットでは 3 つのアクションが定義されます。)
  3. 選択したスキルを開始します。初期アクティビティは、選択したアクションに基づきます。
  4. スキルが完了したら、結果を表示します (ある場合)。 その後、ウォーターフォールを再起動します。

DialogRootBot\Dialogs\MainDialog.cs

MainDialog クラスは、ComponentDialog から派生したものです。 会話の状態に加えて、ダイアログにはルート ボットの ID と、スキル会話 ID ファクトリ、スキル HTTP クライアント、およびスキル構成オブジェクトへの参照が必要です。

ダイアログ コンストラクターでは、その入力パラメーターが確認され、スキル ダイアログが追加され、スキルの外部にある会話フローを管理するためにプロンプトとウォーターフォール ダイアログが追加され、アクティブなスキル (ある場合) を追跡するためにプロパティ アクセサーが作成されます。

構成ファイルから AddSkillDialogs オブジェクトに読み込まれる際に、コンストラクターによりヘルパー メソッド SkillDialog が呼び出されて、構成ファイルに含まれる各スキルに対して SkillsConfiguration が作成されます。

// Helper method that creates and adds SkillDialog instances for the configured skills.
private void AddSkillDialogs(ConversationState conversationState, SkillConversationIdFactoryBase conversationIdFactory, SkillsConfiguration skillsConfig, string botId)
{
    foreach (var skillInfo in _skillsConfig.Skills.Values)
    {
        // Create the dialog options.
        var skillDialogOptions = new SkillDialogOptions
        {
            BotId = botId,
            ConversationIdFactory = conversationIdFactory,
            SkillClient = _auth.CreateBotFrameworkClient(),
            SkillHostEndpoint = skillsConfig.SkillHostEndpoint,
            ConversationState = conversationState,
            Skill = skillInfo
        };

        // Add a SkillDialog for the selected skill.
        AddDialog(new SkillDialog(skillDialogOptions, skillInfo.Id));
    }
}

スキルを選択する

最初の手順では、メイン ダイアログで、呼び出すスキルを入力するようユーザーに要求し、"SkillPrompt" プロンプトを使用して回答を取得します (このボットで定義されるスキルは 1 つだけです)。

DialogRootBot\Dialogs\MainDialog.cs

// Render a prompt to select the skill to call.
private async Task<DialogTurnResult> SelectSkillStepAsync(WaterfallStepContext stepContext, CancellationToken cancellationToken)
{
    // Create the PromptOptions from the skill configuration which contain the list of configured skills.
    var messageText = stepContext.Options?.ToString() ?? "What skill would you like to call?";
    var repromptMessageText = "That was not a valid choice, please select a valid skill.";
    var options = new PromptOptions
    {
        Prompt = MessageFactory.Text(messageText, messageText, InputHints.ExpectingInput),
        RetryPrompt = MessageFactory.Text(repromptMessageText, repromptMessageText, InputHints.ExpectingInput),
        Choices = _skillsConfig.Skills.Select(skill => new Choice(skill.Value.Id)).ToList()
    };

    // Prompt the user to select a skill.
    return await stepContext.PromptAsync("SkillPrompt", options, cancellationToken);
}

スキル アクションを選択する

次の手順では、メイン ダイアログで次の操作を行います。

  1. ユーザーが選択したスキルに関する情報を保存します。
  2. 使用するスキル アクションをユーザーに要求し、"SkillActionPrompt" 選択プロンプトを使用して回答を取得します。
    • ヘルパー メソッドを使用して、選択元となるアクションの一覧を取得します。
    • このプロンプトに関連付けられているプロンプト検証コントロールでは、ユーザーの入力がいずれかの選択肢に一致しない場合、既定でスキルにメッセージが送信されます。

このボットに含まれる選択肢は、このスキルに対して定義されているアクションをテストするのに役立ちます。 通常は、スキルのマニフェストからオプションを読み取り、その一覧に基づいてユーザーにオプションを表示します。

DialogRootBot\Dialogs\MainDialog.cs

// Render a prompt to select the action for the skill.
private async Task<DialogTurnResult> SelectSkillActionStepAsync(WaterfallStepContext stepContext, CancellationToken cancellationToken)
{
    // Get the skill info based on the selected skill.
    var selectedSkillId = ((FoundChoice)stepContext.Result).Value;
    var selectedSkill = _skillsConfig.Skills.FirstOrDefault(s => s.Value.Id == selectedSkillId).Value;

    // Remember the skill selected by the user.
    stepContext.Values[_selectedSkillKey] = selectedSkill;

    // Create the PromptOptions with the actions supported by the selected skill.
    var messageText = $"Select an action # to send to **{selectedSkill.Id}** or just type in a message and it will be forwarded to the skill";
    var options = new PromptOptions
    {
        Prompt = MessageFactory.Text(messageText, messageText, InputHints.ExpectingInput),
        Choices = GetSkillActions(selectedSkill)
    };

    // Prompt the user to select a skill action.
    return await stepContext.PromptAsync("SkillActionPrompt", options, cancellationToken);
}
// Helper method to create Choice elements for the actions supported by the skill.
private IList<Choice> GetSkillActions(BotFrameworkSkill skill)
{
    // Note: the bot would probably render this by reading the skill manifest.
    // We are just using hardcoded skill actions here for simplicity.

    var choices = new List<Choice>();
    switch (skill.Id)
    {
        case "DialogSkillBot":
            choices.Add(new Choice(SkillActionBookFlight));
            choices.Add(new Choice(SkillActionBookFlightWithInputParameters));
            choices.Add(new Choice(SkillActionGetWeather));
            break;
    }

    return choices;
}
// This validator defaults to Message if the user doesn't select an existing option.
private Task<bool> SkillActionPromptValidator(PromptValidatorContext<FoundChoice> promptContext, CancellationToken cancellationToken)
{
    if (!promptContext.Recognized.Succeeded)
    {
        // Assume the user wants to send a message if an item in the list is not selected.
        promptContext.Recognized.Value = new FoundChoice { Value = SkillActionMessage };
    }

    return Task.FromResult(true);
}

スキルを開始する

次の手順では、メイン ダイアログで次の操作を行います。

  1. ユーザーが選択したスキルとスキル アクティビティに関する情報を取得します。
  2. ヘルパー メソッドを使用して、最初にスキルに送信するアクティビティを作成します。
  3. スキル ダイアログを開始するためのダイアログ オプションを作成します。 これには、送信する最初のアクティビティが含まれます。
  4. スキルを呼び出す前に状態を保存します (これは、スキルの応答がスキル コンシューマーの別のインスタンスに由来する可能性があるため、必要です)。
  5. スキル ダイアログを開始し、呼び出すスキル ID と、それを呼び出すオプションを渡します。

DialogRootBot\Dialogs\MainDialog.cs

// Starts the SkillDialog based on the user's selections.
private async Task<DialogTurnResult> CallSkillActionStepAsync(WaterfallStepContext stepContext, CancellationToken cancellationToken)
{
    var selectedSkill = (BotFrameworkSkill)stepContext.Values[_selectedSkillKey];

    Activity skillActivity;
    switch (selectedSkill.Id)
    {
        case "DialogSkillBot":
            skillActivity = CreateDialogSkillBotActivity(((FoundChoice)stepContext.Result).Value, stepContext.Context);
            break;

        // We can add other case statements here if we support more than one skill.
        default:
            throw new Exception($"Unknown target skill id: {selectedSkill.Id}.");
    }

    // Create the BeginSkillDialogOptions and assign the activity to send.
    var skillDialogArgs = new BeginSkillDialogOptions { Activity = skillActivity };

    // Save active skill in state.
    await _activeSkillProperty.SetAsync(stepContext.Context, selectedSkill, cancellationToken);

    // Start the skillDialog instance with the arguments. 
    return await stepContext.BeginDialogAsync(selectedSkill.Id, skillDialogArgs, cancellationToken);
}

スキル結果を要約する

最後の手順では、メイン ダイアログで次の操作を行います。

  1. スキルによって値が返された場合は、結果をユーザーに表示します。
  2. ダイアログの状態からアクティブなスキルをクリアします。
  3. 会話の状態からアクティブなスキル プロパティを削除します。
  4. 自動的に再起動します (メイン ダイアログ)。

DialogRootBot\Dialogs\MainDialog.cs

// The SkillDialog has ended, render the results (if any) and restart MainDialog.
private async Task<DialogTurnResult> FinalStepAsync(WaterfallStepContext stepContext, CancellationToken cancellationToken)
{
    var activeSkill = await _activeSkillProperty.GetAsync(stepContext.Context, () => null, cancellationToken);

    // Check if the skill returned any results and display them.
    if (stepContext.Result != null)
    {
        var message = $"Skill \"{activeSkill.Id}\" invocation complete.";
        message += $" Result: {JsonConvert.SerializeObject(stepContext.Result)}";
        await stepContext.Context.SendActivityAsync(MessageFactory.Text(message, message, inputHint: InputHints.IgnoringInput), cancellationToken: cancellationToken);
    }

    // Clear the skill selected by the user.
    stepContext.Values[_selectedSkillKey] = null;

    // Clear active skill in state.
    await _activeSkillProperty.DeleteAsync(stepContext.Context, cancellationToken);

    // Restart the main dialog with a different message the second time around.
    return await stepContext.ReplaceDialogAsync(InitialDialogId, $"Done with \"{activeSkill.Id}\". \n\n What skill would you like to call?", cancellationToken);
}

スキルのキャンセルをユーザーに許可する

メイン ダイアログでは、on continue dialog メソッドの既定の動作がオーバーライドされて、ユーザーは現在のスキル (ある場合) をキャンセルできます。 メソッド内:

  • アクティブなスキルがあり、ユーザーが "abort" メッセージを送信した場合は、すべてのダイアログをキャンセルし、メイン ダイアログをキューに入れて最初から再開します。
  • 次に、on continue dialog メソッドの基本実装を呼び出して、現在のターンの処理を続行します。

DialogRootBot\Dialogs\MainDialog.cs

protected override async Task<DialogTurnResult> OnContinueDialogAsync(DialogContext innerDc, CancellationToken cancellationToken = default)
{
    // This is an example on how to cancel a SkillDialog that is currently in progress from the parent bot.
    var activeSkill = await _activeSkillProperty.GetAsync(innerDc.Context, () => null, cancellationToken);
    var activity = innerDc.Context.Activity;
    if (activeSkill != null && activity.Type == ActivityTypes.Message && activity.Text.Equals("abort", StringComparison.OrdinalIgnoreCase))
    {
        // Cancel all dialogs when the user says abort.
        // The SkillDialog automatically sends an EndOfConversation message to the skill to let the
        // skill know that it needs to end its current dialogs, too.
        await innerDc.CancelAllDialogsAsync(cancellationToken);
        return await innerDc.ReplaceDialogAsync(InitialDialogId, "Canceled! \n\n What skill would you like to call?", cancellationToken);
    }

    return await base.OnContinueDialogAsync(innerDc, cancellationToken);
}

アクティビティ ハンドラーのロジック

各ターンのスキル ロジックはメイン ダイアログで処理されるため、アクティビティ ハンドラーは他のダイアログ サンプルの場合と同じように見えます。

DialogRootBot\Bots\RootBot.cs

public class RootBot<T> : ActivityHandler
    where T : Dialog

private readonly ConversationState _conversationState;
private readonly Dialog _mainDialog;

public RootBot(ConversationState conversationState, T mainDialog)
{
    _conversationState = conversationState;
    _mainDialog = mainDialog;
}

public override async Task OnTurnAsync(ITurnContext turnContext, CancellationToken cancellationToken = default)
{
    if (turnContext.Activity.Type != ActivityTypes.ConversationUpdate)
    {
        // Run the Dialog with the Activity.
        await _mainDialog.RunAsync(turnContext, _conversationState.CreateProperty<DialogState>("DialogState"), cancellationToken);
    }
    else
    {
        // Let the base class handle the activity.
        await base.OnTurnAsync(turnContext, cancellationToken);
    }

    // Save any state changes that might have occurred during the turn.
    await _conversationState.SaveChangesAsync(turnContext, false, cancellationToken);
}

サービス登録

スキル ダイアログを使用するために必要なサービスは、一般的に、スキル コンシューマーに必要なサービスと同じです。 必要なサービスについては、スキル コンシューマーを実装する方法を参照してください。

ルート ボットのテスト

スキル コンシューマーは通常のボットと同様にエミュレーターでテストできますが、スキルとスキル コンシューマーの両方のボットを同時に実行する必要があります。 スキルを構成する方法については、スキル内でダイアログを使用する方法を参照してください。

最新の Bot Framework Emulator をダウンロードしてインストールします。

  1. ダイアログ スキル ボットとダイアログ ルート ボットを自分のコンピュータでローカルに実行します。 手順が必要な場合は、サンプルの README で C#、JavaScript、Java、Python の箇所を参照してください。
  2. エミュレーターを使用してボットをテストします。
    • 最初に会話に参加すると、ボットによってウェルカム メッセージが表示され、呼び出したいスキルをたずねられます。 このサンプルのスキル ボットには、スキルは 1 つしかありません。
    • [DialogSkillBot] を選択します。
  3. 次に、スキルのアクションを選択するようにボットから求められます。 [BookFlight] を選択します。
    1. プロンプトに答えます。
    2. スキルが完了すると、ルートボットが、予約の詳細を表示し、再び呼び出したいスキルを尋ねます。
  4. もう一度 [DialogSkillBot] を選択し、[BookFlight] を選択します。
    1. 最初のプロンプトに答え、「abort」と入力してスキルを中断します。
    2. ルート ボットでスキルがキャンセルされ、呼び出すスキルが要求されます。

デバッグの詳細

スキルとスキル コンシューマーの間のトラフィックは認証されるため、このようなボットをデバッグする際には追加の手順があります。

  • スキル コンシューマーおよびそれが使用するすべてのスキルが、直接または間接的に実行されている必要があります。
  • ボットがローカルで実行されており、いずれかのボットにアプリ ID とパスワードが設定されている場合は、すべてのボットに有効な ID とパスワードが必要です。
  • ボットがすべてデプロイ済みである場合は、devtunnel を使用して任意のチャネルからボットをデバッグする方法をご覧ください。
  • 一部のボットがローカルで実行されており、一部がデプロイ済みである場合は、スキルまたはスキル コンシューマーをデバッグする方法に関する記事をご覧ください。

それ以外の場合は、その他のボットをデバッグするのと同様に、スキル コンシューマーまたはスキルをデバッグできます。 詳細については、ボットのデバッグに関する記事、およびBot Framework Emulator を使用したデバッグに関する記事を参照してください。

追加情報

一般的なスキル コンシューマーの実装方法については、スキル コンシューマーを実装する方法を参照してください。

  • 最終更新: