Este documento descreve como resolver erros que podem ser encontrados ao configurar um ambiente para o Agent Runtime. Ele aborda etapas de solução de problemas de importação de pacotes.
Erros ao importar o SDK da Agent Platform
Quando não é possível importar o SDK da Agent Platform para Python, a causa pode ser um dos seguintes problemas:
Versão desatualizada do SDK da Agent Platform para Python
Problema:
Você recebe uma mensagem de erro semelhante a esta:
ImportError: cannot import name 'reasoning_engines' from 'vertexai.preview'
ou
ImportError: cannot import name 'agent_angines' from 'vertexai'
Possível causa:
Isso pode acontecer quando a versão do pacote google-cloud-aiplatform é anterior a 1.82.0 (para agent_engines) ou 1.47.0 (para reasoning_engines). Para verificar a versão do pacote google-cloud-aiplatform, execute o seguinte comando no terminal:
pip show google-cloud-aiplatformSolução recomendada:
Execute o seguinte comando no terminal para atualizar o
pacote google-cloud-aiplatform:
pip install google-cloud-aiplatform --upgradeVerifique se a versão atualizada é 1.82.0 ou mais recente executando o seguinte comando:
pip show google-cloud-aiplatformNo caso de uma instância de notebook (por exemplo, Jupyter, Colab ou Workbench), talvez seja necessário reiniciar o ambiente de execução para usar os pacotes atualizados.
Erros de autorização 401
Problema:
Você recebe uma mensagem de erro semelhante a esta:
Error Code: "401"
Error Details: "Context-Aware Access requirements are not met"
OU
Agent Engine Error: An error occurred during invocation. Exception: API request failed with status 401:
Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential.
Possível causa:
Por padrão, quando você usa a identidade do agente com o Agent Runtime, os tokens de acesso vinculados ao certificado são usados para autenticação para evitar o roubo de tokens. Um erro 401 pode ocorrer no ambiente de execução em um dos dois cenários a seguir:
- Usuário ou agente tentando usar um token de acesso fora do contexto em que ele foi emitido, como a transmissão do token entre agentes.
- Agente chamando um endpoint de API não compatível com mTLS, como telemetry.googleapis.com em vez de telemetry.mtls.googleapis.com.
Solução recomendada:
Para o cenário 1, se você tiver um motivo legítimo para compartilhar tokens entre agentes, poderá desativar a política de acesso baseado no contexto (CAA, na sigla em inglês) padrão. Essa ação não é recomendada, porque deixa um agente vulnerável ao roubo de credenciais.
Para desativar a política de CAA padrão, defina a seguinte variável de ambiente ao criar a instância do Agent Runtime:
config={
"env_vars": {
"GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False,
}
}
Para o cenário 2, você pode definir a variável GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES como False para permitir que os agentes usem os endpoints da API não mTLS como uma solução alternativa temporária. Nesse caso, o problema subjacente pode ser um problema conhecido com o ADK.