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 d'un quota de débit par défaut de 1 200 requêtes par minute, ou 20 requêtes par seconde, au niveau mondial et par région.

Si vous rencontrez des problèmes de limitation lorsque vous changez d'onglet dans la console Google Cloud , patientez 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 à 500 Ko, 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 .. ni 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 alpha agent-registry skills list ou gcloud alpha 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 compte utilisateur ou 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 Google ou Google Cloud distant 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. Lorsque Agent Gateway résout une URL cible, les entrées de registre régionales prévalent 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 non concordantes :

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 de vos liaisons de règles cibles :

• Aligner les régions de la passerelle et de Model Armor : assurez-vous que Agent Gateway, les modèles Model Armor, l'extension d'autorisation et la règle 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. Étant donné que 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 régir 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 cible McpServer 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.

Échec de l'enregistrement manuel ou de la création de liaisons dans un emplacement multirégional

L'erreur suivante se produit si vous essayez d'enregistrer manuellement un agent, un serveur MCP ou un point de terminaison, ou de créer une liaison, dans un emplacement multirégional tel que us ou eu :

L'API rejette la requête avec une erreur d'emplacement non compatible ou d'argument non valide.

Pour résoudre ce problème, spécifiez un emplacement régional pris en charge, tel que us-central1 ou europe-west1, ou l'emplacement global. Les emplacements multirégionaux us et eu ne permettent que de découvrir les composants enregistrés automatiquement, et d'enregistrer ou de découvrir des compétences autonomes. Pour obtenir la liste des emplacements compatibles, consultez Emplacements du registre d'agents.

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