Soluciona problemas de implementación de un agente

En este documento, se muestra cómo resolver errores que pueden surgir al implementar un agente.

Errores de plantilla compilada previamente

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

Errores internos del servidor

Problema:

Recibes un mensaje de error similar al siguiente:

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

Lamentablemente, este es un error genérico para cualquier problema con el contenedor en el entorno de ejecución y la posible causa es uno de los tantos errores que pueden estar ocurriendo.

Causas posibles

  • Estado no sincronizado en LangchainAgent. Esto podría suceder si .set_up() se llamó en un LangchainAgent antes de implementar el agente.
  • Versiones de paquete incoherentes. Esto podría ocurrir si los paquetes instalados en el entorno de desarrollo son diferentes de los paquetes instalados en el entorno remoto en Vertex AI Agent Engine.

Soluciones recomendadas

  • Estado no sincronizado en LangchainAgent. Crea una instancia nueva de LangchainAgent o quita agent.set_up() del código antes de implementar el agente.
  • Las especificaciones del paquete no son coherentes. Consulta la sección sobre solución de errores de serialización.

Errores de serialización

En general, es importante asegurarse de que los entornos "local" y "remoto" estén sincronizados cuando se implementa el agente. Para garantizar esto, puedes especificar requirements= cuando implementes el agente.

Si tienes problemas con la serialización (errores relacionados con "pickle" o "pickling" son sinónimos de “serialización”), podría 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 suceder si tu paquete pydantic es anterior a la versión 2.6.4. Para verificar qué versión estás usando, ejecuta el siguiente comando en la terminal:

pip show pydantic

Solución recomendada:

Actualiza el paquete mediante la ejecución del siguiente comando en la terminal:

pip install pydantic --upgrade

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

pip show pydantic

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.

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 suceder si la versión de tu paquete cloudpickle es diferente en el entorno de desarrollo y el de implementación. Para comprobar qué versión usas en desarrollo, ejecuta el siguiente comando en la terminal:

pip show cloudpickle

Solución recomendada:

Implementa la misma versión de cloudpickle en ambos entornos, como tu entorno de desarrollo local y el agente implementado de forma remota. Para ello, especifica requirements= cuando implementes el agente.

Errores internos del servidor

Problema:

Recibes un mensaje de error similar al siguiente:

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

Causa posible:

Esto podría suceder si sys_version= es diferente del entorno de desarrollo cuando implementas el agente.

Solución recomendada:

Después de implementar el agente, considera quitar sys_version= de los argumentos de entrada. Si los problemas persisten, envía un informe de errores.

Errores del bucket de Cloud Storage

Si tienes problemas con el bucket de etapa de pruebas de Cloud Storage que se usa en el momento de la implementación para recopilar y subir tu agente, puede deberse a uno de los siguientes problemas:

Errores de permisos

Solución recomendada:

Si deseas usar un bucket preexistente, asegúrate de que la principal que está autenticada para usar Vertex AI (ya sea tú mismo o una cuenta de servicio) tenga acceso Storage Admin al bucket y otórgale permisos a la cuenta de servicio.

Como alternativa, puedes especificar un bucket nuevo cuando implementes el agente, y el SDK creará el bucket con los permisos necesarios.

Si los problemas persisten, envía un informe de errores.

No se creó el subdirectorio del bucket 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 realizar una copia en una carpeta que no existe).

Causa posible:

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

pip show google-cloud-aiplatform

Solución recomendada:

Actualiza el paquete mediante la ejecución del siguiente comando en la terminal:

pip install google-cloud-aiplatform --upgrade

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

pip show google-cloud-aiplatform

Si usas una instancia de notebook (por ejemplo, Jupyter, Colab o Workbench), quizás debas reiniciar tu entorno de ejecución antes de poder usar los paquetes actualizados.

Errores de incumplimiento de VPC-SC

Si tienes problemas con el VPC-SC, es posible que se deban 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.

o:

Request is prohibited by organization's policy.

Causa posible:

Es probable que esto se deba a la falta de reglas de entrada obligatorias en el perímetro de VPC-SC.

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) en el servicio storage.googleapis.com y el servicio artifactregistry.googleapis.com.

Errores de cuentas de servicio personalizadas

Si tienes problemas con las cuentas de servicio, es posible que se deban a uno de los siguientes motivos:

Actúa 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 hay varias cuentas de servicio personalizadas, un autor o implementador de agentes puede actuar como algunas de las cuentas de servicio. Si usas la cuenta de servicio incorrecta, este error es el comportamiento esperado.

Además, es posible que se produzca este error si la cuenta de servicio personalizada se encuentra en un proyecto diferente del proyecto en el que implementas el agente y la política de la organización iam.disableCrossProjectServiceAccountUsage está aplicada en el proyecto de la cuenta de servicio.

Consulta Cuenta de servicio personalizada entre proyectos para obtener la lista completa de las configuraciones necesarias para esta situación.

Solución recomendada:

Asegúrate de usar la cuenta de servicio prevista. Verifica si tienes el rol de Usuario de cuenta de servicio (roles/iam.serviceAccountUser) en esta cuenta de servicio. De lo contrario, pídele a tu administrador que te otorgue el rol en esta cuenta de servicio.

Si te encuentras en la situación de varios proyectos, verifica si tu proyecto de cuenta de servicio tiene aplicada la política de organización iam.disableCrossProjectServiceAccountUsage. Si es así, pídele al 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 Cuenta de servicio personalizada entre proyectos para obtener la lista completa de las configuraciones necesarias para esta situación.

Solución recomendada:

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

El agente de servicio de AI Platform Reasoning Engine debe estar ubicado en el mismo proyecto que usas para implementar tu agente. La vinculación de IAM del otorgamiento de roles debe estar en el proyecto en el que reside la cuenta de servicio personalizada.

Recursos de asistencia

Si el problema persiste, consulta nuestra guía de asistencia para obtener ayuda.