Résolution des problèmes - Amazon Q Developer
Erreurs de configurationProblèmes de chargement d'agents personnalisésProblèmes d'autorisation des outilsDébogage du comportement d'un agent personnaliséObtenir de l'aide supplémentaire

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Résolution des problèmes

Cette section décrit les problèmes courants que vous pouvez rencontrer lorsque vous travaillez avec des agents personnalisés et explique comment les résoudre.

Erreurs de configuration

Syntaxe JSON non valide

Problème : l'agent personnalisé ne parvient pas à se charger en raison d'erreurs d'analyse JSON.

Symptômes :

  • Messages d'erreur mentionnant un « JSON non valide » ou une « erreur de syntaxe »

  • L'agent personnalisé n'apparaît pas dans /agent list

  • Revenir au comportement par défaut de l'agent

Des solutions :

  • Validez votre JSON à l'aide d'un validateur JSON ou d'un linter

  • Vérifiez les erreurs JSON courantes :

    • Virgules manquantes entre les éléments du tableau ou les propriétés des objets

    • Virgules de fin après le dernier élément

    • Supports ou bretelles inégalés

    • Guillemets non cachés dans les valeurs de chaîne

  • /agent schemaÀ utiliser pour vérifier votre structure de configuration

Erreurs de validation du schéma

Problème : la configuration de l'agent personnalisé ne correspond pas au schéma attendu.

Symptômes :

  • Avertissements concernant des champs de configuration inconnus

  • Le comportement de l'agent personnalisé ne correspond pas à la configuration

  • Erreurs relatives aux champs obligatoires manquants

Des solutions :

  • Comparez votre configuration au schéma en utilisant /agent schema

  • Vérifiez les noms des champs pour détecter les fautes de frappe (par exemple, allowedTools vsallowedTool)

  • Vérifiez que les types de données répondent aux exigences du schéma (tableaux contre chaînes, booléens contre chaînes)

  • Consultez la documentation relative au format de l'agent dans la documentation supplémentaire de la CLI Amazon Q Developer pour connaître la syntaxe correcte.

Problèmes de chargement d'agents personnalisés

Agent personnalisé introuvable

Problème : l'agent personnalisé n'apparaît pas dans la liste ou ne peut pas être utilisé.

Symptômes :

  • /agent listn'affiche pas votre agent personnalisé

  • /agent use [name]échoue avec « agent introuvable »

  • Revenir à l'agent par défaut sans avertissement

Des solutions :

  • Vérifiez que le fichier d'agent personnalisé se trouve au bon emplacement :

    • À l'échelle mondiale : ~/.aws/amazonq/cli-agents/[name].json

    • Local : amazonq/cli-agents/[name].json

  • Vérifiez les autorisations du fichier : assurez-vous que le fichier est lisible

  • Vérifiez que le nom du fichier correspond au nom de l'agent personnalisé que vous essayez d'utiliser

  • Assurez-vous que le fichier possède une .json extension

Mauvaise version de l'agent personnalisé lors du chargement

Problème : une version de votre agent personnalisé ne se charge pas comme prévu.

Symptômes :

  • Le comportement de l'agent personnalisé ne correspond pas à vos récentes modifications de configuration

  • Message d'avertissement concernant les conflits entre agents personnalisés

  • Disponibilité ou autorisations inattendues des outils

Des solutions :

  • Vérifiez les conflits de noms d'agents personnalisés entre les annuaires locaux et globaux

  • N'oubliez pas que les agents personnalisés locaux ont priorité sur les agents personnalisés mondiaux

  • /agent listÀ utiliser pour voir quelle version est en cours de chargement

  • Supprimez ou renommez les fichiers d'agents personnalisés en conflit si nécessaire

Problèmes d'autorisation des outils

Outil non disponible

Problème : l'agent personnalisé ne peut pas accéder à un outil que vous avez configuré.

Symptômes :

  • Messages d'erreur concernant des outils inconnus ou indisponibles

  • Agent personnalisé demandant l'autorisation d'utiliser des outils allowedTools

  • Les outils du serveur MCP ne fonctionnent pas

Des solutions :

  • Vérifiez que les noms des outils sont correctement orthographiés dans le tableau tools

  • Pour les outils MCP, assurez-vous que le serveur est correctement configuré dans mcpServers

  • Vérifiez que les serveurs MCP fonctionnent et sont accessibles

  • Utilisez la syntaxe correcte pour les outils MCP : @server_name/tool_name

  • Vérifiez les noms des outils intégrés par rapport à la documentation relative aux outils intégrés dans la documentation supplémentaire Amazon Q Developer CLI

La commande /tools renvoie une liste vide

Problème : La /tools commande n'affiche aucun outil disponible ou moins d'outils que prévu.

Symptômes :

  • /toolsrenvoie une liste vide

  • Les outils attendus sont absents de la liste des outils

  • L'agent personnalisé ne semble pas avoir de fonctionnalités

Causes courantes :

  • toolsTableau vide dans la configuration de l'agent personnalisé

  • Fautes de frappe dans les noms d'outils du tableau tools

  • Noms d'outils du serveur MCP incorrects (préfixe de serveur manquant)

  • Problèmes de configuration du serveur MCP empêchant le chargement des outils

Des solutions :

  • Vérifiez que la configuration de votre agent personnalisé inclut un tools tableau avec des noms d'outils valides

  • Vérifiez que les noms des outils sont correctement orthographiés (distinction majuscules et minuscules)

  • Pour les outils MCP, assurez-vous d'utiliser le format préfixé par le serveur correct : server-name___tool-name

  • Effectuez un test avec l'agent par défaut pour vérifier que les outils sont disponibles : q chat puis /tools

  • Vérifiez l'état du serveur MCP si vous utilisez des outils externes

Demandes d'autorisation inattendues

Problème : un agent personnalisé demande l'autorisation d'utiliser des outils que vous pensiez avoir été préapprouvés.

Symptômes :

  • Demandes d'autorisation pour les outils répertoriés dans allowedTools

  • Interruptions du flux de travail malgré la configuration personnalisée des agents

Des solutions :

  • Assurez-vous que les outils sont répertoriés à la fois dans les allowedTools tableaux tools et dans les tableaux

  • Vérifiez les fautes de frappe dans les noms d'outils entre les deux tableaux

  • Pour les outils MCP, utilisez le nom complet préfixé par le serveur dans allowedTools

  • Vérifiez qu'toolAliasesils sont correctement appliqués

Débogage du comportement d'un agent personnalisé

Contexte ou ressources manquants

Problème : l'agent personnalisé ne semble pas avoir accès aux fichiers ou au contexte attendus.

Des solutions :

  • Vérifiez que les chemins de fichiers du resources tableau sont corrects et que les fichiers existent

  • Vérifiez que les modèles globaux des ressources correspondent aux fichiers souhaités

  • Assurez-vous que les commandes hook s'exécutent correctement et produisent une sortie

  • Testez les commandes hook manuellement pour vérifier qu'elles fonctionnent dans votre environnement

  • Vérifiez les paramètres de temporisation du hook si les commandes sont coupées

Problèmes liés au serveur MCP

Problème : les serveurs MCP ne fonctionnent pas ou les outils ne sont pas disponibles.

Des solutions :

  • Vérifiez que les commandes du serveur MCP sont correctes et que les exécutables se trouvent dans votre PATH

  • Vérifiez que les variables d'environnement requises sont définies

  • Testez les serveurs MCP de manière indépendante pour vous assurer qu'ils fonctionnent

  • Consultez les journaux du serveur MCP pour détecter les messages d'erreur

  • Augmenter les valeurs de délai d'attente si les serveurs sont lents à démarrer

  • Pour en savoir plus sur la résolution des problèmes liés au MCP, consultez Utilisation du MCP avec Amazon Q Developer

Tester des configurations d'agents personnalisées

Pour tester systématiquement la configuration de votre agent personnalisé :

  1. Valider la syntaxe JSON à l'aide d'un validateur JSON

  2. Vérifiez la configuration par rapport au schéma en utilisant /agent schema

  3. Testez le chargement de l'agent personnalisé avec /agent list

  4. Passez à l'agent personnalisé avec /agent use [name]

  5. Testez chaque outil individuellement pour vérifier l'accès et les autorisations

  6. Vérifiez que les ressources et les hooks fournissent le contexte attendu

  7. Testez les flux de travail courants pour vous assurer que l'agent personnalisé se comporte comme prévu

Obtenir de l'aide supplémentaire

Si vous continuez à rencontrer des problèmes avec les agents :