Solução de problemas do agente do framework

Esta página ajuda a diagnosticar e resolver problemas comuns ao trabalhar com o Agent Framework.

Nesta página:

Instalação e configuração

Problemas comuns:falhas de instalação, erros de importação e problemas de autenticação da API.

Verificação:

  • Versões do Python e do pip
  • Integridade e caminho do arquivo .whl
  • Configuração do arquivo .env (chaves de API, detalhes do projeto)
  • Configuração de gcloud auth (para a Vertex AI)
  • Instalação de dependências (requirements.txt)
  • Ativação do ambiente virtual

Problemas com a definição do agente

Problemas comuns:o agente não se comporta como esperado, as ferramentas não são chamadas e há erros no agent.py.

Verificação:

  • Sintaxe de código agent.py (linting)
  • Agente instruction clareza e correção
  • Definições de ferramentas (nomes, descrições, parâmetros)
  • Atributos do agente (name, model, tools, flow): erros de digitação e validade
  • Lógica de código em agent.py: use instruções de impressão para depuração

Problemas de execução

Problemas comuns:comandos da CLI com falha (af run, af web, af test), erros de interface da Web, problemas com o servidor da API.

Verificação:

  • Sintaxe e argumentos do comando da CLI (--help)
  • Diretório de trabalho (raiz do projeto do agente)
  • Mensagens de erro do terminal (cópia de erros completos)
  • Conflitos de porta (para a IU da Web/servidor da API, tente portas diferentes)
  • Compatibilidade do navegador (para a IU da Web)
  • Erros do console do navegador (para a IU da Web)

Problemas de avaliação

Problemas comuns:falhas de teste, resultados de avaliação inesperados.

Verificação:

  • Sintaxe do arquivo *.test.json (JSON válido)
  • Testar o conteúdo do arquivo (consultas, expected_tool_use, precisão reference)
  • Caminhos de arquivo no comando af test ou no código pytest
  • Critérios de avaliação em test_config.json (se usados)
  • Executar testes na IU da Web para receber feedback visual

Mensagens de erro comuns

  • Problema de instalação
  • Problema com a chave de API ou a autenticação
  • Atributo model incorreto
  • Conflito de porta no servidor da Web/API

Dicas gerais para solução de problemas:

  • Simplifique e isole: comece de forma simples e aumente a complexidade gradualmente.
  • Ver os registros: terminal, Cloud Logging, console do navegador.
  • Consulte a documentação: leia novamente as seções relevantes.
  • Pesquisa on-line: Stack Overflow, fóruns.
  • Fornecer informações detalhadas ao pedir ajuda: código, erros, etapas, ambiente.