활동 처리기를 사용하는 이벤트 기반 대화

적용 대상: SDK v4

활동 처리기는 봇에 대한 대화형 논리를 구성하는 이벤트 기반 방법입니다. 활동의 각 다른 형식 또는 하위 형식은 서로 다른 유형의 대화형 이벤트를 나타냅니다. 봇의 턴 처리기는 수신된 모든 유형의 활동에 대해 개별 활동 처리기를 호출합니다.

예를 들어 봇이 메시지 활동을 수신하는 경우 턴 처리기는 들어오는 활동을 확인하고 메시지 작업 처리기로 보냅니다. 봇을 빌드할 때 메시지 처리 및 응답에 대한 봇 논리는 메시지 활동 처리기에서 이 작업을 수행합니다. 마찬가지로, 대화에 추가되는 멤버를 처리하는 논리는 멤버가 대화에 추가될 때마다 호출되는 멤버 추가 처리기로 이동합니다.

봇 논리를 구성하는 다른 방법은 봇 작동 방식의 봇 논리 섹션을 참조하세요.

참고 항목

Bot Framework JavaScript, C#및 Python SDK는 계속 지원되지만 Java SDK는 2023년 11월에 종료되는 최종 장기 지원으로 사용 중지됩니다.

Java SDK를 사용하여 빌드된 기존 봇은 계속 작동합니다.

새 봇 빌드의 경우 Microsoft Copilot Studio를 사용하고 올바른 부조종사 솔루션 선택에 대해 알아봅니다.

자세한 내용은 봇 빌드의 미래를 참조 하세요.

C#

이러한 처리기에 대한 논리를 구현하려면 아래의 샘플 작업 처리기 섹션과 같이 봇에서 이러한 메서드를 재정의합니다. 이러한 각 처리기에는 기본 구현이 없으므로 재정의에 원하는 논리를 추가하기만 하면 됩니다.

순서가 끝날 때 상태를 저장하는 것과 같이 기본 턴 처리기를 재정의하려는 특정 상황이 있습니다. 이 경우에는 먼저 await base.OnTurnAsync(turnContext, cancellationToken);를 호출하여 OnTurnAsync의 기본 구현이 추가 코드 전에 실행되도록 하세요. 이러한 기본 구현은 무엇보다도 다음과 같은 OnMessageActivityAsync나머지 활동 처리기를 호출하는 역할을 합니다.

JavaScript

JavaScript ActivityHandler 는 이벤트 방출기 및 수신기 패턴을 사용합니다. 예를 들어 메서드를 onMessage 사용하여 메시지 활동에 대한 이벤트 수신기를 등록합니다. 둘 이상의 수신기를 등록할 수 있습니다. 봇이 메시지 활동을 받으면 활동 처리기는 들어오는 활동을 확인하고 각 활동 수신기를 등록된 순서대로 보냅니 onMessage 다.

봇을 빌드할 때 메시지 처리 및 응답에 대한 봇 논리가 수신기로 onMessage 이동합니다. 마찬가지로 대화에 추가되는 멤버를 처리하는 논리는 멤버가 대화에 onMembersAdded 추가될 때마다 호출되는 수신기로 이동합니다. 이러한 수신기를 추가하려면 아래 봇 논리 섹션에 표시된 대로 봇에 등록합니다. 각 수신기에 대해 봇 논리를 포함한 다음, 마지막에 호출 next() 해야 합니다. 호출 next()하여 다음 수신기가 실행되는지 확인합니다.

턴이 끝나기 전에 상태를 저장해야 합니다. 이렇게 하려면 작업 처리기 run 메서드를 재정의하고 부모의 run 메서드가 완료된 후 상태를 저장합니다.

기본 턴 처리기를 재정의하려는 일반적인 상황은 없으므로 그렇게 하려고 하면 주의해야 합니다. 라는 onDialog특수 처리기가 있습니다. onDialog 처리기는 나머지 처리기가 실행된 후 마지막에 실행되며 특정 활동 형식에 연결되지 않습니다. 위의 모든 처리기와 마찬가지로 나머지 프로세스가 래핑되도록 호출 next() 해야 합니다.

Java

이러한 처리기에 대한 논리를 구현하려면 아래의 샘플 작업 처리기 섹션과 같이 봇에서 이러한 메서드를 재정의합니다. 이러한 각 처리기에 대한 기본 구현이 없으므로 재정의에 원하는 논리를 추가합니다.

순서가 끝날 때 상태를 저장하는 것과 같이 기본 턴 처리기를 재정의하려는 특정 상황이 있습니다. 이렇게 할 때는 먼저 호출 super.onTurn(turnContext); 하여 추가 코드 전에 기본 구현 onTurn 이 실행되는지 확인해야 합니다. 이러한 기본 구현은 무엇보다도 다음과 같은 onMessageActivity나머지 활동 처리기를 호출하는 역할을 합니다.

Python

봇을 빌드할 때 메시지 처리 및 응답에 대한 봇 논리는 이 on_message_activity 처리기로 이동합니다. 마찬가지로 대화에 추가되는 멤버를 처리하는 논리는 처리기에서 on_members_added 진행되며, 이 처리기는 멤버가 대화에 추가될 때마다 호출됩니다.

예를 들어 봇이 메시지 활동을 수신하는 경우 턴 처리기는 들어오는 활동을 보고 이를 작업 처리기로 보냅니 on_message_activity 다.

이러한 처리기에 대한 논리를 구현하려면 아래의 샘플 작업 처리기 섹션과 같이 봇에서 이러한 메서드를 재정의합니다. 이러한 각 처리기에는 기본 구현이 없으므로 재정의에 원하는 논리를 추가하기만 하면 됩니다.

순서가 끝날 때 상태를 저장하는 것과 같이 기본 턴 처리기를 재정의하려는 특정 상황이 있습니다. 이 경우에는 먼저 await super().on_turn(turnContext);를 호출하여 on_turn의 기본 구현이 추가 코드 전에 실행되도록 하세요. 이러한 기본 구현은 무엇보다도 다음과 같은 on_message_activity나머지 활동 처리기를 호출하는 역할을 합니다.

활동 처리

봇 논리는 하나 이상의 채널에서 들어오는 활동을 처리하고 응답에서 나가는 활동을 생성합니다.

C#

기본 봇 논리는 봇 코드에 정의됩니다. 봇을 작업 처리기로 구현하려면 인터페이스를 구현하는 봇 클래스를 ActivityHandler파생합니다 IBot . ActivityHandler 는 다음과 같은 OnMessageActivityAsync다양한 유형의 활동에 대한 다양한 처리기를 정의합니다 OnMembersAddedAsync. 이러한 메서드는 보호되지만 파생되므로 재정의 ActivityHandler할 수 있습니다.

정의된 처리기는 다음과 같습니다.ActivityHandler

이벤트	처리기	설명
받은 모든 활동 유형	OnTurnAsync	수신된 작업의 유형에 따라 다른 처리기 중 하나를 호출합니다.
받은 메시지 활동	OnMessageActivityAsync	작업을 처리하도록 재정의 message 합니다.
받은 대화 업데이트 활동	OnConversationUpdateActivityAsync	활동에서 conversationUpdate 봇 이외의 멤버가 대화에 참가하거나 떠난 경우 처리기를 호출합니다.
비봇 멤버가 대화에 참가했습니다.	OnMembersAddedAsync	대화에 참가하는 멤버를 처리하도록 재정의합니다.
비봇 멤버가 대화를 떠났습니다.	OnMembersRemovedAsync	대화를 종료하는 멤버를 처리하도록 재정의합니다.
받은 이벤트 활동	OnEventActivityAsync	활동에서 event 이벤트 유형과 관련된 처리기를 호출합니다.
받은 토큰 응답 이벤트 활동	OnTokenResponseEventAsync	토큰 응답 이벤트를 처리하도록 재정의합니다.
토큰-응답 이외 이벤트 작업이 수신됨	OnEventAsync	다른 유형의 이벤트를 처리하도록 재정의합니다.
받은 메시지 반응 활동	OnMessageReactionActivityAsync	활동에서 messageReaction 메시지에서 하나 이상의 반응이 추가되거나 제거된 경우 처리기를 호출합니다.
메시지에 추가된 메시지 반응	OnReactionsAddedAsync	메시지에 추가된 반응을 처리하도록 이를 재정의합니다.
메시지에서 제거된 메시지 반응	OnReactionsRemovedAsync	메시지에서 제거된 반응을 처리하도록 재정의합니다.
수신된 설치 업데이트 작업	OnInstallationUpdateActivityAsync	활동에서 installationUpdate 봇이 설치 또는 제거되었는지 여부에 따라 처리기를 호출합니다.
봇 설치되어 있음	OnInstallationUpdateAddAsync	이를 재정의하여 봇이 조직 구성 단위 내에 설치된 경우에 대한 논리를 추가합니다.
봇 제거	OnInstallationUpdateRemoveAsync	이를 재정의하여 조직 구성 단위 내에서 봇을 제거할 때의 논리를 추가합니다.
수신된 기타 활동 유형	OnUnrecognizedActivityTypeAsync	달리 처리되지 않은 작업 유형을 처리하도록 재정의합니다.

이러한 처리기에는 turnContext 인바운드 HTTP 요청에 해당하는 들어오는 활동에 대한 정보를 제공하는 처리기가 있습니다. 다양한 작업 유형이 있을 수 있으므로 각 처리기는 순서 컨텍스트 매개 변수에 강력한 형식의 작업을 제공합니다. 대부분의 경우 OnMessageActivityAsync는 항상 처리되고, 일반적으로 가장 많이 사용됩니다.

이 프레임워크의 이전 4.x 버전과 마찬가지로 공용 메서드 OnTurnAsync를 구현하는 옵션도 있습니다. 현재 이 메서드의 기본 구현은 오류 검사를 처리한 다음 들어오는 작업의 유형에 따라 각 특정 처리기(예: 이 샘플에서 정의한 두 처리기)를 호출합니다. 대부분의 경우 해당 메서드를 그대로 두고 개별 처리기를 사용할 수 있지만 상황에 따라 사용자 지정 구현 OnTurnAsync이 필요한 경우 여전히 옵션입니다.

Important

메서드를 OnTurnAsync 재정의하는 경우 다른 On<activity>Async 모든 처리기를 호출하거나 해당 처리기를 직접 호출하는 기본 구현을 가져오기 위해 호출 base.OnTurnAsync 해야 합니다. 그렇지 않으면 해당 처리기가 호출되지 않으며 해당 코드가 실행되지 않습니다.

JavaScript

기본 봇 논리는 봇 코드에 정의됩니다. 봇을 작업 처리기로 구현하려면 을 확장 ActivityHandler합니다. ActivityHandler 는 다양한 유형의 활동에 대한 다양한 이벤트를 정의하며, 이벤트 수신기(예 onMessage onConversationUpdate: with 및 .)를 등록하여 봇의 동작을 수정할 수 있습니다.

다음 메서드를 사용하여 각 이벤트 유형에 대한 수신기를 등록합니다.

이벤트	등록 방법	설명
받은 모든 활동 유형	onTurn	활동을 수신할 때 수신기를 등록합니다.
받은 메시지 활동	onMessage	활동이 수신될 때 수신기를 message 등록합니다.
받은 대화 업데이트 활동	onConversationUpdate	활동을 conversationUpdate 수신할 때 수신기를 등록합니다.
멤버가 대화에 참가함	onMembersAdded	멤버가 봇을 포함하여 대화에 참가한 경우에 대한 수신기를 등록합니다.
멤버가 대화를 나감	onMembersRemoved	멤버가 봇을 포함하여 대화를 떠난 경우에 대한 수신기를 등록합니다.
받은 메시지 반응 활동	onMessageReaction	활동을 messageReaction 수신할 때 수신기를 등록합니다.
메시지에 추가된 메시지 반응	onReactionsAdded	메시지에 반응이 추가되는 경우에 대한 수신기를 등록합니다.
메시지에서 제거된 메시지 반응	onReactionsRemoved	반응이 메시지에서 제거될 때의 수신기를 등록합니다.
받은 이벤트 활동	onEvent	활동을 event 수신할 때 수신기를 등록합니다.
받은 토큰 응답 이벤트 활동	onTokenResponseEvent	tokens/response 이벤트가 수신될 때의 수신기를 등록합니다.
수신된 설치 업데이트 작업	onInstallationUpdate	활동을 installationUpdate 수신할 때 수신기를 등록합니다.
봇 설치되어 있음	onInstallationUpdateAdd	봇이 조직 구성 단위 내에 설치된 경우에 대한 수신기를 등록합니다.
봇 제거	onInstallationUpdateRemove	조직 구성 단위 내에서 봇을 제거할 때 수신기를 등록합니다.
수신된 기타 활동 유형	onUnrecognizedActivityType	특정 유형의 작업에 대한 처리기가 정의되지 않은 경우 수신기를 등록합니다.
작업 처리기가 완료되었습니다.	onDialog	적용 가능한 처리기가 완료된 후 호출됩니다.

next 처리를 계속할 수 있도록 각 처리기에서 연속 함수를 호출합니다. next 호출되지 않으면 작업 처리가 종료됩니다.

Java

기본 봇 논리는 봇 코드에 정의됩니다. 봇을 작업 처리기로 구현하려면 인터페이스를 구현하는 봇 클래스를 ActivityHandler파생합니다 Bot . ActivityHandler 는 다음과 같은 onMessageActivity다양한 유형의 활동에 대한 다양한 처리기를 정의합니다 onMembersAdded. 이러한 메서드는 보호되지만 파생되므로 재정의 ActivityHandler할 수 있습니다.

정의된 처리기는 다음과 같습니다.ActivityHandler

이벤트	처리기	설명
받은 모든 활동 유형	onTurn	수신된 작업의 유형에 따라 다른 처리기 중 하나를 호출합니다.
받은 메시지 활동	onMessageActivity	작업을 처리하도록 재정의 message 합니다.
받은 대화 업데이트 활동	onConversationUpdateActivity	활동에서 conversationUpdate 봇 이외의 멤버가 대화에 참가하거나 떠난 경우 처리기를 호출합니다.
비봇 멤버가 대화에 참가했습니다.	onMembersAdded	대화에 참가하는 멤버를 처리하도록 재정의합니다.
비봇 멤버가 대화를 떠났습니다.	onMembersRemoved	대화를 종료하는 멤버를 처리하도록 재정의합니다.
받은 이벤트 활동	onEventActivity	활동에서 event 이벤트 유형과 관련된 처리기를 호출합니다.
받은 토큰 응답 이벤트 활동	onTokenResponseEvent	토큰 응답 이벤트를 처리하도록 재정의합니다.
토큰-응답 이외 이벤트 작업이 수신됨	onEvent	다른 유형의 이벤트를 처리하도록 재정의합니다.
받은 메시지 반응 활동	onMessageReactionActivity	활동에서 messageReaction 메시지에서 하나 이상의 반응이 추가되거나 제거된 경우 처리기를 호출합니다.
메시지에 추가된 메시지 반응	onReactionsAdded	메시지에 추가된 반응을 처리하도록 이를 재정의합니다.
메시지에서 제거된 메시지 반응	onReactionsRemoved	메시지에서 제거된 반응을 처리하도록 재정의합니다.
수신된 설치 업데이트 작업	onInstallationUpdate	활동에서 installationUpdate 봇이 설치 또는 제거되었는지 여부에 따라 처리기를 호출합니다.
봇 설치되어 있음	onInstallationUpdateAdd	이를 재정의하여 봇이 조직 구성 단위 내에 설치된 경우에 대한 논리를 추가합니다.
봇 제거	onInstallationUpdateRemove	이를 재정의하여 조직 구성 단위 내에서 봇을 제거할 때의 논리를 추가합니다.
수신된 기타 활동 유형	onUnrecognizedActivityType	달리 처리되지 않은 작업 유형을 처리하도록 재정의합니다.

이러한 처리기에는 turnContext 인바운드 HTTP 요청에 해당하는 들어오는 활동에 대한 정보를 제공하는 처리기가 있습니다. 다양한 작업 유형이 있을 수 있으므로 각 처리기는 순서 컨텍스트 매개 변수에 강력한 형식의 작업을 제공합니다. 대부분의 경우 onMessageActivity는 항상 처리되고, 일반적으로 가장 많이 사용됩니다.

공용 메서드 onTurn를 구현하는 옵션도 있습니다. 현재 이 메서드의 기본 구현은 오류 검사를 처리한 다음 들어오는 작업의 유형에 따라 각 특정 처리기(예: 이 샘플에서 정의한 두 처리기)를 호출합니다. 대부분의 경우 해당 메서드를 그대로 두고 개별 처리기를 사용할 수 있지만 상황에 따라 사용자 지정 구현 onTurn이 필요한 경우 여전히 옵션입니다.

Important

메서드를 onTurn 재정의하는 경우 다른 on<activity> 모든 처리기를 호출하거나 해당 처리기를 직접 호출하는 기본 구현을 가져오기 위해 호출 super.onTurn 해야 합니다. 그렇지 않으면 해당 처리기가 호출되지 않으며 해당 코드가 실행되지 않습니다.

Python

기본 봇 논리는 봇 코드에 정의됩니다. 봇을 작업 처리기로 구현하려면 추상 Bot 클래스에서 ActivityHandler파생되는 봇 클래스를 파생합니다. ActivityHandler 는 다음과 같은 on_message_activity 다양한 유형의 활동에 대한 다양한 처리기를 정의합니다 on_members_added. 이러한 메서드는 보호되지만 파생되므로 재정의 ActivityHandler할 수 있습니다.

정의된 처리기는 다음과 같습니다.ActivityHandler

이벤트	처리기	설명
받은 모든 활동 유형	on_turn	수신된 작업의 유형에 따라 다른 처리기 중 하나를 호출합니다.
받은 메시지 활동	on_message_activity	작업을 처리하도록 재정의 message 합니다.
받은 대화 업데이트 활동	on_conversation_update_activity	활동에서 conversationUpdate 봇 이외의 멤버가 대화에 참가하거나 떠난 경우 처리기를 호출합니다.
비봇 멤버가 대화에 참가했습니다.	on_members_added_activity	대화에 참가하는 멤버를 처리하도록 재정의합니다.
비봇 멤버가 대화를 떠났습니다.	on_members_removed_activity	대화를 종료하는 멤버를 처리하도록 재정의합니다.
받은 이벤트 활동	on_event_activity	활동에서 event 이벤트 유형과 관련된 처리기를 호출합니다.
받은 토큰 응답 이벤트 활동	on_token_response_event	토큰 응답 이벤트를 처리하도록 재정의합니다.
토큰-응답 이외 이벤트 작업이 수신됨	on_event_activity	다른 유형의 이벤트를 처리하도록 재정의합니다.
받은 메시지 반응 활동	on_message_reaction_activity	활동에서 messageReaction 메시지에서 하나 이상의 반응이 추가되거나 제거된 경우 처리기를 호출합니다.
메시지에 추가된 메시지 반응	on_reactions_added	메시지에 추가된 반응을 처리하도록 이를 재정의합니다.
메시지에서 제거된 메시지 반응	on_reactions_removed	메시지에서 제거된 반응을 처리하도록 재정의합니다.
수신된 설치 업데이트 작업	on_installation_update	활동에서 installationUpdate 봇이 설치 또는 제거되었는지 여부에 따라 처리기를 호출합니다.
봇 설치되어 있음	on_installation_update_add	이를 재정의하여 봇이 조직 구성 단위 내에 설치된 경우에 대한 논리를 추가합니다.
봇 제거	on_installation_update_remove	이를 재정의하여 조직 구성 단위 내에서 봇을 제거할 때의 논리를 추가합니다.
수신된 기타 활동 유형	on_unrecognized_activity_type	달리 처리되지 않은 작업 유형을 처리하도록 재정의합니다.

이러한 처리기에는 turn_context 인바운드 HTTP 요청에 해당하는 들어오는 활동에 대한 정보를 제공하는 처리기가 있습니다. 다양한 작업 유형이 있을 수 있으므로 각 처리기는 순서 컨텍스트 매개 변수에 강력한 형식의 작업을 제공합니다. 대부분의 경우 on_message_activity는 항상 처리되고, 일반적으로 가장 많이 사용됩니다.

이 프레임워크의 이전 4.x 버전과 마찬가지로 공용 메서드 on_turn를 구현하는 옵션도 있습니다. 현재 이 메서드의 기본 구현은 오류 검사를 처리한 다음 들어오는 작업의 유형에 따라 각 특정 처리기(예: 이 샘플에서 정의한 두 처리기)를 호출합니다. 대부분의 경우 해당 메서드를 그대로 두고 개별 처리기를 사용할 수 있지만 상황에 따라 사용자 지정 구현 on_turn이 필요한 경우 여전히 옵션입니다.

Important

메서드를 on_turn 재정의하는 경우 다른 on_<activity> 모든 처리기를 호출하거나 해당 처리기를 직접 호출하는 기본 구현을 가져오기 위해 호출 super().on_turn 해야 합니다. 그렇지 않으면 해당 처리기가 호출되지 않으며 해당 코드가 실행되지 않습니다.

샘플 작업 처리기

예를 들어 대화에 사용자를 환영하기 위해 추가된 멤버를 처리하고 메시지를 처리하여 봇에 보내는 메시지를 에코할 수 있습니다.

C#

public class EchoBot : ActivityHandler
{
    protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
    {
        var replyText = $"Echo: {turnContext.Activity.Text}";
        await turnContext.SendActivityAsync(MessageFactory.Text(replyText, replyText), cancellationToken);
    }

    protected override async Task OnMembersAddedAsync(IList<ChannelAccount> membersAdded, ITurnContext<IConversationUpdateActivity> turnContext, CancellationToken cancellationToken)
    {
        var welcomeText = "Hello and welcome!";
        foreach (var member in membersAdded)
        {
            if (member.Id != turnContext.Activity.Recipient.Id)
            {
                await turnContext.SendActivityAsync(MessageFactory.Text(welcomeText, welcomeText), cancellationToken);
            }
        }
    }
}

JavaScript

class EchoBot extends ActivityHandler {
    constructor() {
        super();
        // See https://aka.ms/about-bot-activity-message to learn more about the message and other activity types.
        this.onMessage(async (context, next) => {
            const replyText = `Echo: ${ context.activity.text }`;
            await context.sendActivity(MessageFactory.text(replyText, replyText));
            // By calling next() you ensure that the next BotHandler is run.
            await next();
        });

        this.onMembersAdded(async (context, next) => {
            const membersAdded = context.activity.membersAdded;
            const welcomeText = 'Hello and welcome!';
            for (let cnt = 0; cnt < membersAdded.length; ++cnt) {
                if (membersAdded[cnt].id !== context.activity.recipient.id) {
                    await context.sendActivity(MessageFactory.text(welcomeText, welcomeText));
                }
            }
            // By calling next() you ensure that the next BotHandler is run.
            await next();
        });
    }
}

Java

public class EchoBot extends ActivityHandler {

    @Override
    protected CompletableFuture<Void> onMessageActivity(TurnContext turnContext) {
        return turnContext.sendActivity(
            MessageFactory.text("Echo: " + turnContext.getActivity().getText())
        ).thenApply(sendResult -> null);
    }

    @Override
    protected CompletableFuture<Void> onMembersAdded(
        List<ChannelAccount> membersAdded,
        TurnContext turnContext
    ) {
        String welcomeText = "Hello and welcome!";
        return membersAdded.stream()
            .filter(
                member -> !StringUtils
                    .equals(member.getId(), turnContext.getActivity().getRecipient().getId())
            ).map(channel -> turnContext.sendActivity(MessageFactory.text(welcomeText, welcomeText, null)))
            .collect(CompletableFutures.toFutureList()).thenApply(resourceResponses -> null);
    }
}

Python

class EchoBot(ActivityHandler):
    async def on_members_added_activity(
        self, members_added: [ChannelAccount], turn_context: TurnContext
    ):
        for member in members_added:
            if member.id != turn_context.activity.recipient.id:
                await turn_context.send_activity("Hello and welcome!")

    async def on_message_activity(self, turn_context: TurnContext):
        return await turn_context.send_activity(
            MessageFactory.text(f"Echo: {turn_context.activity.text}")
        )

다음 단계

• Microsoft Teams 채널에서는 Teams와 제대로 작동하기 위해 봇이 지원해야 하는 일부 Teams 관련 활동을 소개합니다. Microsoft Teams용 봇 개발의 주요 개념을 이해하려면 Microsoft Teams 봇의 작동 방식을 참조 하세요.
• 활동 처리기는 턴 간에 대화형 상태를 추적할 필요가 없는 봇을 디자인하는 좋은 방법입니다. 대화 상자 라이브러리는 사용자와 장기 실행 대화를 관리하는 방법을 제공합니다.