Soluciona problemas relacionados con la configuración del entorno para Agent Runtime

En este documento, se describe cómo resolver errores que puedes encontrar cuando configuras un entorno para Agent Runtime. Se incluyen los pasos para solucionar problemas de importación de paquetes.

Errores al importar el SDK de Agent Platform

Si no puedes importar el SDK de Agent Platform para Python, es posible que se deba a uno de los siguientes problemas:

Versión desactualizada del SDK de Agent Platform para Python

Problema:

Recibes un mensaje de error similar al siguiente:

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

o

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

Causa posible:

Esto puede suceder si la versión de tu paquete google-cloud-aiplatform es anterior a 1.82.0 (para agent_engines) o 1.47.0 (para reasoning_engines). Para verificar la versión de tu paquete google-cloud-aiplatform, ejecuta el siguiente comando en la terminal:

pip show google-cloud-aiplatform

Solución recomendada:

Ejecuta el siguiente comando en la terminal para actualizar tu paquete google-cloud-aiplatform:

pip install google-cloud-aiplatform --upgrade

Ejecuta el siguiente comando para verificar que la versión actualizada sea 1.82.0 o posterior:

pip show google-cloud-aiplatform

Si estás en una instancia de notebook (por ejemplo, Jupyter, Colab o Workbench), es posible que debas reiniciar tu entorno de ejecución para usar los paquetes actualizados.

Errores de autorización 401

Problema:

Recibes un mensaje de error similar al siguiente:

Error Code: "401"
Error Details: "Context-Aware Access requirements are not met"

O

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.

Causa posible:

De forma predeterminada, cuando usas la identidad del agente con Agent Runtime, se usan tokens de acceso vinculados a certificados para la autenticación y evitar el robo de tokens. Se puede producir un error 401 en el entorno de ejecución en una de las siguientes situaciones:

1. El usuario o el agente intentan usar un token de acceso fuera del contexto en el que se emitió, como pasar el token entre agentes.
2. El agente llama a un extremo de API no compatible con mTLS, como telemetry.googleapis.com en lugar de telemetry.mtls.googleapis.com.

Solución recomendada:

Para el caso n.° 1, si tienes un motivo legítimo para compartir tokens entre agentes, puedes inhabilitar la política predeterminada de Acceso adaptado al contexto (CAA). Esta acción no es recomendable, ya que deja a un agente vulnerable al robo de credenciales.

Para inhabilitar la política predeterminada de CAA, configura la siguiente variable de entorno cuando crees tu instancia de Agent Runtime:

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

Para el caso n.° 2, puedes configurar la variable GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES en False para permitir que los agentes usen los extremos de API no mTLS como solución alternativa temporal. En este caso, el problema subyacente podría ser un problema conocido con ADK.