Soluciona problemas de implementación de un agente

En este documento, se describe cómo resolver los errores que puedes encontrar cuando implementas un agente en Agent Runtime. Se abarca una variedad de problemas habituales, como fallas de serialización, errores de permisos y violaciones de los límites de VPC-SC.

Nota: Para buscar y filtrar los registros de errores del agente, usa el Explorador de registros, selecciona RESOURCE TYPE en "Vertex AI Reasoning Engine" y selecciona el valor RESOURCE CONTAINER correspondiente (es decir, el número de proyecto) y el valor REASONING ENGINE ID.

Errores de compilación y de inicio del contenedor

Si la implementación falla mientras Agent Runtime compila o inicia el contenedor del agente, uno de los siguientes problemas podría ser la causa:

No se pudo compilar la imagen de contenedor

Problema:

Deployment falla con un estado 400, INVALID_ARGUMENT (REASONING_ENGINE_BUILD_FAILED) y un mensaje similar al siguiente:

The Reasoning Engine could not be deployed because its container image failed to build.

Causas posibles:

Cuando implementas un agente desde un objeto de agente, desde archivos de origen o desde un Dockerfile, Agent Runtime compila una imagen de contenedor para el agente. La compilación falla si uno de los siguientes pasos falla:

  • Instalación de los requisitos del paquete: No existe un paquete en requirements o el archivo de requisitos de tus archivos de origen, fija una versión que no existe, entra en conflicto con otro paquete o no admite la versión de Python del agente.
  • Instalación de un wheel local: Un archivo wheel que aparece en requirements tampoco se incluye en extra_packages, por lo que no está disponible para instalarlo.
  • Ejecución de secuencias de comandos de instalación: Una secuencia de comandos en el directorio installation_scripts sale con un error.
  • Compila tu Dockerfile: Cuando implementas desde un Dockerfile (image_spec), falla una instrucción en tu Dockerfile.

Soluciones recomendadas:

  • Verifica los registros de compilación vinculados en el campo logs_url de los metadatos de error para encontrar el paso que falló. Las entradas de registro de compilación incluyen el ID de registro reasoning_engine_build. Para consultar los registros, consulta Compila consultas.

  • Para reproducir la falla de forma local, instala los mismos requisitos en un entorno virtual nuevo que use la versión de Python del agente implementado y corrige los errores que informe pip:

    python -m venv agent-env
agent-env/bin/pip install -r requirements.txt

  • Para que la compilación instale las versiones que probaste de forma local, fija las versiones de tus paquetes. Consulta Define los requisitos del paquete.

  • Si instalas un wheel local, inclúyelo en requirements y extra_packages. Consulta Cómo definir paquetes adicionales.

  • Si usas secuencias de comandos de instalación, asegúrate de que cada una se cierre correctamente cuando se ejecute con permisos de administrador en un entorno limpio. Consulta Cómo definir opciones de compilación.

  • Si implementas desde un Dockerfile, compila la imagen de contenedor de forma local a partir de los mismos archivos de origen (por ejemplo, con docker build) y corrige cualquier instrucción que falle.

Soluciones que no se aplican:

  • Si vuelves a intentar la implementación sin cambiar los requisitos, las secuencias de comandos de instalación o el Dockerfile, se producirá el mismo error, ya que la compilación ejecuta los mismos pasos.

Se agotó el tiempo de espera para compilar la imagen de contenedor

Problema:

Deployment falla con un estado 504, DEADLINE_EXCEEDED (REASONING_ENGINE_BUILD_TIMEOUT) y un mensaje que indica que la imagen de contenedor del agente no terminó de compilarse a tiempo.

Causas posibles:

Cuando implementas desde archivos fuente, Agent Runtime compila una imagen de contenedor que instala tu código y sus dependencias. La implementación falla si la compilación aún se está ejecutando cuando se agota el tiempo permitido. Por lo general, las compilaciones tardan demasiado debido a las dependencias que instalan, por ejemplo:

  • Una lista larga de paquetes en requirements, incluidos los que el agente no usa.
  • Paquetes sin ruedas compiladas previamente para el entorno de compilación, que se compilan desde la fuente durante la compilación.
  • Versiones no fijadas o fijadas de forma imprecisa, que ralentizan la resolución de dependencias

Soluciones recomendadas:

  • Verifica los registros de compilación vinculados en el campo logs_url de los metadatos de error para ver qué paso se estaba ejecutando cuando se detuvo la compilación.
  • Quita las dependencias innecesarias y fija las versiones de todos los paquetes obligatorios.
  • Prioriza los paquetes y las versiones que publican wheels compilados previamente para que no se compile nada durante la compilación.
  • Vuelve a intentar la implementación. En ocasiones, una compilación puede tardar más de lo habitual por motivos no relacionados con tu código.

No se pudo iniciar el contenedor

Problema:

Deployment falla con un estado 400, INVALID_ARGUMENT (REASONING_ENGINE_CONTAINER_FAILED_TO_START) y un mensaje que indica que el contenedor del agente no comenzó a entregar dentro del tiempo de espera de inicio.

Causas posibles:

Agent Runtime inicia tu agente en un contenedor y espera a que acepte solicitudes. La implementación falla si el contenedor se cierra o no responde antes de que se agote el tiempo de espera de inicio. Entre las causas comunes, se incluyen las siguientes:

  • Falta una dependencia: Tu agente importa un paquete que no aparece en requirements ni en extra_packages, por lo que la carga del agente falla con un error como ModuleNotFoundError.
  • No coinciden las versiones de los paquetes: Los paquetes instalados en el entorno implementado difieren de los de tu entorno de desarrollo, por lo que la carga del agente falla con un error como AttributeError: Can't get attribute. Consulta Errores de serialización.
  • Error durante la inicialización: El método set_up() de tu agente o cualquier otro código que se ejecute cuando se cargue el agente genera una excepción o espera un recurso al que no puede acceder.
  • Inicialización lenta: La carga del agente tarda más que el tiempo de espera de inicio.
  • El contenedor personalizado no escucha: Un contenedor personalizado debe escuchar las solicitudes HTTP en 0.0.0.0 en el puerto 8080. Consulta el contrato del entorno de ejecución.

Soluciones recomendadas:

  • Verifica los registros del agente vinculados en el campo logs_url de los metadatos del error para encontrar el error que detuvo el contenedor. Consulta Visualiza los registros de un agente.
  • Agrega los paquetes que falten a requirements o extra_packages, y fija las versiones que usas en el desarrollo.
  • Para reproducir la falla de forma local, instala solo los paquetes que se indican en requirements en un entorno limpio con la misma versión de Python y, luego, importa y crea una instancia de tu agente.
  • Mueve el trabajo lento o propenso a fallas, como la conexión a servicios externos, fuera de la inicialización del agente.
  • En el caso de un contenedor personalizado, asegúrate de que el servidor escuche en 0.0.0.0 y en el puerto de la variable de entorno PORT (8080 de forma predeterminada).

Soluciones que no se aplican:

  • Si vuelves a intentar la implementación sin cambiar el agente o sus dependencias, suele fallar de la misma manera, ya que la causa está en el código del agente o en su entorno.

El contenedor no se inició a tiempo

Problema:

Deployment falla con un estado 504, DEADLINE_EXCEEDED (REASONING_ENGINE_CONTAINER_START_TIMEOUT) y un mensaje que indica que el contenedor del agente no comenzó a entregar a tiempo.

Causas posibles:

Una vez que se compila la imagen, Agent Runtime inicia el contenedor del agente y espera a que esté listo para entregar solicitudes. La implementación falla si el contenedor aún se está iniciando cuando se agota el tiempo permitido. Entre las causas comunes, se incluyen las siguientes:

  • Trabajo lento en el momento de la importación, como la carga de modelos o archivos grandes cuando se importan los módulos del agente.
  • Trabajo lento o de bloqueo en el método set_up() del agente, como llamadas de red que esperan un servicio inaccesible

Soluciones recomendadas:

  • Verifica los registros del contenedor vinculados en el campo logs_url de los metadatos del error para ver dónde se detuvo el inicio.
  • Mueve la inicialización costosa fuera del tiempo de importación del módulo y minimiza la cantidad de pasos en set_up() rápidamente. Difiere el trabajo que no sea necesario para entregar la primera solicitud.
  • Asegúrate de que se pueda acceder a cualquier servicio al que llame el agente durante el inicio y establece tiempos de espera en esas llamadas para que no puedan bloquear el inicio de forma indefinida.
  • Si los registros del contenedor muestran que el agente se inició con normalidad, vuelve a intentar la implementación. En ocasiones, el inicio puede tardar más de lo habitual por motivos que no se relacionan con tu código.

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 YYY 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 Agent Runtime.

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 implementas 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 YYY 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 Agent Platform (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 los Controles del servicio de VPC, es posible que uno de los siguientes problemas sea la causa:

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 que faltan reglas de entrada obligatorias en el perímetro de VPC-SC.

Solución recomendada:

Si usas Agent Platform en un entorno de VPC-SC, debes crear una regla de entrada en tu perímetro para permitir la entrada del agente de servicio de motor de razonamiento (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com) al servicio de storage.googleapis.com y al servicio de artifactregistry.googleapis.com.

Errores de la cuenta de servicio personalizada

Si tienes problemas con las cuentas de servicio, es posible que uno de los siguientes problemas sea la causa:

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 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 encuentres este error si la cuenta de servicio personalizada se encuentra en un proyecto diferente de aquel en el que implementas el agente y la política de la organización iam.disableCrossProjectServiceAccountUsage se aplica 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 el proyecto de tu cuenta de servicio tiene aplicada la política de la 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 suceder si la cuenta de servicio personalizada y tu agente se encuentran en proyectos diferentes y el agente de servicio de plataforma de IA de motor de razonamiento 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 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 del motor de razonamiento de la plataforma de IA debe estar ubicado en el mismo proyecto que usas para implementar tu agente. La vinculación de IAM del otorgamiento del rol debe estar en el proyecto en el que reside la cuenta de servicio personalizada.

Errores de recursos agotados

Si tu implementación falla con un estado 429, RESOURCE_EXHAUSTED, uno de los siguientes problemas podría ser la causa:

Se superó el límite de frecuencia o la cuota de la API

Problema:

Deployment falla con un estado Error 429 o RESOURCE_EXHAUSTED.

Causa posible:

El proyecto superó sus límites de frecuencia de la API o las cuotas de solicitudes simultáneas.

Soluciones recomendadas:

  • Implementa una estrategia de retirada exponencial y reintentos en las secuencias de comandos de implementación.
  • Verifica el uso actual en comparación con los límites en la Google Cloud página Cuotas de la "API de Agent Platform".
  • Reduce la frecuencia de las implementaciones simultáneas.

La región se encuentra temporalmente sin capacidad

Problema:

Deployment falla con un estado 429, RESOURCE_EXHAUSTED y un mensaje que indica que la región alcanzó temporalmente la capacidad máxima de memoria o CPU permitida.

Causa posible:

Las implementaciones de agentes en una región se basan en un grupo de capacidad de entrega que Agent Runtime administra en tu nombre y que comparten todos los clientes de esa región. Cuando se agota el grupo, las implementaciones nuevas en esa región fallan hasta que se libera capacidad.

Este límite no es una de las cuotas de tu proyecto. No aparece en la páginaGoogle Cloud Cuotas y no se puede aumentar solicitando un aumento de cuota.

Soluciones recomendadas:

  • Implementa en otra región admitida. Esta es la forma más rápida de desbloquear una implementación.
  • Vuelve a intentarlo más tarde. Una región con capacidad máxima es un problema temporal que suele resolverse por sí solo.
  • Solicita una cantidad menor de memoria o CPU para tu agente. Una implementación más pequeña puede caber en la capacidad restante.
  • Comunícate con el equipo de asistencia si las implementaciones en una región siguen fallando de esta manera. Aunque no podemos aumentar el límite, tus informes nos ayudan a dirigir la capacidad hacia donde se necesita.

Soluciones que no se aplican:

  • Borrar tus agentes existentes no libera capacidad para este límite, ya que tu proyecto no consume la capacidad por sí solo.
  • Solicitar un aumento de cuota no tiene efecto, ya que el límite no es una cuota del proyecto.

La cantidad máxima de instancias supera el límite regional

Problema:

Deployment falla con un estado 429, RESOURCE_EXHAUSTED y un mensaje que indica que spec.deployment_spec.max_instances supera la cantidad máxima de instancias admitidas para la CPU o la memoria solicitadas en el resource_limits de la región.

Causa posible:

Cuando implementas un agente, Agent Runtime multiplica spec.deployment_spec.max_instances por la cpu y la memory por instancia en spec.deployment_spec.resource_limits y verifica que la asignación máxima de este agente único se ajuste al límite regional del proyecto de entrega subyacente. Si no especificas max_instances, Agent Runtime aplica un valor predeterminado (como 200), que, en regiones con límites más bajos, puede superar la cantidad máxima de instancias admitidas cuando se multiplica por la cpu o memory configuradas por instancia.

Soluciones recomendadas:

  • Establece spec.deployment_spec.max_instances en el valor máximo que se muestra en el mensaje de error (o menos).
  • Reduce el valor de cpu o memory por instancia en spec.deployment_spec.resource_limits.
  • Implementa el agente en otra región admitida con un límite más alto.

Soluciones que no se aplican:

  • Solicitar un aumento de cuota en la página de cuotas de tu proyecto de Google Cloud no tiene ningún efecto, ya que este límite se aplica al proyecto de entrega administrado por Google, en lugar de tu proyecto.
  • Borrar otros agentes en tu proyecto o volver a intentarlo sin cambiar max_instances o resource_limits no resuelve este error, ya que la verificación evalúa la asignación máxima de la implementación única en comparación con un límite estático.

Errores de acceso a Secret Manager

Problema:

Deployment falla con un estado 400, INVALID_ARGUMENT (REASONING_ENGINE_SECRET_ACCESS_DENIED) y un mensaje similar al siguiente:

The Reasoning Engine could not access `projects/PROJECT_NUMBER/secrets/SECRET_ID/versions/VERSION_ID` referenced by `spec.deployment_spec.secret_env` (reason: FAILURE_REASON).

Causas posibles:

  • NOT_FOUND: El ID del secreto o el ID de la versión especificado en secret_env no existe en Secret Manager en el mismo proyecto que el agente implementado o contiene un error de ortografía.
  • DESTROYED o DISABLED: La versión del secreto a la que se hace referencia en Secret Manager está en un estado destruido o inhabilitado.
  • PERMISSION_DENIED: La cuenta de servicio que usa el agente no tiene el rol de descriptor de acceso a secretos de Secret Manager (roles/secretmanager.secretAccessor) en el secreto al que se hace referencia.

Soluciones recomendadas:

  • Para NOT_FOUND, DESTROYED o DISABLED:
    1. En la página de Secret Manager del proyecto en el que implementas el agente, verifica que cada SECRET_ID y VERSION_ID a los que se hace referencia en secret_env existan y estén en el estado Habilitado.
    2. Si se inhabilitó o destruyó una versión a la que se hace referencia, habilita una versión válida o actualiza secret_env para que haga referencia a una versión habilitada.
  • Para PERMISSION_DENIED: Otorga el rol de descriptor de acceso a los Secrets de Secret Manager (roles/secretmanager.secretAccessor) en el Secret (o el proyecto que contiene el Secret) a la cuenta de servicio que recupera el Secret:
    • Cuenta de servicio predeterminada: Otorga el rol al agente de servicio de la plataforma de IA Reasoning Engine (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com).
    • Cuenta de servicio personalizada: Otorga el rol a la cuenta de servicio personalizada configurada en el agente.

Recursos de asistencia

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