Microsoft Bot Framework의 기본 사항
적용 대상: SDK v4
봇은 사용자가 텍스트, 그래픽(예: 카드 또는 이미지) 또는 음성을 사용하여 대화형 방식으로 상호 작용하는 앱입니다. Azure AI Bot Service는 클라우드 플랫폼입니다. 봇을 호스트하고 Microsoft Teams, Facebook 또는 Slack과 같은 채널에서 사용할 수 있도록 합니다.
Azure AI Bot Service의 구성 요소인 Bot Framework Service는 사용자의 봇 연결 앱과 봇 간에 정보를 보냅니다. 각 채널은 보내는 활동에 추가 정보를 포함할 수 있습니다. 봇을 만들기 전에 봇이 활동 개체를 사용하여 사용자와 통신하는 방법을 이해하는 것이 중요합니다.
이 다이어그램에서는 사용자가 에코 봇과 통신할 때 교환될 수 있는 두 가지 활동 유형 인 대화 업데이트 및 메시지를 보여 줍니다.
Bot Framework Service는 파티가 대화에 참가할 때 대화 업데이트를 보냅니다. 예를 들어 Bot Framework Emulator와의 대화를 시작할 때 두 개의 대화 업데이트 작업(대화에 참가하는 사용자와 봇 조인에 대한 작업)이 표시될 수 있습니다. 이러한 대화 업데이트 활동을 구분하려면 활동의 추가된 멤버 속성에 누가 포함되어 있는지 확인합니다.
메시지 활동은 당사자 간의 대화 정보를 전달합니다. 에코 봇 예에서는 메시지 활동이 간단한 텍스트를 전달하고 채널이 이 텍스트를 렌더링합니다. 또는 메시지 활동에는 말할 텍스트, 제안된 작업 또는 표시할 카드가 포함될 수 있습니다.
팁
Bot Framework 프로토콜을 구현하는 것은 각 채널에 달려 있으며, 각 채널의 구현 방식은 약간 다를 수 있습니다. 예를 들어 일부 채널은 먼저 대화 업데이트 활동을 보내고, 일부는 첫 번째 메시지 활동을 보낸 후 대화 업데이트 활동을 보냅니다. 채널에는 한 대화 업데이트 작업에 봇과 사용자가 모두 포함될 수 있고 다른 채널은 두 개의 대화 업데이트 활동을 보낼 수 있습니다.
이 예제에서 봇은 받은 인바운드 메시지 활동에 대한 응답으로 메시지 활동을 만들고 보냈습니다. 그러나 봇은 수신된 메시지 활동에 다른 방법으로 응답할 수 있으며, 봇은 환영 메시지와 함께 메시지 활동을 보내 대화 업데이트 활동에 응답하는 것이 일반적입니다. 자세한 내용은 사용자를 환영하는 방법을 참조하세요.
The Bot Framework SDK
Bot Framework SDK를 사용하면 Azure AI Bot Service에서 호스트할 수 있는 봇을 빌드할 수 있습니다. 이 서비스는 봇과 채널 또는 사용자가 상호 작용하는 방법에 대한 REST API 및 활동 프로토콜을 정의합니다. SDK는 이 REST API를 기반으로 하며 대화 논리에 집중할 수 있도록 서비스의 추상화를 제공합니다. SDK를 사용하기 위해 REST 서비스를 이해할 필요는 없지만 일부 기능을 이해하는 것이 도움이 될 수 있습니다.
봇은 대화형 인터페이스가 있는 앱입니다. 직접적인 사용자의 개입을 더 이상 요구할 수 없는 자동화된 시스템으로 저녁 식사를 예약하거나 프로필 정보를 수집하는 등 간단한 반복 작업을 이동할 수 없습니다. 사용자는 텍스트, 대화형 카드 및 음성을 사용하여 봇과 대화합니다. 빠른 질문 및 대답이거나 지능적으로 서비스에 대한 액세스를 제공하는 복잡한 대화를 통해 봇과 상호 작용할 수 있습니다.
참고 항목
SDK 및 REST API에서 제공하는 기능에 대한 지원은 채널에 따라 다릅니다. Bot Framework Emulator를 사용하여 봇을 테스트할 수 있지만 봇을 사용할 수 있도록 하려는 각 채널에서 봇의 모든 기능을 테스트해야 합니다.
상호 작용에는 차례로 처리되는 활동 교환이 포함됩니다.
활동
사용자(또는 채널)와 봇 간의 모든 상호 작용은 활동으로 표시됩니다. Bot Framework 활동 스키마 는 사용자 또는 채널과 봇 간에 교환할 수 있는 활동을 정의합니다. 활동은 사용자 텍스트 또는 음성, 앱-앱 알림, 다른 메시지에 대한 반응 등을 나타낼 수 있습니다.
회전(turns)
대화에서 사람들은 한 번에 한 명씩 순서대로 말을 합니다. 봇은 일반적으로 사용자 입력에 반응합니다. Bot Framework SDK 내에서 턴 은 봇에 들어오는 사용자의 활동과 봇이 즉각적인 응답으로 사용자에게 다시 보내는 활동으로 구성됩니다. 턴을 지정된 활동을 수신하는 봇과 연결된 처리라고 생각할 수 있습니다.
예를 들어 사용자는 봇에 특정 작업을 수행하도록 요청할 수 있습니다. 봇은 이 턴이 끝나는 시점에 작업에 대한 자세한 정보를 얻기 위해 질문으로 응답할 수 있습니다. 다음 턴에서 봇은 사용자로부터 봇의 질문에 대한 답변을 포함할 수 있는 새 메시지를 받거나, 제목 변경 또는 작업을 수행하기 위한 초기 요청을 무시하라는 요청을 나타낼 수 있습니다.
봇 애플리케이션 구조
SDK는 봇 앱에 대한 대화형 추론을 처리하는 봇 클래스를 정의합니다. 봇 클래스:
- 사용자의 입력을 인식하고 해석합니다.
- 입력에 대한 이유 및 관련 작업을 수행합니다.
- 봇이 수행하거나 수행한 일에 대한 응답을 생성합니다.
또한 SDK는 채널과의 연결을 처리하는 어댑터 클래스를 정의합니다. 어댑터:
- 사용자 채널에 대한 요청을 생성하기 위한 메서드 및 요청 처리를 위한 메서드를 제공합니다.
- 봇의 턴 처리기 외부의 턴 처리를 포함하는 미들웨어 파이프라인을 포함합니다.
- 봇의 턴 처리기를 호출하고 그렇지 않으면 턴 처리기에서 처리되지 않은 오류를 catch합니다.
또한 봇은 종종 각 턴마다 상태를 검색하고 저장해야 합니다. 상태는 스토리지, 봇 상태 및 속성 접근자 클래스를 통해 처리됩니다. SDK는 기본 제공 스토리지를 제공하지 않지만 스토리지에 대한 추상화 및 스토리지 계층의 몇 가지 구현을 제공합니다. 상태 관리 항목에서는 이러한 상태 및 스토리지 기능에 대해 설명합니다.
SDK는 특정 애플리케이션 계층을 사용하여 웹 요청을 보내고 받을 필요가 없습니다. Bot Framework에는 ASP.NET(C#), restify(JavaScript) 및 aiohttp(Python)에 대한 템플릿과 샘플이 있습니다. 그러나 앱에 다른 애플리케이션 계층을 사용하도록 선택할 수 있습니다.
SDK를 사용하여 봇을 만들 때 HTTP 트래픽을 수신하고 어댑터로 전달하는 코드를 제공합니다. Bot Framework는 사용자 고유의 봇을 개발하는 데 사용할 수 있는 몇 가지 템플릿과 샘플을 제공합니다.
참고 항목
Bot Framework JavaScript, C#및 Python SDK는 계속 지원되지만 Java SDK는 2023년 11월에 종료되는 최종 장기 지원으로 사용 중지됩니다.
Java SDK를 사용하여 빌드된 기존 봇은 계속 작동합니다.
새 봇 빌드의 경우 Microsoft Copilot Studio를 사용하고 올바른 부조종사 솔루션 선택에 대해 알아봅니다.
자세한 내용은 봇 빌드의 미래를 참조 하세요.
봇 논리
봇 개체는 턴에 대한 대화형 추론 또는 논리를 포함하고 봇 어댑터에서 들어오는 활동을 허용할 수 있는 메서드인 턴 처리기를 노출합니다.
SDK는 봇 논리를 관리하기 위한 몇 가지 다른 패러다임을 제공합니다.
- 활동 처리기는 들어오는 활동 유형 및 하위 형식이 이벤트인 이벤트 기반 모델을 제공합니다. 사용자와의 짧은 상호 작용이 제한적인 봇에 대한 활동 처리기를 고려합니다.
- 작업 처리기를 사용하고 봇이 인식하고 반응할 각 활동 유형 또는 하위 유형에 대한 처리기를 구현합니다.
- Teams 활동 처리기를 사용하여 Teams 채널에 연결할 수 있는 봇을 만듭니다. (Teams 채널을 사용하려면 봇이 채널별 동작을 처리해야 합니다.)
- 대화 상자 라이브러리는 사용자와의 장기 실행 대화를 관리하는 상태 기반 모델을 제공합니다.
- 주로 순차적인 대화에는 활동 처리기 및 구성 요소 대화 상자를 사용합니다. 자세한 내용은 구성 요소 및 폭포 대화 상자를 참조 하세요.
- 고유한 봇 클래스를 구현하고 각 턴을 처리하기 위한 고유한 논리를 제공합니다. 예를 들어 사용자 입력을 수집하기 위해 사용자 고유의 프롬프트를 만드는 방법을 참조하세요.
봇 어댑터
어댑터에는 턴을 시작하기 위한 프로세스 작업 메서드가 있습니다.
- 요청 본문(작업으로 변환된 요청 페이로드) 및 요청 헤더를 인수로 사용합니다.
- 인증 헤더가 유효한지 여부를 확인합니다.
- 턴에 대한 컨텍스트 개체를 만듭니다. 컨텍스트 개체에는 활동에 대한 정보가 포함됩니다.
- 미들웨어 파이프라인을 통해 컨텍스트 개체를 보냅니다.
- 그런 다음 컨텍스트 개체를 봇 개체의 턴 처리기로 보냅니다.
어댑터도 다음과 같습니다.
- 응답 활동의 형식을 지정하고 보냅니다. 이러한 응답은 일반적으로 사용자를 위한 메시지이지만 사용자의 채널에서 직접 사용할 정보를 포함할 수도 있습니다.
- 메시지 업데이트 및 삭제 메시지와 같은 Bot Connector REST API에서 제공하는 다른 메서드를 표시합니다.
- 그렇지 않으면 턴에 대해 catch되지 않은 오류 또는 예외를 catch합니다.
턴 컨텍스트
턴 컨텍스트 개체는 발신자 및 수신자, 채널 및 활동을 처리하는 데 필요한 기타 데이터와 같은 활동에 대한 정보를 제공합니다. 또한 봇의 다양한 계층에서 턴 중에 정보를 더할 수 있습니다.
턴 컨텍스트는 SDK에서 가장 중요한 추상화 중 하나입니다. 모든 미들웨어 구성 요소 및 애플리케이션 논리에 인바운드 작업을 전달할 뿐만 아니라 미들웨어 구성 요소와 봇 논리가 아웃바운드 활동을 보낼 수 있는 메커니즘도 제공합니다.
미들웨어
미들웨어는 다른 메시징 미들웨어와 유사하게 순서대로 각각 실행되는 선형 구성 요소 집합을 구성하고 각 작업에서 작동할 수 있는 기회를 제공합니다. 미들웨어 파이프라인의 마지막 단계는 애플리케이션이 어댑터의 프로세스 작업 메서드에 등록한 봇 클래스의 턴 처리기에 대한 콜백입니다. 미들웨어는 어댑터가 호출하는 켜기 메서드를 구현합니다.
턴 처리기는 턴 컨텍스트를 인수로 사용합니다. 일반적으로 턴 처리기 함수 내에서 실행되는 애플리케이션 논리는 인바운드 작업의 콘텐츠를 처리하고 응답에서 하나 이상의 활동을 생성하여 턴 컨텍스트에서 활동 보내기 함수를 사용하여 이러한 아웃바운드 활동을 보냅니다. 턴 컨텍스트에서 보내기 작업을 호출하면 미들웨어 구성 요소가 아웃바운드 활동에서 호출됩니다. 미들웨어 구성 요소는 봇의 턴 처리기 함수 전후에 실행됩니다. 실행은 본질적으로 중첩되어 있으며, 따라서 양파와 같다고도 합니다.
미들웨어 항목에서는 미들웨어에 대해 더 자세히 설명합니다.
봇 상태 및 스토리지
다른 웹앱과 마찬가지로 봇은 기본적으로 상태 비지정입니다. 봇 내의 상태는 최신 웹 애플리케이션과 동일한 패러다임을 따르며 Bot Framework SDK는 상태 관리를 더 쉽게 수행할 수 있도록 스토리지 계층 및 상태 관리 추상화 기능을 제공합니다.
상태 관리 항목에서는 이러한 상태 및 스토리지 기능에 대해 설명합니다.
메시징 엔드포인트 및 프로비전
일반적으로 애플리케이션에는 메시지를 받을 REST 엔드포인트가 필요합니다. 또한 사용하기로 결정한 플랫폼에 따라 봇에 대한 리소스를 프로비전해야 합니다.
봇 만들기 빠른 시작에 따라 간단한 에코 봇을 만들고 테스트합니다.
HTTP 세부 정보
활동은 HTTP POST 요청을 통해 Bot Framework 서비스에서 봇에 도착합니다. 봇은 200 HTTP 상태 코드를 사용하여 인바운드 POST 요청에 응답합니다. 봇에서 채널로 전송되는 활동은 별도의 HTTP POST에서 Bot Framework Service로 전송됩니다. 이는 다시 말해 200 HTTP 상태 코드로 승인이 요청됩니다.
프로토콜은 이러한 POST 요청 및 해당 승인이 이루어지는 순서를 지정하지 않습니다. 그러나 일반적인 HTTP 서비스 프레임워크에 맞게 일반적으로 이러한 요청은 중첩됩니다. 즉, 아웃바운드 HTTP 요청은 인바운드 HTTP 요청 범위 내의 봇에서 수행됩니다. 이 패턴은 이전 다이어그램에 설명되어 있습니다. 두 개의 서로 다른 HTTP 연결이 다시 있기 때문에 보안 모델은 둘 다에 대해 제공해야 합니다.
참고 항목
봇은 대부분의 채널에서 상태 200으로 통화를 승인하는 데 15초가 걸립니다. 봇이 15초 이내에 응답하지 않으면 HTTP GatewayTimeout 오류(504)가 발생합니다.
활동 처리 스택
메시지 작업의 도착에 중점을 두고 이전 시퀀스 다이어그램을 자세히 살펴보겠습니다.
채널은 사용자의 메시지를 Azure AI Bot Service로 보내고, 서비스는 메시지를 봇의 메시징 엔드포인트로 전달합니다. 봇의 응답은 턴 범위 내에서 사용자에게 전송됩니다.
위의 예제에서 봇은 동일한 문자 메시지를 포함하는 다른 메시지 활동으로 메시지 활동에 회신했습니다. 처리는 HTTP POST 요청으로 시작되며, 활동 정보는 JSON 페이로드로 전달되어 웹 서버에 도착합니다. 종종 ASP.NET 프로젝트는 C# 봇에 사용되며, Express 또는 restify와 같은 인기 있는 프레임워크는 JavaScript Node.js 봇에 사용됩니다.
SDK의 통합 구성 요소인 어댑터는 SDK 런타임의 핵심입니다. 활동은 HTTP POST 본문에서 JSON으로 전달됩니다. 이 JSON은 역직렬화되어 해당 프로세스 작업 메서드를 통해 어댑터에 전달되는 활동 개체를 만듭니다. 어댑터가 작업을 수신하면 순서 컨텍스트를 만들고 미들웨어를 호출합니다.
위에서 설명한 것처럼 턴 컨텍스트는 봇이 아웃바운드 활동을 보낼 수 있는 메커니즘을 제공하며, 대부분 인바운드 활동에 대한 응답으로 제공됩니다. 턴 컨텍스트는 활동 응답 메서드 보내기, 업데이트 및 삭제를 제공합니다. 각 응답 메서드는 비동기 프로세스에서 실행됩니다.
Important
기본 봇 턴을 처리하는 스레드는 컨텍스트 개체가 완료되면 삭제하는 작업을 처리합니다. 기본 스레드가 턴 컨텍스트의 처리 및 삭제를 완료하기 전에 생성된 작업을 대기하도록 모든 작업 호출을 수행해야 await 합니다. 그렇지 않은 경우 응답(처리기 포함)에 상당한 시간이 걸리고 컨텍스트 개체에 대해 작업을 시도하면 컨텍스트 삭제 오류가 발생할 수 있습니다.
봇 템플릿
앱에 대한 애플리케이션 계층 사용을 선택해야 합니다. 그러나 Bot Framework에는 ASP.NET(C#), restify(JavaScript) 및 aiohttp(Python)에 대한 템플릿과 샘플이 있습니다. 설명서는 이러한 플랫폼 중 하나를 사용하지만 SDK에서 필요하지 않다고 가정하여 작성되었습니다. 템플릿에 액세스하고 설치하는 방법에 대한 지침은 봇 만들기 빠른 시작을 참조하세요.
봇은 웹 애플리케이션이며 SDK의 각 언어 버전에 대해 템플릿이 제공됩니다. 모든 템플릿은 기본 엔드포인트 구현 및 어댑터를 제공합니다. 각 템플릿에는 다음이 포함됩니다.
- 리소스 프로비저닝
- 들어오는 활동을 어댑터로 라우팅하는 언어별 HTTP 엔드포인트 구현입니다.
- 어댑터 개체
- 봇 개체
다양한 템플릿 형식 간의 주요 차이점은 봇 개체에 있습니다. 템플릿은 다음과 같습니다.
- 빈 봇
- 대화의 첫 번째 턴에 "hello world" 메시지를 보내 사용자를 대화에 환영하는 활동 처리기를 포함합니다.
- 에코 봇
- 활동 처리기를 사용하여 사용자를 환영하고 사용자 입력을 에코합니다.
- 핵심 봇
- SDK의 여러 기능을 통합하고 봇에 대한 모범 사례를 보여 줍니다.
- 활동 처리기를 사용하여 사용자를 환영합니다.
- 구성 요소 대화 상자와 자식 대화 상자를 사용하여 대화를 관리합니다.
- 대화 상자는 LUIS(Language Understanding) 및 QnA Maker 기능을 사용합니다.
참고 항목
Azure AI QnA Maker는 2025년 3월 31일에 사용 중지됩니다. 2022년 10월 1일부터 새로운 QnA Maker 리소스 또는 참조 자료를 만들 수 없습니다. 이제 최신 버전의 질문 및 답변 기능이 Azure AI 언어의 일부로 사용할 수 있습니다.
Azure AI Language의 기능인 사용자 지정 질문 답변은 QnA Maker 서비스의 업데이트된 버전입니다. Bot Framework SDK의 질문 및 답변 지원에 대한 자세한 내용은 자연어 이해를 참조하세요.
참고 항목
LUIS(Language Understanding)는 2025년 10월 1일에 사용 중지됩니다. 2023년 4월 1일부터 새 LUIS 리소스를 만들 수 없습니다. 이제 최신 버전의 언어 이해가 Azure AI Language의 일부로 제공됩니다.
Azure AI Language의 기능인 CLU(대화형 언어 이해)는 업데이트된 LUIS 버전입니다. Bot Framework SDK의 언어 이해 지원에 대한 자세한 내용은 자연어 이해를 참조하세요.
추가 정보
봇 리소스 관리
앱 ID 및 암호와 같은 봇의 리소스와 연결된 서비스에 대한 정보도 관리해야 합니다. 봇을 배포할 때 이 정보에 대한 보안 액세스가 필요합니다. 복잡성을 방지하기 위해 대부분의 Bot Framework SDK 문서에서는 이 정보를 관리하는 방법을 설명하지 않습니다.
채널 어댑터
또한 SDK를 사용하면 채널 어댑터를 사용할 수 있습니다. 이 어댑터 자체는 또한 Bot Connector Service가 채널에 대해 정상적으로 수행하는 작업을 추가로 수행합니다.
SDK는 일부 언어로 몇 가지 채널 어댑터를 제공합니다. Botkit 및 커뮤니티 리포지토리를 통해 더 많은 채널 어댑터를 사용할 수 있습니다. 자세한 내용은 Bot Framework SDK 리포지토리의 채널 및 어댑터 테이블을 참조하세요.
The Bot Connector REST API
Bot Framework SDK는 Bot Connector REST API를 기반으로 래핑 및 빌드됩니다. SDK를 지원하는 기본 HTTP 요청을 이해하려면 커넥터 인증 및 관련 문서를 참조하세요. 봇이 보내고 받는 활동은 Bot Framework 활동 스키마를 준수합니다.