Referência da CLI de avaliações de agente

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.

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

`--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:

.env.local (detectado automaticamente para projetos do Kit de Ferramentas de Agentes)
.env.local.user (segredos, carregado automaticamente, se presente)
env/.env.<environment> (especificado por --env)
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	`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`

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`	Êxito
`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 .

Comentários

Esta página foi útil?

Last updated on 2026-08-13

Referência da CLI de avaliações de agente

Sinopse

Descrição

Opções

-V, --version

--log-level [level]

--prompts <prompts...>

--expected <responses...>

--prompts-file <file>

-o, --output <file>

-i, --interactive

--m365-agent-id <id>

--env <environment>

--init-only

-h, --help

Comandos de cache

cache-info

cache-clear

cache-dir

Variáveis de ambiente

Variáveis obrigatórias

Variáveis opcionais

Exemplos

Uso básico

Especificar ambiente

Arquivo de conjunto de dados personalizado

Teste em linha

Modo interativo

Formato de saída personalizado

Modo de depuração

Somente configuração

Substituir ID do agente

Opções combinadas

Códigos de saída

Solução de problemas

Conteúdo relacionado

Comentários

Recursos adicionais

`-V, --version`

`--log-level [level]`

`--prompts <prompts...>`

`--expected <responses...>`

`--prompts-file <file>`

`-o, --output <file>`

`-i, --interactive`

`--m365-agent-id <id>`

`--env <environment>`

`--init-only`

`-h, --help`

`cache-info`

`cache-clear`

`cache-dir`