Solucionar problemas al implementar un agente

En este documento se explica cómo resolver los errores que pueden surgir al desplegar un agente.

Errores de plantillas predefinidas

Si tienes problemas con la plantilla LangchainAgent durante la implementación, puede deberse a uno de los problemas que se indican en esta sección.

Errores de servidor internos

Problema:

Recibes un mensaje de error similar al siguiente:

InternalServerError: 500 Revision XXX is not ready and cannot serve traffic.

Desafortunadamente, este error es genérico y se produce cuando hay algún problema con el contenedor en el tiempo de ejecución. La causa puede ser uno de los muchos errores que se pueden producir.

Causas posibles:

  • Estado sucio en LangchainAgent. Esto puede ocurrir si se llama a .set_up() en un LangchainAgent antes de desplegar el agente.
  • Versiones de paquetes no coherentes. Esto puede ocurrir si los paquetes instalados en el entorno de desarrollo son diferentes de los paquetes instalados en el entorno remoto de Vertex AI Agent Engine.

Soluciones recomendadas:

  • Estado sucio en LangchainAgent. Crea una instancia nueva de LangchainAgent o elimina agent.set_up() del código antes de implementar el agente.
  • Especificaciones de paquete incoherentes. Consulta la sección sobre cómo solucionar errores de serialización.

Errores de serialización

En general, es importante asegurarse de que los entornos "local" y "remoto" estén sincronizados al implementar el agente. Para ello, especifica requirements= al implementar el agente.

Si tienes problemas con la serialización (los errores relacionados con "pickle" o "pickling" son sinónimos de errores de serialización), puede deberse a uno de los problemas que se describen en esta sección.

Versión de Pydantic

Problema:

Recibes un mensaje de error similar al siguiente:

PicklingError: Can't pickle <cyfunction str_validator at 0x7ca030133d30>: it's
not the same object as pydantic.validators.str_validator

Causa posible:

Esto puede ocurrir si tu paquete pydantic es anterior a la versión 2.6.4. Para comprobar qué versión estás usando, ejecuta el siguiente comando en tu terminal:

pip show pydantic

Solución recomendada:

Actualiza el paquete ejecutando el siguiente comando en el terminal:

pip install pydantic --upgrade

Ejecuta el siguiente comando en tu terminal para comprobar que estás usando la versión 2.6.4 o una posterior:

pip show pydantic

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

Versión de Cloudpickle

Problema:

Recibes un mensaje de error similar al siguiente:

AttributeError: Can't get attribute '_class_setstate' on <module 'cloudpickle.cloudpickle'
from '/usr/local/lib/python3.10/site-packages/cloudpickle/cloudpickle.py'>

Causa posible:

Esto puede ocurrir si la versión de tu paquete cloudpickle es diferente en tu entorno de desarrollo y en tu entorno de implementación. Para comprobar qué versión estás usando en el desarrollo, ejecuta el siguiente comando en tu terminal:

pip show cloudpickle

Solución recomendada:

Despliega la misma versión de cloudpickle en ambos entornos, como tu entorno de desarrollo local y el agente desplegado de forma remota, especificando requirements= al desplegar el agente.

Errores de servidor internos

Problema:

Recibes un mensaje de error similar al siguiente:

InternalServerError: 500 Revision XXX is not ready and cannot serve traffic.

Causa posible:

Esto puede ocurrir si sys_version= es diferente del entorno de desarrollo al desplegar el agente.

Solución recomendada:

Después de implementar el agente, considera la posibilidad de eliminar sys_version= de los argumentos de entrada. Si sigues teniendo problemas, envía un informe de errores.

Errores de segmentos de Cloud Storage

Si tienes problemas con el bucket de almacenamiento provisional de Cloud Storage que se usa durante la implementación para recoger y subir tu agente, puede deberse a uno de los siguientes problemas:

Errores de permisos

Solución recomendada:

Si quieres usar un segmento ya creado, asegúrate de que la entidad de seguridad autenticada para usar Vertex AI (tú o una cuenta de servicio) tenga acceso Storage Admin al segmento y concede permisos a la cuenta de servicio.

También puede especificar un nuevo contenedor al desplegar el agente y el SDK creará el contenedor con los permisos necesarios.

Si sigues teniendo problemas, envía un informe de errores.

No se crea la subcarpeta del segmento de Cloud Storage

Problema:

Recibes un mensaje de error similar al siguiente:

NotFound: 404 Can not copy from \"gs://[LOCATION]-*/agent_engine/agent_engine.pkl\" to \"gs://*/code.pkl\", check if the source object and target bucket exist.

El error 404 se produce cuando el sistema intenta copiar en una carpeta que no existe.

Causa posible:

Es probable que se deba a un problema con la interpolación de cadenas en versiones de google-cloud-aiplatform anteriores a la 1.49.0. Este problema se ha solucionado en versiones posteriores. Para comprobar qué versión de google-cloud-aiplatform estás usando, ejecuta el siguiente comando en tu terminal:

pip show google-cloud-aiplatform

Solución recomendada:

Actualiza el paquete ejecutando el siguiente comando en el terminal:

pip install google-cloud-aiplatform --upgrade

Comprueba que estás usando la versión 1.49.0 o una posterior de google-cloud-aiplatform ejecutando el siguiente comando en tu terminal:

pip show google-cloud-aiplatform

Si usas una instancia de cuaderno (por ejemplo, Jupyter, Colab o Workbench), puede que tengas que reiniciar el entorno de ejecución para poder usar los paquetes actualizados.

Errores de infracción de VPC-SC

Si tienes problemas con VPC-SC, puede que se deba a uno de los siguientes motivos:

Errores de permisos

Problema:

Recibes un mensaje de error similar al siguiente:

Reasoning Engine instance REASONING_ENGINE_ID failed to start and cannot serve traffic.

También puedes hacerlo de esta otra forma, si lo prefieres:

Request is prohibited by organization's policy.

Causa posible:

Es probable que se deba a que faltan reglas de entrada obligatorias en el perímetro de los Controles de Servicio de VPC.

Solución recomendada:

Si usas Vertex AI Agent Engine en un entorno de VPC-SC, debes crear una regla de entrada en tu perímetro para permitir la entrada desde el agente de servicio de Reasoning Engine (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com) a los servicios storage.googleapis.com y artifactregistry.googleapis.com.

Errores de cuentas de servicio personalizadas

Si tienes problemas con las cuentas de servicio, puede que se deba a uno de los siguientes motivos:

Actuar como cuenta de servicio

Problema:

Recibes un mensaje de error similar al siguiente:

You do not have permission to act as service_account.

Causa posible:

Es posible que no tengas el permiso iam.serviceAccounts.actAs en la cuenta de servicio personalizada que se usa para la implementación. Ten en cuenta que, en un sistema multiagente en el que haya varias cuentas de servicio personalizadas, un autor o implementador de agentes puede actuar como algunas de las cuentas de servicio. Si estás usando la cuenta de servicio incorrecta, este error es el comportamiento esperado.

Además, puede aparecer este error si la cuenta de servicio personalizada se encuentra en un proyecto distinto de aquel en el que implementas el agente y la política de organización iam.disableCrossProjectServiceAccountUsage está aplicada en el proyecto de la cuenta de servicio.

Consulta la lista completa de configuraciones necesarias para este caso en Cuenta de servicio personalizada entre proyectos.

Solución recomendada:

Asegúrate de que estás usando la cuenta de servicio adecuada. Comprueba si tienes el rol Usuario de cuenta de servicio (roles/iam.serviceAccountUser) en esta cuenta de servicio. Si no es así, pide a tu administrador que te conceda el rol en esta cuenta de servicio.

Si te encuentras en el caso de uso entre proyectos, comprueba si el proyecto de tu cuenta de servicio tiene la política de organización iam.disableCrossProjectServiceAccountUsage aplicada. Si es así, pide a tu administrador que inhabilite la política.

Servidor de metadatos no disponible

Problema:

Recibes un mensaje de error similar al siguiente:

ServiceUnavailable: 503 Getting metadata from plugin failed with error

o

Compute Engine Metadata server unavailable due to : Could not fetch URI /computeMetadata/v1/instance/service-accounts/default/token

Causa posible:

Esto puede ocurrir si la cuenta de servicio personalizada y tu agente están en proyectos diferentes y el agente de servicio de AI Platform Reasoning Engine no tiene el permiso iam.serviceAccounts.getAccessToken en la cuenta de servicio personalizada.

Consulta la lista completa de configuraciones necesarias para este caso en Cuenta de servicio personalizada entre proyectos.

Solución recomendada:

Pídele a tu administrador que asigne el rol Creador de tokens de cuenta de servicio (roles/iam.serviceAccountTokenCreator) al agente de servicio de AI Platform Reasoning Engine del proyecto del agente en la cuenta de servicio personalizada.

El agente de servicio de AI Platform Reasoning Engine debe estar en el mismo proyecto que usas para implementar tu agente. El enlace de gestión de identidades y accesos de la concesión de roles debe estar en el proyecto en el que se encuentre la cuenta de servicio personalizada.

Recursos de asistencia

Si el problema sigue sin resolverse, consulta nuestra guía de asistencia para obtener ayuda.