Solucionar problemas da CLI de avaliações de agente

Este artigo fornece informações de solução de problemas para a CLI de Avaliações do Agente do Microsoft 365 Copilot. Os problemas são agrupados pelo estágio do fluxo de trabalho que afetam: configuração, autenticação, tempo de execução e ambiente.

Problemas de instalação

Problemas encontrados durante a instalação ou ao executar a CLI pela primeira vez.

Falhas de instalação

Se npm install -g @microsoft/m365-copilot-eval falhar:

  • Verifique se você está executando Node.js 24.12.0 ou posterior: node --version.
  • Verifique se você tem permissão para instalar pacotes npm globais. No Unix/macOS, você pode precisar sudo de uma instalação do Node gerenciado pelo nvm.
  • Se você estiver protegido por um proxy corporativo, consulte Problemas de rede ou proxy.

runevals Comando não encontrado

Se o comando não for reconhecido após a runevals instalação:

# Verify the package is installed globally
npm list -g @microsoft/m365-copilot-eval

# Reinstall if missing
npm install -g @microsoft/m365-copilot-eval

Se o pacote estiver listado, mas o comando ainda não for encontrado, Marque se o diretório global bin npm está em seuPATH:

npm bin -g

Adicione o diretório de saída ao seu PATH se ele estiver ausente.

Pré-armazenar em cache o ambiente Python

A ferramenta baixa um runtime do Python e dependências na primeira execução. Para configurar o ambiente antecipadamente sem executar avaliações:

runevals --init-only

Isso é útil para:

  • Pré-aquecimento do cache em pipelines de CI/CD.
  • Testar a configuração sem executar avaliações.
  • Isolar problemas de instalação de problemas de avaliação.

Para solucionar problemas da configuração em si, combine com o log de depuração:

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

Problemas de autenticação

Problemas com acesso ao locatário, agente ou Microsoft Foundry.

Erros de autenticação

Se a autenticação falhar:

  • A verificação TENANT_ID corresponde ao locatário em que o agente está implantado.
  • Confirme se você está executando no Windows. Em breve, haverá suporte para outros sistemas operacionais.
  • Verifique se você está conectado à conta do Microsoft 365 correta.
  • Se você estiver usando vários locatários, saia de outras contas antes de executar runevals.

Incompatibilidade de locatário

Se a ferramenta se conectar, mas não retornar nenhum agente, você TENANT_ID poderá não corresponder ao locatário em que o agente está implantado. Verifique a ID do locatário executando:

az account show --query tenantId

Você também pode seguir as instruções em Variáveis de ambiente obrigatórias.

Erros de pontuação da fundição

Se a pontuação de avaliação falhar com um erro 401 ou 403:

  • Verifique se você está conectado usando a CLI do Azure (az login) ao locatário que hospeda seu projeto do Microsoft Foundry.
  • Confirme se sua conta tem a função Desenvolvedor de IA do Azure no projeto Foundry.
  • Confirme AZURE_AI_PROJECT_ENDPOINT pontos para o projeto correto do Microsoft Foundry.
  • Verifique se gpt-5-mini (ou se o modelo definido em AZURE_AI_MODEL_NAME) está implantado em seu projeto Microsoft Foundry.

Problemas de tempo de execução

Problemas que ocorrem ao executar avaliações após a instalação bem-sucedida.

Agente não encontrado

Se a ferramenta não conseguir localizar seu agente:

  • Verificar M365_AGENT_ID está correto. Para projetos do Agents Toolkit, a CLI o detecta automaticamente em .env.local, portanto, marque esse valor em vez disso, consulte Obter sua ID de M365_TITLE_ID agente.
  • Confirme se o agente está implantado no locatário especificado pelo TENANT_ID.
  • Certifique-se de ter permissão para acessar o agente.
  • Tente especificar a ID do agente explicitamente: runevals --m365-agent-id "<your-agent-id>".

Falhas de avaliação

Se as avaliações começarem, mas falharem no meio da execução:

  • Execute com log detalhado para ver erros detalhados: runevals --log-level debug.
  • Verifique os códigos de saída para a categoria de falha geral. Consulte Códigos de saída na referência da CLI.

Aviso

A --log-level debug opção 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 todos os PII ou credenciais personalizadas. Não compartilhe publicamente a saída no nível de depuração sem revisão manual.

Problemas de ambiente

Problemas com o tempo de execução do Python em cache, diretório de cache ou conectividade de rede.

Problemas de cache

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

# View cache info
runevals cache-info

# Clear and rebuild the cache
runevals cache-clear
runevals --init-only --log-level debug

Problemas de permissão

Se as operações de cache falharem com erros de permissão:

# View the cache directory path
runevals cache-dir

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

# Fix permissions (Windows PowerShell)
icacls "$(runevals cache-dir)" /grant ${env:USERNAME}:F /T

Problemas de rede ou proxy

Se a inicialização falhar por trás de um proxy corporativo:

# Set proxy (Unix/macOS)
export HTTPS_PROXY=http://proxy:8080
export HTTP_PROXY=http://proxy:8080

# Set proxy (Windows PowerShell)
$env:HTTPS_PROXY="http://proxy:8080"
$env:HTTP_PROXY="http://proxy:8080"

# Retry initialization with verbose output
runevals --init-only --log-level debug

Obter suporte

Se as etapas de solução de problemas acima não resolverem seu problema, registre um problema no repositório GitHub de Avaliações do Agente do M365 Copilot.

Antes de registrar um problema, colete:

  • A versão da CLI: runevals --version.
  • O comando exato que você executou.
  • Saída de erro (redigir qualquer PII, chaves ou identificadores específicos do locatário).
  • Seu sistema operacional e Node.js versão: node --version.

Para registrar o problema:

Conteúdo relacionado

  • Last updated on