Início Rápido: Usar a CLI de Avaliações do Agente

A CLI de avaliações de agentes do Microsoft 365 Copilot (@microsoft/m365-copilot-eval) ajuda você a testar, medir e melhorar a qualidade de seus agentes por meio de avaliação imediata automatizada e pontuação baseada em IA. Este guia de início rápido orienta você na instalação da ferramenta Agent Evaluations, na configuração do ambiente, na criação do primeiro conjunto de dados e na execução de uma avaliação.

Importante

Para agentes declarativos implantados, comece com o Work IQ Dev Tools (versão prévia) para obter um fluxo de trabalho guiado. O Work IQ Dev Tools gerencia a versão compatível da CLI de avaliações de agente, portanto, você não precisa instalar @microsoft/m365-copilot-eval globalmente. Siga este início rápido quando precisar de controle de comando de nível inferior ou manter um fluxo de trabalho existente runevals .

Pré-requisitos

Antes de começar, verifique se você tem:

  • Um agente do Microsoft 365 Copilot implantado em seu locatário.
  • Node.js 24.12.0 ou posterior (use node --version para marcar).
  • Créditos do Copilot disponíveis em seu locatário. A CLI de avaliações de agente consome créditos do Copilot ao enviar prompts de teste ao seu agente. O administrador do locatário ativa a cobrança baseada em uso (limitada) no Centro de administração do Microsoft 365 acessando o nóGerenciamento de Custos do Copilot>. Para obter mais informações, consulte Gerenciar créditos do Copilot.
  • Um projeto do Microsoft Foundry com um modelo GPT-5 implantado para pontuar respostas. Para obter mais informações, consulte Obter valores para variáveis de ambiente.
  • Consentimento de administrador do Microsoft Entra concedido para o Work IQ em seu locatário. Se você não for um administrador de locatários, peça a ele para conceder consentimento antes de executar runevals pela primeira vez. Para obter mais informações, consulte Conceder consentimento do administrador.
  • Sua ID de locatário e o ponto de extremidade do projeto Microsoft Foundry. Se você não tiver esses valores, consulte Obter valores para variáveis de ambiente.

Observação

Este início rápido pressupõe que você esteja usando um ambiente de desenvolvimento do Windows. Em breve, haverá suporte de autenticação para outros sistemas operacionais.

Etapa 1: Instalar a CLI

Instale a CLI de avaliações de agente globalmente usando o npm:

npm install -g @microsoft/m365-copilot-eval

Verifique a instalação:

runevals --version

Após a instalação, o runevals comando estará disponível globalmente em seu sistema.

Etapa 2: Configure a estrutura do seu projeto

Execute a ferramenta de avaliação no diretório do projeto do agente do Microsoft 365 (onde está o código do agente), não no repositório da ferramenta de avaliações.

cd /path/to/your-agent-project

Seu projeto de agente deve incluir os seguintes arquivos e pastas:

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)

Você cria o evals/evals.json conjunto de dados na Etapa 4. A .evals/ pasta de relatório é criada automaticamente na primeira execução.

Etapa 3: Configurar variáveis de ambiente

Escolha a opção que corresponda ao seu tipo de projeto.

Dica

Se você criou seu agente usando o Microsoft 365 Agents Toolkit, você já tem .env.local com a configuração do agente. Crie .env.local.user no seu projeto raiz para segredos.

Projetos do Kit de Ferramentas de Agentes do Microsoft 365

Você não define M365_AGENT_ID diretamente — a CLI o detecta automaticamente a partir de M365_TITLE_ID ..env.local Para obter detalhes, consulte Obter sua ID de agente.

Adicionar segredos a .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

A CLI de Avaliações do Agente pontua as respostas usando a avaliação na nuvem do Microsoft Foundry, que se autentica com o Microsoft Entra. Entre com a CLI do Azure (az login) antes de executar runevals. Para obter detalhes sobre esses valores, consulte Obter valores para variáveis de ambiente.

Adicionar .env.local.user ao seu .gitignore:

# User-specific secrets — never commit
.env.local.user
env/.env.local.user

Etapa 4: criar seu primeiro conjunto de dados

Crie evals/evals.json com um pequeno conjunto de prompts e respostas esperadas. Este exemplo usa o esquema válido mais simples para avaliações de turno único.

{
  "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."
    }
  ]
}

Dica

Se você ignorar esta etapa, a ferramenta oferecerá a geração de um arquivo inicial com prompts de amostra na primeira vez que você executar runevalso .

Para esquema completo do conjunto de dados, categorias e padrões avançados, consulte Criar conjuntos de testes de avaliação.

Etapa 5: executar sua primeira avaliação

Para projetos do Agents Toolkit (usa .env.local.env.local.usere automaticamente):

runevals

Para projetos do Kit de Ferramentas não Agentes:

runevals --env dev

Etapa 6: confirmar a configuração bem-sucedida

Uma execução bem-sucedida produz:

  • Uma mensagem de conclusão no terminal semelhante à mensagem a seguir.

    M365 Copilot Agent 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

  • Um relatório HTML salvo para ./.evals/YYYY-MM-DD_HH-MM-SS.html que seja aberto automaticamente no navegador.

O relatório inclui pontuações para cada prompt.

Avaliador Tipo Escala Limite Padrão Padrão
Relevância Baseado em LLM 1-5 3 Sim
Coerência Baseado em LLM 1-5 3 Sim
Aterramento Baseado em LLM 1-5 3 Não
Similaridade Baseado em LLM 1-5 3 Não
Citações Com base em contagem >= 0 1 Não
ExactMatch Correspondência de cadeia de caracteres booliano N/D Não
PartialMatch Correspondência de cadeia de caracteres 0.0-1.0 0.5 Não

Se você não vir esses resultados, consulte Solução de problemas.

Conteúdo relacionado

  • Last updated on