Referência da CLI de Avaliações do Microsoft 365 Copilot

Este artigo fornece uma referência completa da linha de comando para o runevals comando, que faz parte do @microsoft/m365-copilot-eval pacote.

Sinopse

runevals [options]
runevals cache-info
runevals cache-clear
runevals cache-dir

Descrição

O runevals comando avalia os agentes do Microsoft 365 Copilot enviando prompts de teste e pontuando as respostas usando a avaliação na nuvem do Microsoft Foundry e métricas internas. A ferramenta oferece suporte à avaliação em lote de arquivos JSON, prompts embutidos e testes interativos.

A CLI v1 usa a tag npm latest . A CLI v2 usa preview e também avalia as respostas do Copilot que usam plug-ins. Na v2, uma execução sem uma ID de agente configurada avalia o chat do Microsoft 365 Copilot. Para obter exemplos de configuração de visualização e esquema v2, consulte Avaliadores de chamada de ferramentas.

Opções

-V, --version

Produza o número da versão da ferramenta CLI.

Exemplo:

runevals --version

Saída:

1.15.0

--log-level [level]

Defina o nível de detalhamento de log. Níveis disponíveis: debug, info, warningerror, .

  • Padrão: quando você usa o sinalizador sem um valor, o padrão infoé .
  • debug: informações detalhadas de depuração, incluindo payloads de API.
  • info: Informações gerais sobre o progresso da avaliação.
  • warning: Somente mensagens de aviso.
  • error: Somente mensagens de erro.

Exemplos:

# Info level (default when flag is present)
runevals --log-level

# Debug level
runevals --log-level debug

# Error level only
runevals --log-level error

Aviso

O debug nível pode incluir cargas de API brutas e dados de resposta na saída do console. A redação é baseada em padrão e pode não capturar todas as PII ou credenciais. Não compartilhe a saída de depuração publicamente sem revisão manual.

--prompts <prompts...>

Especifique um ou mais prompts diretamente na linha de comando para testes rápidos sem criar um arquivo.

Exemplos:

# Single prompt
runevals --prompts "What is Microsoft 365?"

# Multiple prompts
runevals --prompts "What is Teams?" "What is SharePoint?" "What is OneDrive?"

--expected <responses...>

Forneça as respostas esperadas para acompanhar os prompts especificados com --prompts. O número de respostas deve corresponder ao número de prompts.

Exemplo:

runevals --prompts "What is Microsoft Graph?" \
  --expected "Microsoft Graph is the API gateway to Microsoft 365 data and intelligence."

Vários prompts e respostas:

runevals --prompts "What is Teams?" "What is SharePoint?" \
  --expected "Teams is a collaboration platform" "SharePoint is a content management system"

--prompts-file <file>

Especifique um arquivo JSON personalizado contendo prompts de teste. Esse arquivo substitui a descoberta automática.

Exemplo:

runevals --prompts-file ./tests/my-custom-tests.json

Formato do arquivo:

[
  {
    "prompt": "Test question",
    "expected_response": "Expected answer"
  }
]

Para obter o esquema completo do conjunto de dados, consulte Esquema do conjunto de dados e design de teste.

-o, --output <file>

Especifique o caminho e o formato do arquivo de saída. O formato é determinado pela extensão do arquivo.

Formatos com suporte:

  • .html - Relatório HTML (padrão, abre automaticamente no navegador)
  • .json - Resultados JSON
  • .csv - Planilha CSV

Exemplos:

# HTML output
runevals --output ./reports/results.html

# JSON output
runevals --output ./results/eval-results.json

# CSV output
runevals --output ./data/scores.csv

Comportamento padrão:

Sem --output, o comando salva os resultados em ./.evals/YYYY-MM-DD_HH-MM-SS.html.

-i, --interactive

Entre no modo interativo para entrada manual de prompt e teste.

Exemplo:

runevals --interactive

No modo interativo, você é solicitado a inserir prompts um de cada vez, para que possa fazer testes exploratórios.

--m365-agent-id <id>

Substitua o ID do agente para avaliar um agente específico. Esse parâmetro é útil ao testar vários agentes ou quando o ID do agente não pode ser detectado automaticamente.

Exemplo:

runevals --m365-agent-id "U_0dc4a8a2-b95f-edac-91c8-d802023ec2d4"

Formatos de ID do agente:

  • Escopo pelo usuário: U_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  • Escopo do locatário: T_agent-name.declarativeAgent

Para cenários de plug-in de visualização v2, omita essa opção e remova M365_AGENT_ID um legado AGENT_ID do shell e dos arquivos de ambiente carregados.

--list-tools <agent-id> (Versão prévia v2)

Liste identificadores de consentimento e identidades de avaliador prontas para cópia para ações de um agente declarativo. Essa opção não é compatível com plug-ins autônomos. As ferramentas descobertas dinamicamente podem não aparecer; Confirmar suas identidades após diagnostics.tool_calls uma avaliação.

npx -y --package @microsoft/m365-copilot-eval@preview runevals --list-tools "<your-agent-id>"

Para obter nomes de consentimento de plug-in autônomo e a identidade do avaliador de três partes, consulte Localizar nomes de chamada de ferramenta.

--evaluate-only <file>

Repontue as respostas salvas e os diagnósticos disponíveis sem executar prompts. Cada item ou turno deve incluir um response. Configure um juiz se você selecionar avaliadores baseados em LLM; A autenticação de execução do Microsoft 365 não é necessária.

runevals --evaluate-only results\captured-responses.json --output results\rescored.html

A repontuação da chamada de ferramenta requer visualização da CLI v2 e evidências de chamada de ferramenta retidas. Para obter detalhes, consulte Avaliação de diagnóstico e resposta salva.

--env <environment>

Especifique a configuração de ambiente a ser carregada. Este parâmetro carrega env/.env.<environment>.

Padrão: dev (carrega env/.env.dev)

Exemplos:

# Load env/.env.dev (default)
runevals --env dev

# Load env/.env.prod
runevals --env prod

# Load env/.env.staging
runevals --env staging

Precedência do arquivo de ambiente:

  1. .env.local (detectado automaticamente para projetos do Kit de Ferramentas de Agentes)
  2. .env.local.user (segredos, carregado automaticamente, se presente)
  3. env/.env.<environment> (especificado por --env)
  4. Variáveis de ambiente do sistema

--init-only

Inicializa o ambiente Python e baixa dependências sem executar avaliações. Essa opção é útil para:

  • Pré-aquecendo o cache em pipelines de CI/CD
  • Solução de problemas de instalação
  • Verificando a instalação antes de executar testes

Exemplo:

runevals --init-only

Para solução de problemas, combine esta opção com --log-level debug:

runevals --init-only --log-level debug

-h, --help

Exibe informações da ajuda sobre comandos e opções disponíveis.

Exemplo:

runevals --help

Comandos de cache

A ferramenta de avaliação usa um cache local para o runtime e as dependências do Python. Esses comandos ajudam a gerenciar o cache.

cache-info

Exibe estatísticas sobre o ambiente Python em cache, incluindo tamanho, localização e pacotes instalados.

Exemplo:

runevals cache-info

Saída:

Cache Information

Location: C:\Users\YourName\.m365-copilot-eval\cache
Size: 245 MB
Python Version: 3.11.5
Packages: 42 installed

Last updated: 2026-04-10 14:23:15

cache-clear

Remove o ambiente Python em cache e todas as dependências baixadas. Use esse comando ao solucionar problemas de instalação ou liberar espaço em disco.

Exemplo:

runevals cache-clear

Acompanhamento:

Depois de limpar o cache, reininicialize:

runevals --init-only

cache-dir

Imprime o caminho absoluto para o diretório de cache. Esse recurso é útil para scripts ou inspeção manual.

Exemplo:

runevals cache-dir

Saída:

C:\Users\YourName\.m365-copilot-eval\cache

Uso em scripts:

# Check cache directory permissions (Unix/macOS)
chmod -R u+w $(runevals cache-dir)

# View cache contents
ls -lah $(runevals cache-dir)

Variáveis de ambiente

A ferramenta lê a configuração de arquivos de ambiente e variáveis do sistema. Para obter instruções passo a passo sobre como obter esses valores, consulte Variáveis de ambiente necessárias.

Variáveis obrigatórias

Variável Descrição Exemplo
TENANT_ID ID do locatário do Microsoft Entra xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
AZURE_AI_PROJECT_ENDPOINT Ponto de extremidade do projeto Microsoft Foundry para pontuação baseada em LLM. Não é necessário para a avaliação somente determinística. https://<account>.services.ai.azure.com/api/projects/<project>

Variáveis opcionais

Variável Descrição Padrão
M365_AGENT_ID ID do agente a ser avaliada Detecção automática de M365_TITLE_ID
M365_TITLE_ID ID do título do agente (Agents Toolkit) Nenhum
AZURE_AI_MODEL_NAME Modelo para avaliações gpt-5-mini
EVALS_SUPPRESS_DIAGNOSTICS Defina como true para omitir os diagnósticos retidos. Não redigir prompts, respostas, opções do avaliador ou mensagens de validação nativas. Evidências suprimidas não podem ser reproduzidas. Remover definição

Exemplos

Uso básico

Avalie usando o arquivo de conjunto de dados descoberto automaticamente:

cd /path/to/your-agent-project
runevals

Especificar ambiente

Usar a configuração do ambiente de produção:

runevals --env prod

Arquivo de conjunto de dados personalizado

Use um arquivo de teste específico:

runevals --prompts-file ./tests/regression-tests.json

Teste em linha

Teste rápido com prompts embutidos:

runevals --prompts "What is Microsoft 365?" \
  --expected "Microsoft 365 is a cloud-based productivity suite"

Modo interativo

Inserir prompts manualmente:

runevals --interactive

Formato de saída personalizado

Gerar resultados JSON:

runevals --output ./results/eval-$(date +%Y%m%d).json

Modo de depuração

Execute com registro em log detalhado:

runevals --log-level debug --output ./debug-results.json

Somente configuração

Pré-cache do ambiente Python sem executar testes:

runevals --init-only --log-level info

Substituir ID do agente

Teste um agente específico:

runevals --m365-agent-id "U_0dc4a8a2-b95f-edac-91c8-d802023ec2d4"

Opções combinadas

Avaliação abrangente com configurações personalizadas:

runevals \
  --env staging \
  --prompts-file ./evals/full-suite.json \
  --output ./reports/staging-eval-$(date +%Y%m%d).html \
  --log-level info \
  --m365-agent-id "T_my-agent.declarativeAgent"

Códigos de saída

Código Significado
0 Sucesso
1 Erro geral
2 Argumentos inválidos
3 Erro de configuração do ambiente
4 Agente não encontrado
5 Falha na autenticação
10 Falha na configuração do ambiente Python

Solução de problemas

Para problemas comuns com instalação, autenticação, erros de tempo de execução, problemas de cache e configuração de proxy, consulte o artigo de solução de problemas .