管理对话复杂性

适用于：SDK v4

可以通过组件对话创建独立的对话来处理特定的方案，将大型对话集分解成更易于管理的片段。其中的每个片段有自身的对话集，可避免与其外的对话集发生名称冲突。组件对话可重复使用，因为它们可以：

已添加到您的机器人中的另一个 ComponentDialog 或 DialogSet。
作为软件包的一部分导出。
在其他机器人中使用。

重要

Bot Framework SDK 和 Bot Framework Emulator 已在 GitHub 上存档。项目不再更新或维护。自 2025 年 12 月 31 日起，Bot Framework SDK 的支持票证将不再提供服务。

若要使用所选的 AI 服务、业务流程和知识生成代理，请考虑使用 Microsoft 365 代理 SDK。代理 SDK 对 C#、JavaScript 或 Python 具有语言支持。可以在 aka.ms/agents 了解有关代理 SDK 的详细信息。如果现有的机器人是使用 Bot Framework SDK 生成的，则可以将机器人更新到代理 SDK。查看 Bot Framework SDK 到代理 SDK 迁移指南的核心更改和更新。

如果要构建设计为在 Microsoft Teams 中工作的协作代理，请考虑使用 Teams SDK。它为在 Teams 环境中运行的代理提供 Teams 特定的 API、自适应卡支持和内置 AI 协同调度功能。可以在 Teams SDK（Teams AI 库）中了解详细信息。

如果要查找基于 SaaS 的代理平台，请考虑 Microsoft Copilot Studio。

先决条件

了解机器人基础知识、对话库、以及如何管理聊天。
以 C#、JavaScript、Java 或 Python 编写的“多轮次提示”示例的副本。

关于本示例

在多轮次提示示例中，我们将使用一个瀑布对话、几个提示和一个组件对话来创建交互，向用户提出一系列问题。代码使用对话来循环执行以下步骤：

步骤	提示类型
请求用户提供其交通方式	选择提示
请求用户输入其姓名	文本提示
询问用户是否愿意提供其年龄	确认提示
如果他们回答“是”，则请求他们提供年龄	带有验证的数字提示，仅接受大于 0 且小于 150 的年龄输入。
询问收集的信息是否“正确”	重复使用确认提示

最后，如果用户回答“是”，则显示收集的信息；否则，告知用户他们的信息不会保留。

实现你的组件对话框

在多轮次提示示例中，我们将使用一个瀑布对话、几个提示和一个组件对话来创建交互，向用户提出一系列问题。

组件对话可封装一个或多个对话。组件对话有一个内部对话集，而添加到此内部对话集的对话和提示有其自己的 ID，这些 ID 只能在组件对话内部查看。

若要使用对话，请安装 Microsoft.Bot.Builder.Dialogs NuGet 包。

Dialogs\UserProfileDialog.cs

在这里，UserProfileDialog 类派生自 ComponentDialog 类。

public class UserProfileDialog : ComponentDialog

在构造函数中，AddDialog 方法会将对话和提示添加到组件对话。使用此方法添加的第一项设置为初始对话。可以通过显式设置 InitialDialogId 属性来更改初始对话。启动组件对话框时，它会启动其 初始对话框。

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

若要详细了解如何实现瀑布对话，请参阅如何实现顺序聊天流。

若要使用对话，项目需要安装 botbuilder-dialogs npm 包。

dialogs/userProfileDialog.js

在这里，UserProfileDialog 类扩展了 ComponentDialog。

const WATERFALL_DIALOG = 'WATERFALL_DIALOG';

在构造函数中，AddDialog 方法会将对话和提示添加到组件对话。使用此方法添加的第一项设置为初始对话。可以通过显式设置 InitialDialogId 属性来更改初始对话。启动组件对话框时，将会启动其 初始对话框。


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 方法来更改初始对话，并提供初始对话的名称。启动组件对话框时，它将启动其 初始对话框。

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

若要详细了解如何实现瀑布对话，请参阅如何实现顺序聊天流。

若要使用对话功能，请在终端中运行 pip install botbuilder-dialogs 和 pip install botbuilder-ai，安装 botbuilder-dialogs 和 botbuilder-ai PyPI 包。

dialogs/user_profile_dialog.py

在这里，UserProfileDialog 类扩展了 ComponentDialog。

class UserProfileDialog(ComponentDialog):

在构造函数中，add_dialog 方法会将对话和提示添加到组件对话。使用此方法添加的第一项设置为初始对话。可以通过显式设置 initial_dialog_id 属性来更改初始对话。当你启动组件对话框时，它会启动其 初始对话框。

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。在外层集合中，该组件看起来像一个单独的对话框，就像提示框一样。

若要使用组件对话，请将该组件对话的实例添加到机器人的对话集中。

Bots\DialogBot.cs

在该示例中，这是通过从机器人的 OnMessageActivityAsync 方法中调用的 RunAsync 方法完成的。

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

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

在该示例中，这是通过从机器人的 onMessageActivity 方法中调用的 run 方法实现的。

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

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"),
    )

测试你的机器人

安装 Bot Framework Emulator（如果尚未安装）。
在计算机本地运行示例。
按如下所示启动 Emulator，连接到机器人，然后发送消息。

多轮提示词对话的示例文本记录。

其他信息

组件对话框的取消机制如何工作

如果从组件对话的上下文调用“取消所有对话”，组件对话会取消其内部堆栈上的所有对话，然后结束，将控制返回给外部堆栈上的下一对话。

如果从外部上下文调用“取消所有对话”，则会取消该组件以及外部上下文中的其余对话。

后续步骤

了解如何创建支持分支和循环的复杂对话。

处理用户中断

Last updated on 2026-06-24

管理对话复杂性

先决条件

关于本示例

实现你的组件对话框

从你的机器人中调用对话框

测试你的机器人

其他信息

组件对话框的取消机制如何工作

后续步骤

其他资源