Résoudre les problèmes liés au registre d'agents

Lorsque vous enregistrez, découvrez ou connectez des composants dans Agent Registry, vous pouvez diagnostiquer et résoudre les problèmes courants tels que les limites de quota, les erreurs de validation de la charge utile et des compétences, les incohérences d'emplacement, les retards de synchronisation et les erreurs d'autorisation.

Quota de débit d'API dépassé

L'erreur suivante se produit si vous dépassez la limite de taux de requêtes lorsque vous interagissez avec l'API Agent Registry ou que vous parcourez rapidement Agent Registry dans la consoleGoogle Cloud  :

429 Too Many Requests

Pour résoudre ce problème, implémentez un intervalle exponentiel entre les tentatives dans vos clients API afin de gérer les taux de demandes. L'API Agent Registry dispose de quotas de débit par défaut de requêtes par minute et par emplacement qui s'appliquent à vos ressources Agent Registry.

Si vous rencontrez des problèmes de limitation lorsque vous changez d'onglet dans la console Google Cloud , attendez quelques instants, puis réessayez. Si votre cas d'utilisation programmatique nécessite des limites plus élevées, demandez une augmentation de quota pour la métrique RequestsPerMinute.

Erreur de taille de charge utile lors de l'enregistrement manuel

L'erreur suivante se produit lorsque vous enregistrez manuellement un agent ou un serveur MCP avec un fichier de spécification qui dépasse la limite de taille :

L'API rejette la requête avec une erreur indiquant que la charge utile est trop volumineuse.

Pour résoudre ce problème, vérifiez que votre fichier agent-card.json ou toolspec.json fait moins de 10 Ko. La taille des contenus AgentSpec et McpServerSpec est limitée à 10 Ko. Minimisez vos fichiers JSON, supprimez les espaces inutiles ou condensez les descriptions des outils pour respecter cette limite. Pour en savoir plus, consultez Schémas JSON.

Agents ou serveurs MCP manquants après la création

L'erreur suivante se produit après la création d'un agent ou d'un serveur MCP dans un produit Google Cloud compatible, tel que Google Workspace ou Gemini Enterprise :

La ressource n'apparaît pas dans le résultat lorsque vous appelez les API ListAgents ou ListMcpServers.

Pour résoudre ce problème, attendez que la synchronisation en arrière-plan soit terminée. Vos ressources sont mises à jour en temps réel, mais des jobs par lot hors connexion périodiques alimentent d'autres intégrations. Si votre ressource n'apparaît pas après plusieurs heures, vérifiez les paramètres Service Usage de votre projet et assurez-vous que l'API appropriée est activée.

Les opérations de longue durée semblent bloquées

L'erreur suivante se produit lorsque vous déployez des agents ou configurez des liaisons complexes :

L'opération prend beaucoup de temps et semble bloquée.

Pour résoudre ce problème, utilisez l'outil MCP get_operation ou le point de terminaison de l'API google.longrunning.Operations.GetOperation pour interroger l'état de l'opération. La création de certains backends d'agent et de MCP nécessite un provisionnement d'infrastructure important, ce qui peut entraîner des opération de longue durée (LRO) pouvant prendre jusqu'à 30 minutes. Configurez les paramètres de délai avant expiration de votre client en conséquence et interrogez l'indicateur booléen done pour vérifier que l'opération est terminée.

Résultats vides lors de la récupération des liaisons disponibles

L'erreur suivante se produit si vous récupérez les liaisons disponibles pour un fournisseur d'authentification sans disposer des autorisations suffisantes sur la ressource AuthProvider cible :

L'API renvoie un tableau vide ou une erreur d'accès, même si la liaison existe.

Pour résoudre ce problème, vérifiez que votre compte principal dispose des autorisations IAM (Identity and Access Management) appropriées sur la ressource AuthProvider cible. L'API applique des vérifications IAM strictes et supprime les objets Binding qui font référence à des fournisseurs d'authentification auxquels l'appelant n'a pas accès. Assurez-vous que votre compte principal dispose de l'accès requis sur le fournisseur d'authentification et du rôle roles/agentregistry.viewer sur le projet.

Échec du téléchargement de la révision de la compétence avec l'erreur 302

L'erreur suivante se produit si vous essayez de télécharger une charge utile de révision de compétence à l'aide de l'API GetSkillRevision avec le paramètre de requête ?alt=media et que votre client HTTP ne suit pas les redirections :

{
  "error": {
    "code": 302,
    "message": "Unknown Error.",
    "status": "UNKNOWN"
  }
}

Pour résoudre ce problème, vérifiez que votre client HTTP est configuré pour suivre automatiquement les redirections. Le point de terminaison ?alt=media nécessite une redirection 302 pour télécharger l'archive de la compétence. Par exemple, si vous utilisez curl, ajoutez l'option -L ou --location à votre commande.

La validation de la révision de la compétence échoue ou affiche l'état FAILED

L'erreur suivante se produit lorsque vous créez une révision de compétence avec une archive ZIP non valide :

La révision passe à l'état FAILED et ne peut pas être chargée par les agents.

Pour résoudre ce problème, vérifiez les journaux de validation ou inspectez le contenu de la charge utile ZIP :

  • Assurez-vous que l'archive ZIP contient un fichier SKILL.md à la racine.
  • Vérifiez que le fichier SKILL.md comporte un bloc d'en-tête YAML valide avec name et description définis.
  • Vérifiez que la charge utile ZIP ne dépasse pas les limites de taille : la taille compressée doit être inférieure à 1 Mo, la taille totale non compressée doit être inférieure à 10 Mo et la taille de chaque fichier doit être inférieure à 1 Mo.
  • Vérifiez que l'archive ne contient pas de liens symboliques, d'éléments de traversée de répertoire tels que .. ou de chemins absolus.

Les compétences autonomes n'apparaissent pas dans les listes de ressources de service ou d'agent

L'erreur suivante se produit si vous interrogez les listes d'agents ou de services pour des compétences autonomes, par exemple en exécutant gcloud agent-registry services list ou gcloud agent-registry agents list :

La compétence autonome n'apparaît pas dans le résultat.

Pour résoudre ce problème, interrogez plutôt la collection skills :

  • Contrairement aux agents, aux serveurs MCP et aux points de terminaison enregistrés manuellement, les compétences autonomes n'utilisent pas de ressources Service accessibles en écriture ni de ressources de découverte Agent, McpServer ou Endpoint. À la place, Agent Registry représente les compétences autonomes directement en tant que ressources Skill de premier niveau et ressources SkillRevision avec gestion des versions.
  • Pour lister, rechercher ou inspecter des compétences autonomes, utilisez l'onglet Compétences de la consoleGoogle Cloud , exécutez gcloud agent-registry skills list ou gcloud agent-registry skills search, ou appelez les méthodes de l'API REST skills. Pour obtenir des instructions, consultez Gérer les compétences et Rechercher des compétences autonomes.
  • Si vous recherchez des compétences A2A intégrées déclarées dans la fiche d'un agent, inspectez le champ skills de la ressource de découverte Agent à l'aide de gcloud agent-registry agents describe ou gcloud agent-registry agents search.

Erreur "Entité de ressource introuvable" lors de la gestion des règles IAP

L'erreur suivante se produit lorsque vous utilisez des commandes gcloud iap web pour gérer les règles de sortie Identity-Aware Proxy (IAP) sur les ressources Agent Registry :

NOT_FOUND: Requested entity was not found

Pour résoudre ce problème, vérifiez les points suivants :

  • État d'enregistrement : vérifiez que le composant cible est enregistré dans Agent Registry à l'emplacement attendu.
  • Format de l'identifiant : vérifiez que votre commande ou votre liaison de stratégie spécifie le nom de ressource standard plutôt qu'un URN d'identifiant de registre.
  • Option de ressource : vérifiez que l'option de ressource que vous transmettez à gcloud iap web correspond au type de ressource enfant du registre d'agents sous-jacent :
    • Pour les points de terminaison, tels que les API externes ou les points de sortie des Google APIs, utilisez l'option --endpoint.
    • Pour les serveurs MCP (Model Context Protocol), utilisez l'option --mcp-server.
    • Pour les agents enregistrés, utilisez l'option --agent.

Vérifiez le nom de la ressource renvoyé par gcloud agent-registry endpoints list, gcloud agent-registry mcp-servers list ou gcloud agent-registry agents list pour confirmer si le nom de la ressource contient /endpoints/, /mcpServers/ ou /agents/. Si vous transmettez un flag de ressource incorrect, par exemple --endpoint pour un ID de serveur MCP, une erreur NOT_FOUND se produit.

Autorisation refusée lors de l'application des stratégies IAM Web IAP

L'erreur suivante se produit lorsque vous appliquez ou modifiez des stratégies IAM Web IAP pour les ressources du registre d'agents sans disposer des rôles d'administrateur requis :

ERROR: (gcloud.iap.web.set-iam-policy) PERMISSION_DENIED

Pour résoudre ce problème, vérifiez que votre utilisateur ou compte de service actif dispose des autorisations requises sur le projet hébergeant le registre et la passerelle :

  • Assurez-vous que l'appelant dispose du rôle Administrateur de règles IAP (roles/iap.admin) ou Administrateur IAM de projet (roles/resourcemanager.projectIamAdmin) sur le projet de gouvernance central.
  • Vérifiez que l'appelant dispose des autorisations iap.web.setIamPolicy et resourcemanager.projects.setIamPolicy.

Serveur MCP distant introuvable dans un emplacement régional

L'erreur suivante se produit si vous interrogez un serveur MCP distant Google ou Google Cloud enregistré automatiquement, ou si vous lui appliquez une règle de sortie IAP, dans un emplacement régional tel que us-central1 :

La requête renvoie une erreur NOT_FOUND ou une liste vide, même lorsque le service fournit des points de terminaison régionaux (REP) ou lorsque le trafic est acheminé via une Agent Gateway régionale.

Lorsque Agent Registry enregistre automatiquement un serveur MCP Google ouGoogle Cloud distant pour une API activée, il crée la ressource McpServer uniquement dans l'emplacement global, et non dans des régions individuelles telles que us-central1. Si le service fournit des points de terminaison régionaux, tels que https://SERVICE.REGION.rep.googleapis.com/mcp, Agent Registry liste ces URL régionales dans le champ interfaces de cette ressource global McpServer unique.

Pour résoudre ce problème, effectuez l'une des opérations suivantes :

  • Utilisez global pour les serveurs enregistrés automatiquement : spécifiez l'emplacement global lorsque vous interrogez le serveur dans Agent Registry avec --location=global ou que vous lui appliquez des règles de sortie IAP avec --region=global, même lorsque l'agent appelant achemine le trafic via une passerelle régionale.
  • Enregistrer dans une région pour la résidence des données : si vous devez conserver les métadonnées du registre dans une région spécifique, déployez des serveurs MCP personnalisés sur des environnements d'exécution régionaux Cloud Run ou Google Kubernetes Engine (GKE), ou enregistrez manuellement le serveur MCP et l'URL de son point de terminaison régional dans cette région, puis appliquez votre stratégie IAP dans cette même région. Lorsqu'Agent Gateway résout une URL cible, les entrées de registre régionales sont prioritaires sur les entrées global.

Erreurs de non-concordance de région lors de la configuration de Model Armor sur Agent Gateway

L'erreur suivante se produit lorsque vous configurez des filtres de stratégie Model Armor sur Agent Gateway dans des régions incompatibles :

La création de la stratégie d'autorisation échoue avec une erreur d'incompatibilité de région, ou le trafic acheminé via la passerelle vers un serveur MCP échoue à l'évaluation de la stratégie.

Pour résoudre ce problème, vérifiez l'alignement régional de vos ressources de passerelle et des liaisons de règles cibles :

  • Aligner les régions de la passerelle et de Model Armor : assurez-vous que l'Agent Gateway, les modèles Model Armor, l'extension d'autorisation et la stratégie se trouvent tous dans la même région, par exemple us-central1.
  • Acheminer vers des serveurs MCP global ou régionaux : vous n'avez pas besoin de réenregistrer les serveurs MCP global dans une région uniquement pour utiliser Model Armor. Comme Model Armor inspecte les charges utiles des requêtes et des réponses au niveau de la passerelle régionale, une passerelle régionale peut inspecter et gérer le trafic acheminé vers les serveurs MCP enregistrés dans l'emplacement global ainsi que vers les destinations régionales.
  • Faire correspondre les liaisons de sortie IAP à l'emplacement d'enregistrement de la cible : appliquez la liaison d'autorisation de sortie IAP à l'emplacement où la ressource McpServer cible est enregistrée. Utilisez global pour les serveurs MCP distants enregistrés automatiquement, ou utilisez la région spécifique pour les serveurs MCP enregistrés au niveau régional.

Échecs lors de l'accès à Agent Registry avec la fédération des identités des employés

Les erreurs suivantes se produisent si vous accédez au registre d'agents dans la consoleGoogle Cloud ou si vous utilisez la Google Cloud CLI lorsque vous êtes authentifié avec la fédération des identités des employés :

La consoleGoogle Cloud affiche des erreurs de chargement génériques, telles que les suivantes :

  • "Une erreur s'est produite lors du chargement..."
  • "Le serveur n'a pas pu traiter votre requête"
  • "Échec du chargement"

De plus, les commandes gcloud peuvent renvoyer une erreur interne, telle que error 13: an internal error has occurred.

Pour résoudre ce problème, authentifiez-vous avec un compte Google standard géré via Cloud Identity ou Google Workspace. Assurez-vous que le compte dispose des autorisations requises, telles que roles/agentregistry.admin ou roles/agentregistry.viewer.

Les services de gouvernance de Gemini Enterprise Agent Platform offrent une compatibilité limitée avec les identités fédérées. L'attribution de rôles IAM plus larges à un compte principal fédéré ne résout pas le problème.

Téléchargement de la révision de la compétence bloqué en raison de problèmes de sécurité

L'erreur suivante se produit si vous tentez de télécharger une charge utile de révision de compétence lorsque la règle d'analyse de la compétence est définie sur ENABLED_BLOCKING et que la révision comporte des résultats de sécurité :

FAILED_PRECONDITION: cannot download skill revision with scan findings when scanning policy is ENABLED_BLOCKING

Pour résoudre ce problème, effectuez l'une des opérations suivantes :

  1. Inspectez les résultats de sécurité détectés sur la révision en exécutant la commande gcloud agent-registry findings list. Cette commande nécessite le rôle roles/agentregistry.admin.
  2. Corrigez le résultat dans vos fichiers sources locaux, par exemple en supprimant le code de sortie réseau non autorisé, en supprimant les identifiants exposés ou en éliminant les modèles d'injection de prompt.
  3. Importez et enregistrez une nouvelle révision de compétence.
  4. Si vous travaillez dans un environnement de test ou de préproduction autorisé, vous pouvez également mettre à jour la règle d'analyse de la compétence sur ENABLED_NONBLOCKING à l'aide de --scanning-policy=enabled-nonblocking. Pour en savoir plus, consultez Analyser les compétences pour détecter les problèmes de sécurité.

Échec de la définition de la révision par défaut ou de l'activation de la règle de blocage

L'erreur suivante se produit si vous mettez à jour le pointeur de révision par défaut d'une compétence (--default-revision) ou si vous remplacez la règle d'analyse d'une compétence par ENABLED_BLOCKING lorsque la révision comporte des résultats ou des résultats d'analyse en attente :

L'API renvoie une erreur FAILED_PRECONDITION avec l'un des messages suivants :

  • cannot set default revision to a revision with scan findings when scanning policy is ENABLED_BLOCKING
  • cannot set default revision to a revision with pending scan results when scanning policy is ENABLED_BLOCKING
  • cannot set scanning policy to ENABLED_BLOCKING when default revision has scan findings
  • cannot set scanning policy to ENABLED_BLOCKING when default revision has pending scan results

Pour résoudre ce problème, procédez comme suit :

  • Si l'analyse est toujours en attente (RUNNING), attendez que l'analyse en arrière-plan se termine et vérifiez que scanResult.scanState est résolu en SUCCEEDED sans findings avant de définir la révision par défaut ou d'activer ENABLED_BLOCKING.
  • Si la révision cible ou la révision par défaut actuelle présente des résultats de sécurité, publiez une nouvelle révision dans laquelle les problèmes de sécurité sont résolus, vérifiez que son scanResult.scanState correspond à SUCCEEDED sans qu'aucun findings ne soit listé, et définissez cette révision propre comme defaultRevision de la compétence.

Révision de la compétence refusée en raison des limites de taille non compressée

L'erreur suivante se produit lorsque vous importez une révision de compétence qui dépasse les limites de taille d'analyse maximale non compressée :

L'opération de longue durée échoue avec une erreur INVALID_ARGUMENT, ou l'état scanResult.scanState de la révision passe à UNSUPPORTED_FORMAT.

Pour résoudre ce problème, effectuez l'une des opérations suivantes :

  • Inspectez les fichiers non compressés de votre package ZIP. Supprimez les ensembles de données volumineux, les binaires de modèle ou les éléments inutiles pour que chaque fichier ne dépasse pas 1 Mo et que le package extrait total ne dépasse pas 10 Mo.
  • Si votre workflow de développement nécessite l'importation de fichiers volumineux pour un prototypage rapide dans un projet, remplacez la règle d'analyse de la compétence par DISABLED à l'aide de --scanning-policy=disabled, si votre règle d'administration le permet.

Impossible de désactiver l'analyse des compétences en raison d'une règle d'administration

L'erreur suivante se produit si vous créez ou mettez à jour une compétence dont la règle d'analyse est définie sur DISABLED, ou si vous mettez à jour un champ d'une compétence existante dont le champ scanningConfig.policy était précédemment défini sur DISABLED :

La requête échoue avec une erreur de non-respect d'une contrainte personnalisée liée à une règle d'administration.

Pour résoudre ce problème, procédez comme suit :

  • Votre organisation a appliqué une contrainte de règle d'administration personnalisée, telle que custom.skillsScanningEnforcement, sur agentregistry.googleapis.com/Skill qui refuse resource.scanningConfig.policy == "DISABLED".
  • Si vous mettez à jour une compétence existante dont le champ scanningConfig.policy était défini sur DISABLED avant l'application de la règle d'administration, incluez une mise à jour de scanningConfig.policy en le définissant sur ENABLED_BLOCKING ou une valeur autorisée dans votre requête UpdateSkill.
  • Pour autoriser la désactivation de l'analyse dans les environnements de test ou de bac à sable, demandez à l'administrateur des règles d'administration d'ajouter un tag d'exemption conditionnelle, tel que exempt-scanning-enforcement: true, à votre projet.

Pour en savoir plus, consultez Appliquer l'analyse à l'aide du service de règles d'administration.

La révision de la compétence n'a pas été analysée après l'activation de l'analyse

L'erreur suivante se produit si vous activez l'analyse sur une compétence existante pour laquelle des révisions ont déjà été importées :

L'état de l'analyse (scanResult.scanState) d'une révision existante reste DISABLED, la révision n'est pas analysée et aucun résultat de sécurité n'est généré.

L'activation de l'analyse pour une compétence ne s'applique qu'aux révisions de compétences créées après l'activation de l'analyse. Agent Registry n'analyse pas rétroactivement les révisions créées avant l'activation de l'analyse.

Pour résoudre ce problème, importez et enregistrez une nouvelle révision de la compétence. Lorsque vous importez la nouvelle révision, Agent Registry analyse la charge utile conformément à la configuration d'analyse mise à jour de la compétence. Pour en savoir plus, consultez Créer une révision de compétence et Analyser les compétences pour détecter les problèmes de sécurité.

Impossible de configurer la CMEK, car des compétences existent déjà

L'erreur suivante se produit si vous tentez de définir ou de mettre à jour le champ SkillEncryptionSpec pour un emplacement où des compétences existent déjà :

FAILED_PRECONDITION: crypto_key_name can only be set or updated when no Skills exist in this location

Vous ne pouvez configurer ou mettre à jour une clé de chiffrement gérée par le client (CMEK) dans un projet et un emplacement que si aucune compétence n'existe dans cet emplacement.

Pour résoudre ce problème, configurez SkillEncryptionSpec dans l'emplacement cible avant d'y enregistrer votre première compétence, ou supprimez toutes les compétences existantes dans cet emplacement avant de définir ou de mettre à jour la clé Cloud Key Management Service. Pour en savoir plus, consultez Configurer des CMEK pour les compétences.

Emplacement de clé Cloud KMS non valide pour les compétences

L'erreur suivante se produit si vous configurez un SkillEncryptionSpec avec une clé Cloud KMS qui ne se trouve pas dans l'emplacement Cloud KMS requis ou dans un emplacement de compétence non compatible :

La requête échoue avec une erreur INVALID_ARGUMENT indiquant l'un des éléments suivants :

  • crypto_key_name "..." is in location "...", but Skills in location "..." can only be encrypted with a Cloud KMS key in location "..."
  • customer-managed encryption keys aren't supported for Skills in location "..."

Pour résoudre ce problème, vérifiez que vous configurez les CMEK dans un emplacement de compétence compatible (us ou eu) et que votre clé Cloud KMS se trouve dans l'emplacement multirégional Cloud KMS requis :

Emplacement de la compétence Emplacement de la clé Cloud KMS requis
us us
eu europe

Cloud KMS utilise europe comme identifiant d'emplacement pour l'emplacement multirégional de l'Union européenne. Les clés CMEK ne sont pas compatibles avec d'autres emplacements, y compris global. Pour en savoir plus, consultez Configurer des CMEK pour les compétences.

Création de la compétence bloquée par une règle d'administration CMEK

L'erreur suivante se produit lorsque vous créez une compétence ou une révision de compétence dans un projet soumis à des contraintes de règle d'administration CMEK :

La requête échoue avec une erreur FAILED_PRECONDITION indiquant l'un des éléments suivants :

  • constraint "constraints/gcp.restrictNonCmekServices" violated for value "agentregistry.googleapis.com". See https://cloud.google.com/kms/docs/cmek-org-policy#require-cmek for more information.
  • constraint "constraints/gcp.restrictCmekCryptoKeyProjects" violated for value "projects/KMS_PROJECT_ID". See https://cloud.google.com/kms/docs/cmek-org-policy#restrict-cmek-projects for more information.

Pour résoudre ce problème, procédez comme suit :

  • Si la contrainte constraints/gcp.restrictNonCmekServices n'est pas respectée, votre organisation nécessite une protection CMEK pour Agent Registry. Créez des compétences dans un emplacement compatible avec les CMEK (us ou eu) et configurez une SkillEncryptionSpec pour cet emplacement avant d'y créer des compétences.
  • Si la règle constraints/gcp.restrictCmekCryptoKeyProjects n'est pas respectée, la clé Cloud KMS configurée dans la SkillEncryptionSpec de l'emplacement appartient à un projet qui n'est pas autorisé par la règle constraints/gcp.restrictCmekCryptoKeyProjects de votre organisation. Mettez à jour le SkillEncryptionSpec lorsqu'aucune compétence n'existe dans cet emplacement pour référencer une clé Cloud KMS d'un projet autorisé, ou contactez l'administrateur des règles d'administration pour autoriser le projet de clé.

Pour en savoir plus, consultez Appliquer les CMEK à l'aide du service de règles d'administration.