에뮬레이터를 사용하여 테스트 및 디버그
적용 대상: SDK v4
Bot Framework Emulator는 봇 개발자가 로컬 또는 원격으로 봇을 테스트하고 디버그할 수 있는 데스크톱 애플리케이션입니다. Emulator를 사용하면 봇과 채팅하고 봇이 보내고 받는 메시지를 검사할 수 있습니다. Emulator는 봇과 메시지를 교환할 때 웹 채팅 UI에 표시되는 대로 메시지를 표시하며 JSON 요청과 응답을 기록합니다. 봇을 클라우드에 배포하기 전에 Emulator를 사용하여 로컬로 실행하고 테스트합니다. 아직 Azure AI Bot Service를 사용하여 봇을 만들거나 채널에서 실행하도록 구성하지 않은 경우에도 에뮬레이터를 사용하여 봇을 테스트할 수 있습니다.
참고 항목
Bot Framework JavaScript, C#및 Python SDK는 계속 지원되지만 Java SDK는 2023년 11월에 종료되는 최종 장기 지원으로 사용 중지됩니다.
Java SDK를 사용하여 빌드된 기존 봇은 계속 작동합니다.
새 봇 빌드의 경우 Microsoft Copilot Studio를 사용하고 올바른 부조종사 솔루션 선택에 대해 알아봅니다.
자세한 내용은 봇 빌드의 미래를 참조 하세요.
필수 조건
- Bot Framework Emulator 설치
로컬로 봇 실행
Bot Framework Emulator에 봇을 연결하기 전에 봇을 로컬로 실행해야 합니다. Visual Studio 또는 Visual Studio Code를 사용하여 봇을 실행하거나 명령줄을 사용할 수 있습니다. 명령줄을 사용하여 봇을 실행하려면 다음을 수행합니다.
명령줄 프롬프트로 이동하여 디렉터리를 봇 프로젝트 디렉터리로 변경합니다.
다음 명령을 실행하여 봇을 시작합니다.
dotnet run애플리케이션이 시작되기 전에 줄의 포트 번호를 복사합니다. Ctrl+C를 눌러 종료합니다.
이 시점에서 봇은 로컬로 실행되어야 합니다.
로컬 호스트에서 실행되는 봇에 연결
프록시 설정 구성
회사 프록시 뒤에서 개발하는 경우 에뮬레이터는 구성된 환경 변수 HTTP_PROXY 를 사용하고 HTTP 및 HTTPS_PROXYHTTP 요청에 대한 프록시 URL 경로를 각각 지정합니다.
실행 중인 봇에 localhost연결하는 경우 에뮬레이터는 먼저 연결하기 전에 프록시를 통해 라우팅을 시도합니다 localhost. 일반적으로 프록시는 연결을 무시 localhost하도록 지정하지 않는 한 연결을 차단합니다.
및 HTTPS_PROXY 설정을 무시하고 HTTP_PROXY 에뮬레이터가 연결할 localhost수 있도록 하려면 로컬 컴퓨터에서 다음 환경 변수를 정의해야 합니다.
NO_PROXY=localhost
인증을 위해 에뮬레이터 구성
봇에 로그인 대화 상자를 표시하는 인증이 필요한 경우 아래와 같이 에뮬레이터를 구성해야 합니다.
로그인 확인 코드 사용
- 에뮬레이터를 시작합니다.
- 에뮬레이터의 왼쪽 창에서 설정(기어 아이콘)을 선택합니다.
- OAuthCards에 대한 로그인 확인 코드 사용
- 저장을 선택합니다.
봇이 표시하는 로그인 단추를 선택하면 유효성 검사 코드가 생성됩니다. 인증이 수행되도록 봇 입력 채팅 상자에 코드를 입력합니다. 그런 다음 허용된 작업을 수행할 수 있습니다.
또는 아래에 설명된 단계를 수행할 수 있습니다.
인증 토큰 사용
- 에뮬레이터를 시작합니다.
- 에뮬레이터의 왼쪽 창에서 설정(기어 아이콘)을 선택합니다.
- 버전 1.0 인증 토큰 사용
- 저장을 선택합니다.
봇이 표시하는 로그인 단추를 선택하면 자격 증명을 입력하라는 메시지가 표시됩니다. 인증 토큰이 생성됩니다. 그런 다음 허용된 작업을 수행할 수 있습니다.
로컬로 실행되는 봇에 연결하려면 봇 열기를 선택합니다. 이전에 복사한 포트 번호를 다음 URL에 추가하고 업데이트된 URL을 봇 URL 표시줄에 붙여넣습니다.
http://localhost:<port number>/api/messages
MSA(Microsoft 계정) 자격 증명을 사용하여 봇을 실행하는 경우 이 자격 증명도 입력합니다.
봇 자격 증명 사용
봇을 열 때 봇이 자격 증명을 사용하여 실행되는 경우 Microsoft 앱 ID 및 Microsoft 앱 암호를 설정합니다. Azure AI Bot Service를 사용하여 봇을 만든 경우 자격 증명은 설정 -> 구성 섹션의 봇 App Service에서 사용할 수 있습니다. 값을 모르는 경우 로컬로 실행 중인 봇의 구성 파일에서 해당 값을 제거한 다음 에뮬레이터에서 봇을 실행할 수 있습니다. 봇이 이러한 설정으로 실행되지 않는 경우 설정으로 에뮬레이터를 실행할 필요가 없습니다.
AD ID 공급자 애플리케이션을 만드는 경우 다음 사항에 주의하세요.
- 지원되는 계정 유형을 단일 테넌트로 설정하면 Microsoft 계정 대신 개인 구독을 사용하는 경우 에뮬레이터에서 오류를 발생합니다. 봇의 Microsoft 앱 ID 또는 Microsoft 앱 암호가 올바르지 않습니다.
- 이 경우 지원되는 계정 유형을 모든 조직 디렉터리(모든 Microsoft Entra ID 디렉터리 - 다중 테넌트) 및 개인 Microsoft 계정(예: Xbox)의 계정으로 설정해야 합니다.
자세한 내용은 Azure Portal을 사용하여 Microsoft Entra ID ID 공급자 애플리케이션 만들기 및 새 애플리케이션 등록을 참조하세요.
검사기를 사용하여 자세한 메시지 활동 보기
봇에 메시지를 보내면 봇이 응답합니다. 대화 창 내에서 메시지 풍선을 선택하고, 창의 오른쪽에 있는 검사기 기능을 사용하여 원시 JSON 작업을 검사할 수 있습니다. 메시지 풍선을 선택하면 해당 풍선이 노란색으로 바뀌며 활동 JSO 개체가 채팅 창 왼쪽에 표시됩니다. JSON 정보에는 채널 ID, 활동 유형, 대화 ID, 텍스트 메시지, 엔드포인트 URL 등과 같은 주요 메타데이터가 포함됩니다. 사용자로부터 보낸 활동과 봇이 응답하는 활동을 검사할 수 있습니다.
팁
검사 미들웨어를 봇에 추가하여 채널에 연결된 봇의 상태 변경을 디버그할 수 있습니다.
서비스 검사
참고 항목
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의 언어 이해 지원에 대한 자세한 내용은 자연어 이해를 참조하세요.
에뮬레이터를 사용하여 LUIS 및 QnA Maker의 JSON 응답을 검사할 수도 있습니다. 연결된 언어 서비스가 있는 봇을 사용하여 LOG 창의 오른쪽 아래에서 추적을 선택할 수 있습니다. 이 새로운 도구는 에뮬레이터에서 직접 언어 서비스를 업데이트하는 기능도 제공합니다.
연결된 LUIS 서비스를 사용하여 추적 링크는 Luis 추적을 지정합니다. 이 옵션을 선택하면 지정된 점수와 함께 의도 및 엔터티를 포함하는 LUIS 서비스의 원시 응답이 표시됩니다. 사용자 발화에 대한 의도를 다시 할당할 수 있습니다.
연결된 QnA Maker 서비스를 사용하면 로그에 QnA 추적이 표시됩니다. 선택하면 신뢰도 점수와 함께 해당 활동과 관련된 질문 및 답변 쌍을 미리 볼 수 있습니다. 여기에서 답변에 대한 대체 질문 문구를 추가할 수 있습니다.
Azure에 로그인
에뮬레이터를 사용하여 Azure 계정에 로그인할 수 있습니다. 이는 봇이 의존하는 서비스를 추가하고 관리하는 데 유용합니다. 로그인 방법:
파일을 선택한 다음, Azure로 로그인합니다.
시작 화면에서 Azure 계정으로 로그인을 선택합니다. 필요에 따라 에뮬레이터 애플리케이션을 다시 시작할 때 에뮬레이터가 로그인된 상태로 유지하도록 할 수 있습니다.
데이터 수집을 사용하지 않도록 설정
에뮬레이터의 사용량 현황 데이터 수집을 중지하게 하려면 다음 단계에 따라 데이터 수집을 간단히 해제할 수 있습니다.
에뮬레이터의 왼쪽 창에서 설정(기어 아이콘)을 선택합니다.
데이터 수집에서 사용량 현황 데이터를 수집할 수 있도록 하여 에뮬레이터 개선 도움말을 선택 취소합니다.
저장을 선택합니다.
마음이 바뀌면 나중에 데이터 수집을 다시 사용할 수 있습니다.
추가 리소스
Bot Framework Emulator는 오픈 소스입니다. 버그 및 제안을 제출하여 개발에 기여할 수 있습니다.
문제를 해결하려면 일반 문제 해결 및 해당 섹션의 다른 문제 해결 문서를 참조하세요.
다음 단계
검사 미들웨어를 사용하여 채널에 연결된 봇을 디버그합니다.