Microsoft 365 Copilot 평가 CLI(@microsoft/m365-copilot-eval)를 사용하면 자동화된 프롬프트 평가 및 AI 기반 점수 매기기를 통해 에이전트의 품질을 테스트, 측정 및 개선할 수 있습니다. 이 빠른 시작에서는 CLI 설치, 환경 구성, 첫 번째 데이터 세트 생성 및 평가 실행 과정을 안내합니다.
참고
이 빠른 시작에서는 CLI v1(latest)을 사용하여 배포된 에이전트를 평가합니다. CLI v2 미리 보기, 플러그 인 시나리오 및 새 ToolCallSelection 및 ToolCallExecution 계산기는 도구 호출 계산기를 참조하세요.
중요
배포된 선언적 에이전트의 경우 단계별 워크플로를 위해 Work IQ Dev 도구 로 시작합니다. Work IQ Dev Tools는 호환되는 Microsoft 365 Copilot 평가 CLI 버전을 관리하므로 전역적으로 설치할 @microsoft/m365-copilot-eval 필요가 없습니다. 하위 수준의 명령 제어가 필요하거나 기존 runevals 워크플로를 유지 관리해야 할 때 이 빠른 시작을 따르세요.
필수 구성 요소
시작하기 전에 다음 사항이 있는지 확인합니다.
- 테넌트에 배포된 Microsoft 365 Copilot 에이전트입니다.
-
Node.js 24.12.0 이상(검사에 사용
node --version). - 테넌트에서 사용할 수 있는 Copilot 크레딧입니다. Microsoft 365 Copilot 평가 CLI는 에이전트에 테스트 프롬프트를 보낼 때 Copilot 크레딧을 사용합니다. 테넌트 관리자는 Copilot> 비용관리 노드로 이동하여 Microsoft 365 관리 센터에서 사용량 기반(요금제) 청구를 켭니다. 자세한 내용은 Copilot 크레딧 관리를 참조하세요.
- 응답의 점수를 매기기 위해 배포된 GPT-5 모델이 있는 Microsoft Foundry 프로젝트입니다. 자세한 내용은 환경 변수에 대한 값 가져오기를 참조하세요.
- 테넌트에서 Work IQ에 대해 Microsoft Entra 관리자 동의가 부여되었습니다. 테넌트 관리자가 아닌 경우 처음 실행
runevals하기 전에 관리자에게 동의를 요청하세요. 자세한 내용은 관리자 동의 부여를 참조하세요. - 테넌트 ID 및 Microsoft Foundry 프로젝트 엔드포인트입니다. 이러한 값이 없는 경우 환경 변수에 대한 값 가져오기를 참조하세요.
참고
이 빠른 시작에서는 Windows 개발 환경을 사용하고 있다고 가정합니다. 다른 운영 체제에 대한 인증 지원이 곧 제공될 예정입니다.
1단계: CLI 설치
npm을 사용하여 전역적으로 Microsoft 365 Copilot 평가 CLI v1을 설치합니다.
npm install -g @microsoft/m365-copilot-eval@latest
설치를 확인합니다.
runevals --version
설치 runevals 한 후에는 시스템에서 전역적으로 명령을 사용할 수 있습니다.
2단계: 프로젝트 구조 설정
평가 도구 리포지토리가 아닌 Microsoft 365 에이전트 프로젝트 디렉터리 (에이전트 코드가 있는 위치)에서 평가 도구를 실행합니다.
cd /path/to/your-agent-project
에이전트 프로젝트에는 다음 파일과 폴더가 포함되어야 합니다.
my-agent/
├── .env.local # Agent configuration (Agents Toolkit projects)
├── .env.local.user # Secrets — never committed
├── evals/
│ └── evals.json # Your test dataset (auto-discovered)
└── .evals/
└── <generated reports> # Results written here (YYYY-MM-DD_HH-MM-SS.html)
4단계에서 데이터 세트를 evals/evals.json 만듭니다.
.evals/ 처음 실행 시 보고서 폴더가 자동으로 만들어집니다.
3단계: 환경 변수 구성
프로젝트 유형과 일치하는 옵션을 선택합니다.
팁
Microsoft 365 에이전트 도구 키트를 사용하여 에이전트를 빌드한 경우 에이전트 구성이 이미 있습니다 .env.local . 프로젝트 루트에서 비밀을 만듭니다 .env.local.user .
Microsoft 365 에이전트 도구 키트 프로젝트
직접 설정 M365_AGENT_ID 하지 않습니다. CLI가 에서 자동으로 검색합니다M365_TITLE_ID..env.local 자세한 내용은 에이전트 ID 가져오기를 참조하세요.
비밀 추가:.env.local.user
# .env.local.user (NOT checked in — secrets go here)
TENANT_ID="your-tenant-id-here"
AZURE_AI_PROJECT_ENDPOINT="https://<account>.services.ai.azure.com/api/projects/<project>"
AZURE_AI_MODEL_NAME="gpt-5-mini" # default
Microsoft 365 Copilot 평가 CLI는 Microsoft Entra로 인증하는 Microsoft Foundry 클라우드 평가를 사용하여 응답의 점수를 매깁니다. 실행runevals하기 전에 Azure CLI(az login)로 로그인합니다. 이러한 값에 대한 자세한 내용은 환경 변수에 대한 값 가져오기 단원을 참조하십시오.
다음.gitignore에 추가.env.local.user:
# User-specific secrets — never commit
.env.local.user
env/.env.local.user
4단계: 첫 번째 데이터 세트 만들기
작은 프롬프트 집합과 예상되는 응답으로 만듭니다 evals/evals.json . 이 예제에서는 단일 턴 평가에 가장 간단한 유효한 스키마를 사용합니다.
{
"schemaVersion": "1.0.0",
"items": [
{
"prompt": "What is Microsoft 365?",
"expected_response": "Microsoft 365 is a cloud-based productivity suite that includes Office apps, cloud services, and device management."
},
{
"prompt": "How do I share a file in Microsoft Teams?",
"expected_response": "To share a file in Teams, you can upload it to a channel or chat, or share it from OneDrive with specific permissions."
}
]
}
팁
이 단계를 건너뛰면 도구를 처음 실행할 runevals때 샘플 프롬프트와 함께 시작 파일을 생성하도록 제안합니다.
전체 데이터 세트 스키마, 범주 및 고급 패턴은 평가 테스트 도구 모음 만들기를 참조하세요.
5단계: 첫 번째 평가 실행
에이전트 도구 키트 프로젝트의 경우(자동으로 및 .env.local.user사용.env.local):
runevals
비 에이전트 도구 키트 프로젝트의 경우:
runevals --env dev
6단계: 성공적인 설정 확인
성공적으로 실행하면 다음이 생성됩니다.
다음 메시지와 유사한 완료 메시지가 터미널에 표시됩니다.
Microsoft 365 Copilot Evaluations CLI Loading environment: dev Agent ID: T_my-agent.declarativeAgent Using prompts file: ./evals/evals.json Running evaluations... Evals completed successfully! Results saved to: ./.evals/2026-04-22_14-30-45.html브라우저에서 자동으로 열리는 HTML 보고서에
./.evals/YYYY-MM-DD_HH-MM-SS.html저장됩니다.
보고서에는 각 프롬프트에 대한 점수가 포함됩니다.
| 평가자 | Type(종류) | Scale | 기본 임계값 | Default |
|---|---|---|---|---|
| 관련성 | LLM 기반 | 1-5 | 3 | 예 |
| 일관성 | LLM 기반 | 1-5 | 3 | 예 |
| 기초함 | LLM 기반 | 1-5 | 3 | 아니요 |
| 유사성 | LLM 기반 | 1-5 | 3 | 아니요 |
| 인용 | 개수 기반 | >= 0 | 1 | 아니요 |
| ExactMatch | 문자열 일치 | 부울 | 해당 없음 | 아니요 |
| PartialMatch | 문자열 일치 | 0.0-1.0 | 0.5 | 아니요 |
이러한 결과가 표시되지 않으면 문제 해결을 참조하세요.