Résoudre les problèmes de déploiement d'un agent

Ce document explique comment résoudre les erreurs que vous pouvez rencontrer lors du déploiement d'un agent sur Agent Runtime. Il couvre divers problèmes courants, y compris les échecs de sérialisation, les erreurs d'autorisation et les violations de limites VPC-SC.

Remarque : Pour rechercher et filtrer les journaux d'erreurs de l'agent, utilisez l'explorateur de journaux, sélectionnez RESOURCE TYPE pour "Moteur de raisonnement Vertex AI", puis sélectionnez la valeur RESOURCE CONTAINER correspondante (c'est-à-dire le numéro de projet) et la valeur REASONING ENGINE ID.

Erreurs de compilation et de démarrage du conteneur

Si votre déploiement échoue pendant qu'Agent Runtime crée ou démarre le conteneur de l'agent, l'un des problèmes suivants peut en être la cause :

Échec de la compilation de l'image de conteneur

Problème :

Le déploiement échoue avec l'état 400, INVALID_ARGUMENT (REASONING_ENGINE_BUILD_FAILED) et un message semblable à celui-ci :

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

Causes possibles :

Lorsque vous déployez un agent à partir d'un objet d'agent, de fichiers sources ou d'un Dockerfile, Agent Runtime crée une image de conteneur pour l'agent. La compilation échoue si l'une des étapes suivantes échoue :

  • Installation des dépendances de package : un package dans requirements ou le fichier de dépendances de vos fichiers sources n'existe pas, épingle une version qui n'existe pas, est en conflit avec un autre package ou n'est pas compatible avec la version Python de l'agent.
  • Installation d'un fichier wheel local : un fichier wheel listé dans requirements n'est pas inclus dans extra_packages. Il n'est donc pas disponible pour l'installation.
  • Exécution des scripts d'installation : un script du répertoire installation_scripts se termine par une erreur.
  • Création de votre Dockerfile : lorsque vous effectuez un déploiement à partir d'un Dockerfile (image_spec), une instruction de votre Dockerfile échoue.

Solutions recommandées :

  • Consultez les journaux de compilation associés au champ logs_url des métadonnées d'erreur pour identifier l'étape qui a échoué. Les entrées de journal de compilation incluent l'ID de journal reasoning_engine_build. Pour interroger les journaux, consultez Créer des requêtes.
  • Pour reproduire l'échec localement, installez les mêmes exigences dans un nouvel environnement virtuel qui utilise la version Python de l'agent déployé, puis corrigez les erreurs signalées par pip :

    python -m venv agent-env
    agent-env/bin/pip install -r requirements.txt
  • Pour que la compilation installe les versions que vous avez testées localement, épinglez vos versions de package. Consultez Définir les exigences du package.

  • Si vous installez un wheel local, incluez-le à la fois dans requirements et extra_packages. Consultez Définir des packages supplémentaires.

  • Si vous utilisez des scripts d'installation, assurez-vous que chaque script se termine correctement lorsqu'il est exécuté avec des autorisations racine dans un environnement propre. Consultez Définir des options de compilation.

  • Si vous effectuez le déploiement à partir d'un Dockerfile, créez l'image de conteneur localement à partir des mêmes fichiers sources (par exemple, avec docker build) et corrigez les instructions qui échouent.

Solutions non applicables :

  • Si vous relancez le déploiement sans modifier les exigences, les scripts d'installation ou le fichier Dockerfile, l'échec se reproduit, car la compilation exécute les mêmes étapes.

La création de l'image de conteneur a expiré

Problème :

Le déploiement échoue avec l'état 504, DEADLINE_EXCEEDED (REASONING_ENGINE_BUILD_TIMEOUT) et un message indiquant que la création de l'image de conteneur de l'agent n'a pas été terminée à temps.

Causes possibles :

Lorsque vous déployez à partir de fichiers sources, Agent Runtime crée une image de conteneur qui installe votre code et ses dépendances. Le déploiement échoue si la compilation est toujours en cours d'exécution lorsque le temps imparti est écoulé. Les compilations prennent généralement trop de temps en raison des dépendances qu'elles installent, par exemple :

  • Une longue liste de packages dans requirements, y compris ceux que l'agent n'utilise pas.
  • Packages sans roues prédéfinies pour l'environnement de compilation, qui sont compilés à partir de la source pendant la compilation.
  • Versions non épinglées ou épinglées de manière lâche, ce qui ralentit la résolution des dépendances.

Solutions recommandées :

  • Consultez les journaux de compilation associés au champ logs_url des métadonnées d'erreur pour voir quelle étape était en cours d'exécution lorsque la compilation s'est arrêtée.
  • Supprimez les dépendances inutiles et épinglez les versions de tous les packages requis.
  • Donnez la priorité aux packages et aux versions qui publient des wheels prédéfinis, afin que rien ne soit compilé pendant la compilation.
  • Relancez le déploiement. Une compilation peut parfois prendre plus de temps que d'habitude pour des raisons sans rapport avec votre code.

Échec du démarrage du conteneur

Problème :

Le déploiement échoue avec l'état 400, INVALID_ARGUMENT (REASONING_ENGINE_CONTAINER_FAILED_TO_START) et un message indiquant que le conteneur de l'agent n'a pas commencé à diffuser dans le délai de démarrage.

Causes possibles :

Agent Runtime démarre votre agent dans un conteneur et attend qu'il accepte les requêtes. Le déploiement échoue si le conteneur se ferme ou ne répond pas avant l'expiration du délai de démarrage. Voici les causes les plus courantes :

  • Dépendance manquante : votre agent importe un package qui n'est pas listé dans requirements ou extra_packages. Par conséquent, le chargement de l'agent échoue avec une erreur telle que ModuleNotFoundError.
  • Incompatibilité de version de package : les packages installés dans l'environnement déployé diffèrent de ceux de votre environnement de développement. Par conséquent, le chargement de l'agent échoue avec une erreur telle que AttributeError: Can't get attribute. Consultez Erreurs de sérialisation.
  • Erreur lors de l'initialisation : la méthode set_up() de votre agent ou un autre code qui s'exécute lors du chargement de l'agent lève une exception ou attend une ressource qu'il ne peut pas atteindre.
  • Initialisation lente : le chargement de l'agent prend plus de temps que le délai avant expiration du démarrage.
  • Conteneur personnalisé n'écoutant pas : un conteneur personnalisé doit écouter les requêtes HTTP sur 0.0.0.0 sur le port 8080. Consultez le contrat d'exécution.
  • Agent Gateway bloque le démarrage : lorsque vous acheminez le trafic via Agent Gateway, le démarrage échoue si Identity-Aware Proxy (IAP) bloque les appels d'initialisation, si l'identité de l'agent ne dispose pas des rôles requis ou si un conteneur personnalisé ne fait pas confiance au certificat racine de la passerelle. Consultez Erreurs lors du démarrage d'Agent Runtime et Échec de la connexion de l'agent déployé avec un conteneur personnalisé (BYOC) à Agent Gateway.

Solutions recommandées :

  • Consultez les journaux de l'agent associés au champ logs_url des métadonnées d'erreur pour identifier l'erreur qui a arrêté le conteneur. Consultez Afficher les journaux d'un agent.
  • Ajoutez les packages manquants à requirements ou extra_packages, puis épinglez les versions que vous utilisez en développement.
  • Pour reproduire l'échec localement, n'installez que les packages listés dans requirements dans un environnement propre avec la même version de Python, puis importez et instanciez votre agent.
  • Déplacez les tâches lentes ou sujettes aux échecs, telles que la connexion à des services externes, en dehors de l'initialisation de l'agent.
  • Pour un conteneur personnalisé, assurez-vous que le serveur écoute sur 0.0.0.0 et sur le port de la variable d'environnement PORT (par défaut, 8080).

Solutions non applicables :

  • Si vous relancez le déploiement sans modifier l'agent ou ses dépendances, l'échec se reproduit généralement, car la cause se trouve dans le code de l'agent ou dans son environnement.

Le conteneur n'a pas démarré à temps

Problème :

Le déploiement échoue avec l'état 504, DEADLINE_EXCEEDED (REASONING_ENGINE_CONTAINER_START_TIMEOUT) et un message indiquant que le conteneur de l'agent n'a pas commencé à diffuser à temps.

Causes possibles :

Une fois l'image créée, Agent Runtime démarre le conteneur de l'agent et attend qu'il soit prêt à diffuser des requêtes. Le déploiement échoue si le conteneur est toujours en cours de démarrage lorsque le délai imparti est écoulé. Voici les causes les plus courantes :

  • Travail lent au moment de l'importation, comme le chargement de modèles ou de fichiers volumineux lorsque les modules de l'agent sont importés.
  • Travail lent ou bloquant dans la méthode set_up() de l'agent, comme les appels réseau qui attendent un service inaccessible.

Solutions recommandées :

  • Vérifiez les journaux du conteneur associés au champ logs_url des métadonnées d'erreur pour voir où le démarrage s'est arrêté.
  • Déplacez l'initialisation coûteuse en dehors du temps d'importation du module et réduisez le nombre d'étapes dans set_up(). Différez les tâches qui ne sont pas nécessaires pour répondre à la première requête.
  • Assurez-vous que tous les services appelés par l'agent au démarrage sont accessibles depuis l'agent, et définissez des délais avant expiration pour ces appels afin qu'ils ne puissent pas bloquer le démarrage indéfiniment.
  • Si les journaux du conteneur indiquent que l'agent a démarré normalement, relancez le déploiement. Le démarrage peut parfois prendre plus de temps que d'habitude pour des raisons sans rapport avec votre code.

Erreurs de modèle prédéfini

Si vous rencontrez des problèmes avec le modèle LangchainAgent lors du déploiement, cela peut être dû à l'un des problèmes décrits dans cette section.

Erreurs internes du serveur

Problème :

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

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

Malheureusement, il s'agit d'une erreur généralisée pour tout problème lié au conteneur au moment de l'exécution. La cause possible est l'une des nombreuses erreurs pouvant se produire.

Causes possibles :

  • État modifié sur LangchainAgent. Cela peut se produire si .set_up() a été appelé sur un LangchainAgent avant le déploiement de l'agent.
  • Versions de package incohérentes. Cela peut se produire si les packages installés dans l'environnement de développement sont différents de ceux installés dans l'environnement distant d'Agent Runtime.

Solutions recommandées :

  • État modifié sur LangchainAgent. Instanciez une nouvelle instance de LangchainAgent ou supprimez agent.set_up() du code avant de déployer l'agent.
  • Spécifications de package incohérentes. Consultez la section sur le dépannage des erreurs de sérialisation.

Erreurs de sérialisation

En général, il est important de s'assurer que les environnements "local" et "distant" sont synchronisés lors du déploiement de l'agent. Pour ce faire, spécifiez requirements= lorsque vous déployez l'agent.

Si vous rencontrez des problèmes de sérialisation (les erreurs liées au "pickle" ou au "pickling" sont synonymes d'erreurs de "sérialisation"), cela peut être dû à l'un des problèmes décrits dans cette section.

Version Pydantic

Problème :

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

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

Cause possible :

Cela peut se produire si votre package pydantic est antérieur à la version 2.6.4. Pour vérifier la version que vous utilisez, exécutez la commande suivante dans votre terminal :

pip show pydantic

Solution recommandée :

Mettez à jour votre package en exécutant la commande suivante dans le terminal :

pip install pydantic --upgrade

Exécutez la commande suivante dans votre terminal pour vérifier que vous utilisez la version 2.6.4 ou une version ultérieure :

pip show pydantic

Si vous êtes 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.

Version Cloudpickle

Problème :

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

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

Cause possible :

Cela peut se produire si la version de votre package cloudpickle est différente dans votre environnement de développement et votre environnement de déploiement. Pour vérifier quelle version vous utilisez en développement, exécutez la commande suivante dans votre terminal :

pip show cloudpickle

Solution recommandée :

Déployez la même version de cloudpickle dans les deux environnements, par exemple votre environnement de développement local et l'agent déployé à distance, en spécifiant requirements= lors du déploiement de l'agent.

Erreurs internes du serveur

Problème :

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

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

Cause possible :

Cela peut se produire si sys_version= est différent de l'environnement de développement lors du déploiement de l'agent.

Solution recommandée :

Après avoir déployé l'agent, envisagez de supprimer sys_version= des arguments d'entrée. Si le problème persiste, envoyez un rapport de bug.

Erreurs du bucket Cloud Storage

Si vous rencontrez des problèmes avec le bucket de préproduction Cloud Storage utilisé au moment du déploiement pour collecter et importer votre agent, cela peut être dû à l'une des raisons suivantes :

Erreurs liées aux autorisations

Solution recommandée :

Si vous souhaitez utiliser un bucket préexistant, assurez-vous que le compte principal authentifié pour utiliser Agent Platform (vous-même ou un compte de service) dispose d'un accès Storage Admin au bucket, et accordez des autorisations au compte de service.

Vous pouvez également spécifier un nouveau bucket lors du déploiement de l'agent afin que le SDK crée le bucket avec les autorisations nécessaires.

Si le problème persiste, envoyez un rapport de bug.

Le sous-répertoire du bucket Cloud Storage n'est pas créé

Problème :

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

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.

(L'erreur 404 se produit lorsque le système tente de copier dans un dossier qui n'existe pas.)

Cause possible :

Ce problème est probablement dû à un problème d'interpolation de chaîne dans les versions de google-cloud-aiplatform antérieures à la version 1.49.0. Ce problème est corrigé dans les versions ultérieures. Pour vérifier la version de google-cloud-aiplatform que vous utilisez, exécutez la commande suivante dans votre terminal :

pip show google-cloud-aiplatform

Solution recommandée :

Mettez à jour votre package en exécutant la commande suivante dans le terminal :

pip install google-cloud-aiplatform --upgrade

Vérifiez que vous utilisez la version 1.49.0 ou une version ultérieure de google-cloud-aiplatform en exécutant la commande suivante dans votre terminal :

pip show google-cloud-aiplatform

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

Erreurs de non-respect de VPC-SC

Si vous rencontrez des problèmes avec VPC-SC, l'un des problèmes suivants peut en être la cause :

Erreurs liées aux autorisations

Problème :

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

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

ou :

Request is prohibited by organization's policy.

Cause possible :

Cela est probablement dû à l'absence de règles d'entrée requises dans le périmètre VPC-SC.

Solution recommandée :

Si vous utilisez Agent Platform dans un environnement VPC-SC, vous devez créer une règle d'entrée dans votre périmètre pour autoriser l'entrée de l'agent de service Moteur de raisonnement (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com) dans le service storage.googleapis.com et le service artifactregistry.googleapis.com.

Erreurs liées aux comptes de service personnalisés

Si vous rencontrez des problèmes avec les comptes de service, l'un des problèmes suivants peut en être la cause :

Agir en tant que compte de service

Problème :

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

You do not have permission to act as service_account.

Cause possible :

Vous ne disposez peut-être pas de l'autorisation iam.serviceAccounts.actAs sur le compte de service personnalisé utilisé pour le déploiement. Notez que dans un système multi-agent comportant plusieurs comptes de service personnalisés, un auteur ou un déployeur d'agent peut agir en tant que certains des comptes de service. Si vous utilisez un compte de service incorrect, cette erreur est le comportement attendu.

De plus, vous pouvez rencontrer cette erreur si le compte de service personnalisé se trouve dans un projet différent de celui où vous déployez l'agent, et que la règle d'administration iam.disableCrossProjectServiceAccountUsage est appliquée dans le projet du compte de service.

Consultez Compte de service personnalisé multiprojet pour obtenir la liste complète des configurations requises pour ce scénario.

Solution recommandée :

Assurez-vous d'utiliser le compte de service prévu. Vérifiez si vous disposez du rôle Utilisateur du compte de service (roles/iam.serviceAccountUser) sur ce compte de service. Si ce n'est pas le cas, demandez à votre administrateur de vous attribuer le rôle sur ce compte de service.

Si vous êtes dans le scénario multiprojet, vérifiez si la règle d'administration iam.disableCrossProjectServiceAccountUsage est appliquée à votre projet de compte de service. Si c'est le cas, demandez à votre administrateur de désactiver la règle.

Serveur de métadonnées indisponible

Problème :

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

ServiceUnavailable: 503 Getting metadata from plugin failed with error

ou

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

Cause possible :

Cela peut se produire si le compte de service personnalisé et votre agent se trouvent dans des projets différents, et que l'agent de service Agent Platform (service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com) ne dispose pas de l'autorisation iam.serviceAccounts.getAccessToken sur le compte de service personnalisé.

Consultez Compte de service personnalisé multiprojet pour obtenir la liste complète des configurations requises pour ce scénario.

Solution recommandée :

Demandez à votre administrateur d'accorder à l'agent de service Agent Platform (service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com) du projet d'agent le rôle Créateur de jetons du compte de service (roles/iam.serviceAccountTokenCreator) sur le compte de service personnalisé.

L'agent de service Agent Platform doit se trouver dans le même projet que celui que vous utilisez pour déployer votre agent. La liaison IAM de l'attribution de rôle doit se trouver dans le projet où réside le compte de service personnalisé.

Échec du provisionnement de l'environnement

Problème :

La création d'un agent échoue avec l'état 500, INTERNAL (REASONING_ENGINE_PROVISIONING_FAILED) et un message indiquant que l'environnement géré par Google de l'agent n'a pas pu être provisionné.

Cause possible :

Avant qu'Agent Runtime ne déploie votre premier agent dans un projet et une région, il configure des ressources gérées par Google pour vos agents, telles que les agents de service et l'environnement d'hébergement. Si cette configuration échoue, toutes les créations d'agents en attente dans ce projet et cette région échouent avec cette erreur.

Solution recommandée :

Contactez l'assistance et indiquez le nom de l'opération ayant échoué au format projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID.

Solutions non applicables :

  • Réessayer de créer l'agent ne résout pas cette erreur, car Google doit d'abord corriger la configuration défaillante.
  • Modifier le code, les exigences ou le fichier resource_limits de votre agent ne sert à rien, car l'échec se produit avant qu'Agent Runtime ne déploie votre agent.
  • Demander une augmentation de quota pour votre projet n'a aucun effet, car Google gère ces ressources.

Erreurs d'épuisement des ressources

Si votre déploiement échoue avec l'état 429, RESOURCE_EXHAUSTED, l'un des problèmes suivants peut en être la cause :

Limite de débit ou quota d'API dépassé

Problème :

Le déploiement échoue avec l'état Error 429 ou RESOURCE_EXHAUSTED.

Cause possible :

Le projet a dépassé ses limites de débit d'API ou ses quotas de requêtes simultanées.

Solutions recommandées :

  • Implémentez une stratégie d'intervalle exponentiel entre les tentatives et de nouvelle tentative dans les scripts de déploiement.
  • Vérifiez l'utilisation actuelle par rapport aux limites sur la page Google Cloud Quotas de l'API Agent Platform.
  • Réduisez la fréquence des déploiements simultanés.

Capacité maximale temporairement atteinte dans la région

Problème :

Le déploiement échoue avec l'état 429, RESOURCE_EXHAUSTED et un message indiquant que la région a temporairement atteint sa capacité maximale pour une quantité totale de mémoire ou de processeur autorisée.

Cause possible :

Les déploiements d'agents dans une région s'appuient sur un pool de capacité de diffusion qu'Agent Runtime gère en votre nom et que tous les clients de cette région partagent. Lorsque le pool est épuisé, les nouveaux déploiements dans cette région échouent jusqu'à ce que de la capacité se libère.

Cette limite ne fait pas partie des quotas de votre projet. Il n'apparaît pas sur la page Google Cloud Quotas et ne peut pas être augmenté en demandant une augmentation de quota.

Solutions recommandées :

  • Déployez dans une autre région prise en charge. Il s'agit du moyen le plus rapide de débloquer un déploiement.
  • Vous devrez réessayer plus tard. Une région ayant atteint sa capacité maximale est un problème temporaire qui se résout généralement de lui-même.
  • Demandez une quantité de mémoire ou de processeur inférieure pour votre agent. Un déploiement plus petit peut s'adapter à la capacité restante.
  • Contactez l'assistance si les déploiements dans une région continuent d'échouer de cette manière. Bien que nous ne puissions pas augmenter la limite, vos rapports nous aident à orienter la capacité là où elle est nécessaire.

Solutions non applicables :

  • La suppression de vos agents existants ne libère pas de capacité pour cette limite, car la capacité n'est pas consommée uniquement par votre projet.
  • Demander une augmentation de quota n'a aucun effet, car la limite n'est pas un quota de projet.

Le nombre maximal d'instances dépasse la limite régionale

Problème :

Le déploiement échoue avec l'état 429, RESOURCE_EXHAUSTED et un message indiquant que spec.deployment_spec.max_instances dépasse le nombre maximal d'instances compatibles pour le processeur ou la mémoire demandés dans le resource_limits de la région.

Cause possible :

Lorsque vous déployez un agent, Agent Runtime multiplie spec.deployment_spec.max_instances par les valeurs cpu et memory par instance dans spec.deployment_spec.resource_limits, et vérifie que l'allocation maximale de cet agent unique respecte la limite régionale du projet de diffusion sous-jacent. Si vous ne spécifiez pas max_instances, Agent Runtime applique une valeur par défaut (telle que 200), qui, dans les régions où les limites sont plus basses, peut dépasser le nombre maximal d'instances acceptées lorsqu'elle est multipliée par la valeur cpu ou memory configurée par instance.

Solutions recommandées :

  • Définissez spec.deployment_spec.max_instances sur la valeur maximale indiquée dans le message d'erreur (ou moins).
  • Réduisez la valeur cpu ou memory par instance dans spec.deployment_spec.resource_limits.
  • Déployez l'agent dans une autre région prise en charge avec une limite plus élevée.

Solutions non applicables :

  • Demander une augmentation de quota sur la page Google Cloud Quotas de votre projet n'a aucun effet, car cette limite est appliquée au projet de diffusion géré par Google, et non à votre projet.
  • La suppression d'autres agents de votre projet ou une nouvelle tentative sans modifier max_instances ou resource_limits ne résout pas cette erreur, car la vérification évalue l'allocation maximale du déploiement unique par rapport à une limite statique.

La recherche Agent Gateway a été limitée

Problème :

Le déploiement ou la mise à jour d'un agent qui utilise un Agent Gateway échoue avec l'état 429, RESOURCE_EXHAUSTED (REASONING_ENGINE_AGENT_GATEWAY_LOOKUP_THROTTLED) et un message semblable à celui-ci :

The Reasoning Engine could not be created or updated because the request to look up Agent Gateway `projects/PROJECT_NUMBER/locations/LOCATION/agentGateways/AGENT_GATEWAY_ID` was throttled. Wait about a minute, then try again.

Cause possible :

Avant le début d'un déploiement ou d'une mise à jour, Agent Runtime recherche chaque Agent Gateway dans le spec.deployment_spec.agent_gateway_config de l'agent pour valider la requête. Cette erreur signifie que la recherche est temporairement limitée en débit. La requête est rejetée avant le début du déploiement ou de la mise à jour. Votre agent n'est donc pas créé ni modifié.

Solutions recommandées :

  • Attendez environ une minute, puis réessayez de déployer ou de mettre à jour.
  • Dans les workflows automatisés, relancez la requête avec un intervalle exponentiel entre les tentatives.
  • Contactez l'assistance si l'erreur persiste.

Solutions non applicables :

  • Modifier le code, requirements ou resource_limits de votre agent ne résout pas cette erreur. De plus, l'examen des journaux de trafic du conteneur ou d'Agent Gateway n'affiche aucune erreur, car la requête est rejetée avant qu'Agent Runtime ne crée ou ne démarre le conteneur de votre agent.

Erreurs d'accès à Secret Manager

Problème :

Le déploiement échoue avec l'état 400, INVALID_ARGUMENT (REASONING_ENGINE_SECRET_ACCESS_DENIED) et un message semblable à celui-ci :

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).

Causes possibles :

  • NOT_FOUND : l'ID de secret ou l'ID de version spécifié dans secret_env n'existe pas dans Secret Manager dans le même projet que l'agent déployé, ou contient une faute de frappe.
  • DESTROYED ou DISABLED : la version du secret référencée dans Secret Manager est détruite ou désactivée.
  • PERMISSION_DENIED : lors d'un déploiement basé sur un compte de service (service_account personnalisé ou agent de service AI Platform Reasoning Engine par défaut), le compte de service configuré ne dispose pas du rôle d'accesseur de secrets Secret Manager (roles/secretmanager.secretAccessor) sur le secret référencé lors de la validation du déploiement.

Solutions recommandées :

  • Pour NOT_FOUND, DESTROYED ou DISABLED :
    1. Sur la page Secret Manager du projet dans lequel vous déployez l'agent, vérifiez que chaque SECRET_ID et VERSION_ID référencé dans secret_env existe et est à l'état Activé.
    2. Si une version référencée a été désactivée ou détruite, activez une version valide ou mettez à jour secret_env pour référencer une version activée.
  • Pour PERMISSION_DENIED : suivez les instructions de la section Gérer l'accès aux secrets pour attribuer le rôle Accesseur de secrets Secret Manager (roles/secretmanager.secretAccessor) sur le secret spécifique au compte de service personnalisé dédié configuré sur l'agent (ou passez à une identité d'agent isolée).

Échec du démarrage du conteneur lors de l'utilisation de secret_env avec AGENT_IDENTITY

Problème :

Un agent configuré avec identity_type = AGENT_IDENTITY et secret_env échoue ou expire lors du démarrage du conteneur (au lieu de renvoyer REASONING_ENGINE_SECRET_ACCESS_DENIED lors de la validation du déploiement).

Causes possibles :

Pour les déploiements AGENT_IDENTITY, Agent Runtime ignore la validation de l'accès aux secrets au moment du déploiement et récupère les secrets référencés au démarrage du conteneur. Si vous transmettez secret_env lors de la création initiale (avant que l'identité de l'agent provisionné n'existe et n'ait obtenu l'accès), si l'identité de l'agent provisionné ne dispose pas de roles/secretmanager.secretAccessor sur un secret référencé, ou si une version de secret référencée est manquante (NOT_FOUND), désactivée (DISABLED) ou détruite (DESTROYED), le démarrage du conteneur échoue à plusieurs reprises lors de la récupération du secret.

Solutions recommandées :

  1. Créez d'abord l'agent avec AGENT_IDENTITY sans secret_env.
  2. Suivez la procédure Gérer l'accès aux secrets pour accorder roles/secretmanager.secretAccessor sur le secret spécifique à l'identité d'agent provisionnée de l'agent (ajoutez principal:// à spec.effective_identity lorsque vous spécifiez le membre IAM, par exemple --member="principal://EFFECTIVE_IDENTITY").
  3. Vérifiez que chaque version de secret référencée existe et est activée, puis mettez à jour l'agent pour associer secret_env. Limitez les autorisations aiplatform.reasoningEngines.update sur l'agent afin que seuls les comptes principaux autorisés puissent modifier le code exécuté en tant qu'identité.

Erreurs de liaison Agent Gateway

Si vous acheminez le trafic via Agent Gateway et que le déploiement ou la mise à jour de votre agent échoue avant son démarrage, l'un des problèmes suivants peut en être la cause :

Le délai de liaison de l'Agent Gateway a expiré

Problème :

Le déploiement ou la mise à jour d'un agent échoue avec l'état 504, DEADLINE_EXCEEDED (REASONING_ENGINE_AGENT_GATEWAY_PROVISION_TIMEOUT) et un message semblable à celui-ci :

The Reasoning Engine timed out waiting for an in-progress operation on shared Agent Gateway `projects/PROJECT_NUMBER/locations/LOCATION/agentGateways/AGENT_GATEWAY_ID` to finish. Wait for the other operation to complete, then try again.

Causes possibles :

Les agents Agent Runtime d'un même projet et d'une même région partagent une liaison avec chaque Agent Gateway configuré. La configuration ou la suppression de la liaison partagée peut prendre plusieurs minutes de plus que l'association d'un agent à une liaison active. Votre déploiement ou votre mise à jour expire si une autre opération de liaison ou de dissociation dans le même projet et la même région ne se termine pas dans le délai imparti. Voici les causes les plus courantes :

  • Liaisons initiales simultanées : vous liez plusieurs agents à une passerelle d'agent dans le même projet et la même région avant la fin de la configuration partagée initiale.
  • Dissociation en cours : vous dissociez ou supprimez le dernier agent lié à la passerelle dans le projet et la région, puis vous liez un autre agent à la même passerelle ou à une autre avant la fin du démontage partagé.
  • Réessayer après un échec de liaison : un déploiement ou une mise à jour qui lie une passerelle échoue, et vous réessayez avant qu'Agent Runtime ait terminé de nettoyer la configuration ayant échoué.

Solutions recommandées :

  • Attendez quelques minutes que les autres opérations sur la passerelle nommée dans l'erreur se terminent, puis réessayez le déploiement ou la mise à jour.
  • Pour lier plusieurs agents dans un projet et une région sans liaison Agent Gateway active, liez d'abord un agent et attendez que l'opération aboutisse. Ensuite, déployez ou mettez à jour les agents restants simultanément.
  • Dans les workflows automatisés, évitez de dissocier ou de supprimer le dernier agent lié à la passerelle dans un projet et une région juste avant de lier d'autres agents. La suppression du dernier agent lié à la passerelle supprime la liaison partagée. Le déploiement suivant répète donc la configuration complète.

Solutions non applicables :

  • La vérification des journaux de conteneur ou des journaux de trafic d'Agent Gateway n'affiche pas d'erreur pour cet échec, car le délai avant expiration se produit avant qu'Agent Runtime ne démarre le conteneur de votre agent.
  • La modification du code, de requirements ou de resource_limits de votre agent ne réduit pas le temps de configuration de la liaison partagée.

Si la liaison de la passerelle réussit, mais que le conteneur ne démarre pas, consultez Erreurs lors du démarrage d'Agent Runtime.

Liaison de l'Agent Gateway abandonnée

Problème :

Le déploiement ou la mise à jour d'un agent échoue avec l'état 409, ABORTED (REASONING_ENGINE_AGENT_GATEWAY_CONCURRENT_PROVISION_ABORTED) et un message semblable à celui-ci :

The Reasoning Engine could not be bound to Agent Gateway `projects/PROJECT_NUMBER/locations/LOCATION/agentGateways/AGENT_GATEWAY_ID` because a concurrent shared gateway provisioning operation failed and rolled back. Try again.

Cause possible :

Les agents Agent Runtime d'un même projet et d'une même région partagent une liaison avec chaque Agent Gateway configuré. Lorsque vous associez plusieurs agents à la même passerelle avant que sa liaison partagée ne soit configurée, un déploiement ou une mise à jour configure la liaison, et les autres attendent qu'elle soit configurée. Si ce déploiement ou cette mise à jour échoue avant que la liaison ne soit prête, Agent Runtime annule la liaison, et chaque déploiement ou mise à jour en attente échoue avec cette erreur. Le déploiement ou la mise à jour qui a configuré la liaison signale sa propre erreur, qui n'est peut-être pas liée à Agent Gateway.

Solutions recommandées :

Solutions non applicables :

  • La vérification des journaux de conteneur ou des journaux de trafic d'Agent Gateway n'affiche pas d'erreur pour cet échec, car il se produit avant qu'Agent Runtime ne démarre le conteneur de votre agent.
  • Modifier le code, le requirements ou le resource_limits de votre agent ne résoudra pas le problème, car cette erreur est due à un autre déploiement ou à une autre mise à jour, et non à votre agent.

Liaison Agent Gateway temporairement indisponible

Problème :

Le déploiement ou la mise à jour d'un agent échoue avec l'état 503, UNAVAILABLE (REASONING_ENGINE_AGENT_GATEWAY_PROVISION_UNAVAILABLE) et un message semblable à celui-ci :

The Reasoning Engine could not be bound to Agent Gateway `projects/PROJECT_NUMBER/locations/LOCATION/agentGateways/AGENT_GATEWAY_ID` because network provisioning encountered a transient upstream service error. Try again.

Cause possible :

Lorsque le premier agent d'un projet et d'une région se lie à une Agent Gateway, Agent Runtime configure des ressources réseau partagées gérées par Google qui connectent les agents à la passerelle. Si un service Google Clouddont dépend cette configuration continue de renvoyer des erreurs temporaires après plusieurs tentatives automatiques, Agent Runtime effectue un rollback de la configuration, et le déploiement ou la mise à jour échoue avec cette erreur. Les autres déploiements ou mises à jour en attente de la même configuration échouent avec l'état 409, ABORTED. Consultez Liaison de la passerelle d'agent abandonnée.

Solutions recommandées :

  • Attendez au moins 10 minutes que l'Agent Runtime termine le rollback de la configuration ayant échoué, puis réessayez le déploiement ou la mise à jour. Une nouvelle tentative qui démarre avant la fin du rollback peut échouer avec l'état 504, DEADLINE_EXCEEDED. Consultez Expiration de la liaison de l'Agent Gateway.
  • Si l'erreur persiste après plusieurs tentatives, contactez l'assistance et indiquez le nom de l'opération ayant échoué au format projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID.

Solutions non applicables :

  • Modifier le code de votre agent, requirements ou resource_limits ne résoudra pas le problème, car l'échec se produit avant qu'Agent Runtime ne déploie votre agent.
  • Demander une augmentation de quota pour votre projet n'a aucun effet, car Google gère ces ressources réseau.

Ressources d'assistance

Si le problème persiste, consultez notre guide d'assistance pour obtenir de l'aide.