Résoudre les problèmes de configuration de l'environnement pour Agent Runtime

Ce document explique comment résoudre les erreurs que vous pouvez rencontrer lors de la configuration d'un environnement pour Agent Runtime. Il décrit les étapes de dépannage pour les problèmes d'importation de packages.

Erreurs lors de l'importation du SDK Agent Platform

Si vous ne parvenez pas à importer le SDK Agent Platform pour Python, cela peut être dû à l'un des problèmes suivants :

Version obsolète du SDK Agent Platform pour Python

Problème :

Vous recevez un message d'erreur semblable à celui-ci :

ImportError: cannot import name 'reasoning_engines' from 'vertexai.preview'

ou

ImportError: cannot import name 'agent_angines' from 'vertexai'

Cause possible :

Cela peut se produire si la version de votre package google-cloud-aiplatform est antérieure à 1.82.0 (pour agent_engines) ou 1.47.0 (pour reasoning_engines). Pour vérifier la version de votre package google-cloud-aiplatform, exécutez la commande suivante dans le terminal :

pip show google-cloud-aiplatform

Solution recommandée :

Exécutez la commande suivante dans votre terminal pour mettre à jour votre package google-cloud-aiplatform :

pip install google-cloud-aiplatform --upgrade

Vérifiez que votre version mise à jour est 1.82.0 ou ultérieure en exécutant la commande suivante :

pip show google-cloud-aiplatform

Si vous vous trouvez dans une instance de notebook (par exemple, Jupyter, Colab ou Workbench), vous devrez peut-être redémarrer votre environnement d'exécution pour utiliser les packages mis à jour.

Erreurs d'autorisation 401

Problème :

Vous recevez un message d'erreur semblable à celui-ci :

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.

Cause possible :

Par défaut, lorsque vous utilisez l'identité de l'agent avec Agent Runtime, des jetons d'accès liés à un certificat sont utilisés pour l'authentification afin d'empêcher le vol de jetons. Une erreur 401 peut se produire lors de l'exécution dans l'un des deux scénarios suivants :

1. Un utilisateur ou un agent tente d'utiliser un jeton d'accès en dehors du contexte dans lequel il a été émis, par exemple en transmettant le jeton entre des agents.
2. L'agent appelle un point de terminaison d'API non compatible avec mTLS, tel que telemetry.googleapis.com au lieu de telemetry.mtls.googleapis.com.

Solution recommandée :

Pour le scénario 1, si vous avez une raison légitime de partager des jetons entre les agents, vous pouvez désactiver la règle d'accès contextuel par défaut. Cette action est fortement déconseillée, car elle expose l'agent au vol d'identifiants.

Pour désactiver la règle CAA par défaut, définissez la variable d'environnement suivante lorsque vous créez votre instance Agent Runtime :

config={
  "env_vars": {
    "GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False,
  }
}

Pour le scénario 2, vous pouvez également définir la variable GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES sur False pour permettre aux agents d'utiliser les points de terminaison d'API non-mTLS comme solution de contournement temporaire. Dans ce cas, le problème sous-jacent peut être un problème connu avec ADK.