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

Cette page explique comment résoudre les problèmes liés à Agent Registry.

Quota de débit API dépassé

Ce problème peut se produire si vous interagissez avec l'API Agent Registry ou si vous naviguez rapidement dans Agent Registry dans la Google Cloud console :

429 Too Many Requests

Pour résoudre ce problème, implémentez une stratégie de backoff exponentiel dans vos clients API afin de gérer les taux de requêtes. L'API Agent Registry dispose d'un quota de débit par défaut de requêtes de 1 200 requêtes par minute au niveau mondial et par région (20 requêtes par seconde).

Si vous rencontrez une limitation du débit lorsque vous changez d'onglet dans la Google Cloud console, 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

Ce problème peut se produire si vous enregistrez manuellement un agent ou un serveur MCP : 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 est inférieur à 10 Ko. La taille du contenu AgentSpec et McpServerSpec est limitée à 10 Ko. Pour respecter cette limite, réduisez la taille de vos fichiers JSON, supprimez les espaces inutiles ou condensez les descriptions d'outils. Pour en savoir plus, consultez la section Schémas JSON.

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

Ce problème peut se produire si vous créez un agent ou un serveur MCP dans un produit compatible Google Cloud , tel que Google Workspace ou Gemini Enterprise : la ressource n'apparaît pas lorsque vous appelez les API ListAgents ou ListMcpServers.

Pour résoudre ce problème, attendez la fin de la synchronisation en arrière-plan. Vos ressources sont mises à jour en temps réel, mais d'autres intégrations sont remplies par des jobs par lot hors connexion exécutés régulièrement. Si votre ressource n'apparaît pas après plusieurs heures, vérifiez les paramètres d'utilisation des services de votre projet et assurez-vous que l'API concernée est activée.

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

Ce problème peut se produire si 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. Certaines créations de backend d'agent et de MCP nécessitent 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

Ce problème peut se produire si vous récupérez les liaisons disponibles pour un fournisseur d'authentification : l'API renvoie un empty array ou une erreur d'accès, même si vous avez vérifié que la liaison existe.

Pour résoudre ce problème, vérifiez que votre 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 principal dispose de l'accès requis au fournisseur d'authentification et du rôle roles/agentregistry.viewer sur le projet.

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

Ce problème peut se produire 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 : la requête échoue et renvoie une erreur semblable à la suivante :

{
  "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 correctement l'archive de la compétence. Par exemple, si vous utilisez curl, ajoutez l'indicateur -L ou --location à votre commande.

Échec de la validation de la révision de compétence ou état FAILED

Ce problème peut se produire après la création d'une révision de compétence : la révision passe à l'état FAILED et ne peut pas être chargée par les agents.

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

• Assurez-vous que l'archive ZIP contient un fichier SKILL.md à sa racine.
• Vérifiez que le fichier SKILL.md comporte un bloc de frontmatter YAML valide avec les éléments 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 inférieure à 10 Mo et la taille de chaque fichier 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.