적용 대상: SDK v4
구성 요소 대화 상자를 사용하면 독립적인 대화 상자를 만들어 특정 시나리오를 처리할 수 있으며, 큰 대화 상자를 보다 관리하기 쉬운 조각으로 분할할 수 있습니다. 이러한 각 부분에는 고유한 대화 집합이 있으며 외부의 대화 집합과 이름 충돌을 방지합니다. 구성 요소 대화 상자는 다음과 같은 경우에 다시 사용할 수 있습니다.
- 귀하의 봇에 추가된
ComponentDialog
또는DialogSet
. - 패키지의 일부로 내보냅니다.
- 다른 봇 내에서 사용됩니다.
참고
선택한 AI 서비스, 오케스트레이션 및 지식으로 에이전트를 빌드하려면 Microsoft 365 에이전트 SDK를 사용하는 것이 좋습니다. 에이전트 SDK는 C#, JavaScript 또는 Python을 지원합니다. aka.ms/agents 에이전트 SDK에 대해 자세히 알아볼 수 있습니다. SaaS 기반 에이전트 플랫폼을 찾고 있는 경우 Microsoft Copilot Studio를 고려하세요. Bot Framework SDK를 사용하여 빌드된 기존 봇이 있는 경우 봇을 에이전트 SDK로 업데이트할 수 있습니다. Bot Framework SDK에서 에이전트 SDK로의 주요 변경 내용 및 업데이트를 검토할 수 있습니다. Bot Framework SDK에 대한 지원 티켓은 2025년 12월 31일부터 더 이상 서비스되지 않습니다.
필수 조건
- 봇 기본 사항, 대화 상자 라이브러리 및 대화 관리 방법에 대한 지식
- C#, JavaScript, Java 또는 Python의 다중 턴 프롬프트 샘플 복사본입니다.
샘플 정보
다중 턴 프롬프트 샘플에서는 폭포 대화 상자, 몇 가지 프롬프트 및 구성 요소 대화 상자를 사용하여 사용자에게 일련의 질문을 하는 상호 작용을 만듭니다. 코드는 대화 상자를 사용하여 다음 단계를 순환합니다.
단계 | 프롬프트 형식 |
---|---|
사용자에게 교통 모드를 요청합니다. | 선택 프롬프트 |
사용자에게 이름을 요청합니다. | 텍스트 프롬프트 |
사용자에게 나이를 제공할지 물어보세요. | 확인 프롬프트 |
'예'라고 대답하면 나이를 물어보세요. | 0보다 크고 150보다 작은 나이만 허용하는 유효성 검사를 포함한 숫자 프롬프트 |
수집된 정보가 "괜찮은지" 묻습니다. | 확인 프롬프트 다시 사용 |
마지막으로, '예'라고 대답하면 수집된 정보를 표시합니다. 그렇지 않으면 사용자에게 해당 정보가 유지되지 않는다고 알릴 수 있습니다.
구성 요소의 대화 상자 구현하기
다중 턴 프롬프트 샘플에서는 폭포 대화 상자, 몇 가지 프롬프트 및 구성 요소 대화 상자를 사용하여 사용자에게 일련의 질문을 하는 상호 작용을 만듭니다.
구성 요소 대화 상자는 하나 이상의 대화 상자를 캡슐화합니다. 구성 요소 대화 상자에는 내부 대화 집합이 있으며, 이 내부 대화 집합에 추가하는 대화 상자와 프롬프트에는 구성 요소 대화 상자 내에서만 볼 수 있는 고유한 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);
}
폭포 대화 구현에 대한 자세한 내용은 순차적 대화 흐름을 구현하는 방법을 참조하세요.
런타임에 구성 요소 대화 상자는 자체의 고유한 대화 상자 스택을 유지 관리합니다. 구성 요소 대화 상자가 시작되는 경우:
- 인스턴스가 만들어지고 외부 대화 상자 스택에 추가됩니다.
- 해당 상태에 추가하는 내부 대화 상자 스택을 만듭니다.
- 초기 대화 상자를 시작하고 내부 대화 스택에 추가합니다.
부모 컨텍스트는 구성 요소를 활성 대화 상자로 봅니다. 그러나 구성 요소 내의 컨텍스트에서는 초기 대화 상자가 활성 대화 상자인 것처럼 보입니다.
봇에서 대화 상자 호출
구성 요소 대화 상자를 추가한 외부 대화 상자 집합에서는 구성 요소 대화 상자에 여러분이 만든 ID가 포함되어 있습니다. 외부 집합에서 구성 요소는 프롬프트처럼 단일 대화 상자처럼 보입니다.
구성 요소 대화 상자를 사용하려면 봇의 대화 상자 집합에 해당 인스턴스를 추가합니다.
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);
}
봇 테스트
- 아직 설치하지 않은 경우 Bot Framework Emulator를 설치합니다.
- 머신에서 로컬로 샘플을 실행합니다.
- 에뮬레이터를 시작하고 봇에 연결한 다음, 아래와 같은 메시지를 보냅니다.
추가 정보
구성 요소 대화 상자에서 취소가 작동하는 방식
구성 요소 대화 상자의 컨텍스트에서 모든 대화 취소를 호출하는 경우 구성 요소 대화 상자는 내부 스택의 모든 대화 상자를 취소한 다음 종료되어 외부 스택의 다음 대화 상자로 제어를 반환합니다.
외부 컨텍스트에서 모든 대화 취소를 호출하면 외부 컨텍스트의 나머지 대화 상자와 함께 구성 요소가 취소됩니다.
다음 단계
분기되고 반복되는 복잡한 대화를 만드는 방법에 대해 알아봅니다.