ダイアログの複雑さを管理する

適用対象: SDK v4

コンポーネント ダイアログを使用すると、大規模なダイアログ セットをより管理しやすい要素に分割して、特定のシナリオを処理する独立したダイアログを作成できます。 各要素には独自のダイアログ セットがあり、その要素外にあるダイアログ セットとの名前の競合を回避しています。 コンポーネント ダイアログは、次のことができるという点で再利用可能です。

• ボット内の別の ComponentDialog または DialogSet へ追加。
• パッケージの一部としてエクスポート。
• 他のボット内で使用。

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 を検討してください。

前提条件

• ボットの基本、ダイアログ ライブラリ、および会話を管理する方法に関する知識。
• マルチターン プロンプト サンプルのコピー (C#、JavaScript、JavaまたはPython)。

サンプルについて

マルチターン プロンプト サンプルでは、ウォーターフォール ダイアログ、いくつかのプロンプト、および コンポーネント ダイアログを使用して、ユーザーに一連の質問を行う対話を作成します。 コードはダイアログを使用して、これらの手順を順番に切り替えます。

手順	プロンプトの種類
移動手段をユーザーに聞きます	選択プロンプト
名前をユーザーに聞きます	テキスト プロンプト
年齢を指定するかどうかをユーザーに聞きます	確認プロンプト
「はい」と回答した場合は、年齢を聞きます。	数値プロンプト。数値を検証し、0 より大きく 150 未満の場合のみ受け入れます。
収集された情報が正しいかどうかを聞きます	確認プロンプトの再利用

最後に、回答が「はい」なら、収集された情報を表示します。それ以外の場合は、ユーザー情報が保持されないことをユーザーに通知します。

コンポーネントのロジックを実装する

マルチターン プロンプト サンプルでは、ウォーターフォール ダイアログ、いくつかのプロンプト、および コンポーネント ダイアログを使用して、ユーザーに一連の質問を行う対話を作成します。

コンポーネント ダイアログによって 1 つ以上のダイアログがカプセル化されます。 コンポーネント ダイアログには内部ダイアログ セットがあり、この内部ダイアログ セットに追加したダイアログとプロンプトは独自の ID を持っています。これらの ID は、コンポーネント ダイアログ内からのみ表示できます。

C#

ダイアログを使用するには、Microsoft.Bot.Builder.Dialogs NuGet パッケージをインストールします。

Dialogs\UserProfileDialog.cs

ここでは UserProfileDialog クラスは、ComponentDialog クラスから派生しています。

public class UserProfileDialog : ComponentDialog

コンストラクター内で、AddDialog メソッドによって、ダイアログとプロンプトがコンポーネント ダイアログに追加されます。 このメソッドで追加する最初のアイテムは、初期ダイアログとして設定されます。 InitialDialogIdプロパティを明示的に設定することで、初期ダイアログを変更できます。 コンポーネント ダイアログを開始すると、その initial dialog が開始されます。

public UserProfileDialog(UserState userState)
    : base(nameof(UserProfileDialog))
{
    _userProfileAccessor = userState.CreateProperty<UserProfile>("UserProfile");

    // This array defines how the Waterfall will execute.
    var waterfallSteps = new WaterfallStep[]
    {
        TransportStepAsync,
        NameStepAsync,
        NameConfirmStepAsync,
        AgeStepAsync,
        PictureStepAsync,
        SummaryStepAsync,
        ConfirmStepAsync,
    };

    // Add named dialogs to the DialogSet. These names are saved in the dialog state.
    AddDialog(new WaterfallDialog(nameof(WaterfallDialog), waterfallSteps));
    AddDialog(new TextPrompt(nameof(TextPrompt)));
    AddDialog(new NumberPrompt<int>(nameof(NumberPrompt<int>), AgePromptValidatorAsync));
    AddDialog(new ChoicePrompt(nameof(ChoicePrompt)));
    AddDialog(new ConfirmPrompt(nameof(ConfirmPrompt)));
    AddDialog(new AttachmentPrompt(nameof(AttachmentPrompt), PicturePromptValidatorAsync));

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

次のコードは、ウォーターフォール ダイアログの最初の手順を表します。

private static async Task<DialogTurnResult> NameStepAsync(WaterfallStepContext stepContext, CancellationToken cancellationToken)
{
    stepContext.Values["transport"] = ((FoundChoice)stepContext.Result).Value;

    return await stepContext.PromptAsync(nameof(TextPrompt), new PromptOptions { Prompt = MessageFactory.Text("Please enter your name.") }, cancellationToken);
}

ウォーターフォール ダイアログの実装の詳細については、連続して行われる会話フローを実装する方法をご覧ください。

JavaScript

ダイアログを使用するには、ご自身のプロジェクトで botbuilder-dialogs npm パッケージをインストールする必要があります。

dialogs/userProfileDialog.js

ここでは UserProfileDialog クラスによって ComponentDialog が拡張されます。

const WATERFALL_DIALOG = 'WATERFALL_DIALOG';

コンストラクター内で、AddDialog メソッドによって、ダイアログとプロンプトがコンポーネント ダイアログに追加されます。 このメソッドで追加する最初のアイテムは、初期ダイアログとして設定されます。 InitialDialogIdプロパティを明示的に設定することで、初期ダイアログを変更できます。 コンポーネント ダイアログを開始すると、その initial dialog が開始されます。

class UserProfileDialog extends ComponentDialog {
    constructor(userState) {
        super('userProfileDialog');

        this.userProfile = userState.createProperty(USER_PROFILE);

        this.addDialog(new TextPrompt(NAME_PROMPT));
        this.addDialog(new ChoicePrompt(CHOICE_PROMPT));
        this.addDialog(new ConfirmPrompt(CONFIRM_PROMPT));
        this.addDialog(new NumberPrompt(NUMBER_PROMPT, this.agePromptValidator));
        this.addDialog(new AttachmentPrompt(ATTACHMENT_PROMPT, this.picturePromptValidator));

        this.addDialog(new WaterfallDialog(WATERFALL_DIALOG, [
            this.transportStep.bind(this),
            this.nameStep.bind(this),
            this.nameConfirmStep.bind(this),
            this.ageStep.bind(this),
            this.pictureStep.bind(this),
            this.summaryStep.bind(this),
            this.confirmStep.bind(this)
        ]));

次のコードは、ウォーターフォール ダイアログの最初の手順を表します。

}

async transportStep(step) {
    // WaterfallStep always finishes with the end of the Waterfall or with another dialog; here it is a Prompt Dialog.
    // Running a prompt here means the next WaterfallStep will be run when the user's response is received.
    return await step.prompt(CHOICE_PROMPT, {
        prompt: 'Please enter your mode of transport.',
        choices: ChoiceFactory.toChoices(['Car', 'Bus', 'Bicycle'])

ウォーターフォール ダイアログの実装の詳細については、連続して行われる会話フローを実装する方法をご覧ください。

ジャワ

UserProfileDialog.java

ここでは UserProfileDialog クラスは、ComponentDialog クラスから派生しています。

public class UserProfileDialog extends ComponentDialog {

コンストラクター内で、addDialog メソッドによって、ダイアログとプロンプトがコンポーネント ダイアログに追加されます。 このメソッドで追加する最初のアイテムは、初期ダイアログとして設定されます。 setInitialDialogIdメソッドを呼び出し、初期ダイアログの名前を指定すれば、初期ダイアログを変更することができます。 コンポーネント ダイアログを開始すると、その initial dialog が開始されます。

public UserProfileDialog(UserState withUserState) {
    super("UserProfileDialog");

    userProfileAccessor = withUserState.createProperty("UserProfile");

    WaterfallStep[] waterfallSteps = {
        UserProfileDialog::transportStep,
        UserProfileDialog::nameStep,
        this::nameConfirmStep,
        this::ageStep,
        UserProfileDialog::pictureStep,
        this::confirmStep,
        this::summaryStep
    };

    // Add named dialogs to the DialogSet. These names are saved in the dialog state.
    addDialog(new WaterfallDialog("WaterfallDialog", Arrays.asList(waterfallSteps)));
    addDialog(new TextPrompt("TextPrompt"));
    addDialog(new NumberPrompt<Integer>("NumberPrompt", UserProfileDialog::agePromptValidator, Integer.class));
    addDialog(new ChoicePrompt("ChoicePrompt"));
    addDialog(new ConfirmPrompt("ConfirmPrompt"));
    addDialog(new AttachmentPrompt("AttachmentPrompt", UserProfileDialog::picturePromptValidator));

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

次のコードは、ウォーターフォール ダイアログの最初の手順を表します。

private static CompletableFuture<DialogTurnResult> nameStep(WaterfallStepContext stepContext) {
    stepContext.getValues().put("transport", ((FoundChoice) stepContext.getResult()).getValue());

    PromptOptions promptOptions = new PromptOptions();
    promptOptions.setPrompt(MessageFactory.text("Please enter your name."));
    return stepContext.prompt("TextPrompt", promptOptions);
}

ウォーターフォール ダイアログの実装の詳細については、連続して行われる会話フローを実装する方法をご覧ください。

Python

ダイアログを使用するには、ターミナルから と を実行して pip install botbuilder-dialogs および pip install botbuilder-ai PyPI パッケージをインストールします。

dialogs/user_profile_dialog.py

ここでは UserProfileDialog クラスによって ComponentDialog が拡張されます。

class UserProfileDialog(ComponentDialog):

コンストラクター内で、add_dialog メソッドによって、ダイアログとプロンプトがコンポーネント ダイアログに追加されます。 このメソッドで追加する最初のアイテムは、初期ダイアログとして設定されます。 initial_dialog_idプロパティを明示的に設定することで、初期ダイアログを変更できます。 コンポーネント ダイアログを開始すると、その initial dialog が開始されます。

class UserProfileDialog(ComponentDialog):
    def __init__(self, user_state: UserState):
        super(UserProfileDialog, self).__init__(UserProfileDialog.__name__)

        self.user_profile_accessor = user_state.create_property("UserProfile")

        self.add_dialog(
            WaterfallDialog(
                WaterfallDialog.__name__,
                [
                    self.transport_step,
                    self.name_step,
                    self.name_confirm_step,
                    self.age_step,
                    self.picture_step,
                    self.summary_step,
                    self.confirm_step,
                ],
            )
        )
        self.add_dialog(TextPrompt(TextPrompt.__name__))
        self.add_dialog(
            NumberPrompt(NumberPrompt.__name__, UserProfileDialog.age_prompt_validator)
        )
        self.add_dialog(ChoicePrompt(ChoicePrompt.__name__))
        self.add_dialog(ConfirmPrompt(ConfirmPrompt.__name__))
        self.add_dialog(
            AttachmentPrompt(
                AttachmentPrompt.__name__, UserProfileDialog.picture_prompt_validator
            )
        )

        self.initial_dialog_id = WaterfallDialog.__name__

次のコードは、ウォーターフォール ダイアログの最初の手順を表します。

async def transport_step(
    self, step_context: WaterfallStepContext
) -> DialogTurnResult:
    # WaterfallStep always finishes with the end of the Waterfall or with another dialog;
    # here it is a Prompt Dialog. Running a prompt here means the next WaterfallStep will
    # be run when the users response is received.
    return await step_context.prompt(
        ChoicePrompt.__name__,
        PromptOptions(
            prompt=MessageFactory.text("Please enter your mode of transport."),
            choices=[Choice("Car"), Choice("Bus"), Choice("Bicycle")],
        ),
    )

ウォーターフォール ダイアログの実装の詳細については、連続して行われる会話フローを実装する方法をご覧ください。

実行時、コンポーネント ダイアログに独自のダイアログ スタックが保持されます。 コンポーネント ダイアログが開始すると、以下が行われます。

• インスタンスが作成され、外部ダイアログ スタックに追加されます
• 内部ダイアログ スタックが作成され、その状態が追加されます
• 初期ダイアログが開始され、内部ダイアログ スタックに追加されます。

親コンテキストでは、コンポーネントがアクティブなダイアログとして表示されます。 しかし、コンポーネント内のコンテキストには、初期ダイアログがアクティブなダイアログに見えます。

ボットからダイアログを呼び出します

コンポーネント ダイアログを追加した外部ダイアログ セットでは、コンポーネント ダイアログの ID は、それを作成したときに使用したものです。 外部セットでは、コンポーネントは 1 つのダイアログのように見えます。これはプロンプトの動作と似ています。

コンポーネント ダイアログを使用するには、そのインスタンスをボットのダイアログ セットに追加します。

C#

Bots\DialogBot.cs

サンプルでは、これはボットの RunAsync メソッドから呼び出される OnMessageActivityAsync メソッドを使用して行います。

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    Logger.LogInformation("Running dialog with Message Activity.");

    // Run the Dialog with the new message Activity.
    await Dialog.RunAsync(turnContext, ConversationState.CreateProperty<DialogState>(nameof(DialogState)), cancellationToken);
}

JavaScript

dialogs/userProfileDialog.js

サンプルでは、run メソッドをユーザー プロファイル ダイアログに追加しました。

 * @param {*} accessor
 */
async run(turnContext, accessor) {
    const dialogSet = new DialogSet(accessor);
    dialogSet.add(this);

    const dialogContext = await dialogSet.createContext(turnContext);
    const results = await dialogContext.continueDialog();
    if (results.status === DialogTurnStatus.empty) {
        await dialogContext.beginDialog(this.id);

bots/dialogBot.js

run メソッドは、ボットの onMessage メソッドから呼び出されます。

this.conversationState = conversationState;
this.userState = userState;
this.dialog = dialog;
this.dialogState = this.conversationState.createProperty('DialogState');

this.onMessage(async (context, next) => {
    console.log('Running dialog with Message Activity.');

ジャワ

DialogBot.java

サンプルでは、これはボットの run メソッドから呼び出される onMessageActivity メソッドを使用して行います。

@Override
protected CompletableFuture<Void> onMessageActivity(
    TurnContext turnContext
) {
    LoggerFactory.getLogger(DialogBot.class).info("Running dialog with Message Activity.");

    // Run the Dialog with the new message Activity.
    return Dialog.run(dialog, turnContext, conversationState.createProperty("DialogState"));
}

Python

helpers/dialog_helper.py

サンプルでは、run_dialog メソッドをユーザー プロファイル ダイアログに追加しました。

class DialogHelper:
    @staticmethod
    async def run_dialog(
        dialog: Dialog, turn_context: TurnContext, accessor: StatePropertyAccessor
    ):
        dialog_set = DialogSet(accessor)
        dialog_set.add(dialog)

        dialog_context = await dialog_set.create_context(turn_context)
        results = await dialog_context.continue_dialog()
        if results.status == DialogTurnStatus.Empty:
            await dialog_context.begin_dialog(dialog.id)

ボットの run_dialog メソッドから呼び出される on_message_activity メソッド。

bots/dialog_bot.py

async def on_message_activity(self, turn_context: TurnContext):
    await DialogHelper.run_dialog(
        self.dialog,
        turn_context,
        self.conversation_state.create_property("DialogState"),
    )

ボットをテストする

1. Bot Framework Emulator をインストールします (まだインストールしていない場合)。
2. ご自身のマシンを使ってローカルでサンプルを実行します。
3. 以下に示すように、エミュレーターを起動し、お使いのボットに接続して、メッセージを送信します。

追加情報

コンポーネント ダイアログのキャンセルのしくみ

コンポーネント ダイアログのコンテキストから cancel all dialogs を呼び出すと、コンポーネント ダイアログによって、その内部スタックのすべてのダイアログがキャンセルされた後、終了します。そして外部スタックの次のダイアログに制御が戻ります。

外部コンテキストからすべてのダイアログをキャンセルするを呼び出すと、コンポーネントは、外部コンテキストの残りのダイアログとともにキャンセルされます。

次のステップ

分岐とループを行う複雑な会話を作成する方法について説明します。

ユーザーによる割り込みの処理