Ce guide vous aide à diagnostiquer et à résoudre les problèmes courants liés à la création et à l'utilisation d'agents personnalisés.
Problème : L'agent personnalisé ne se charge pas en raison d'erreurs d'analyse JSON.
Symptômes :
- Messages d'erreur mentionnant « JSON invalide » ou « erreur de syntaxe »
- L'agent personnalisé n'apparaît pas dans
/agent list - Retour au comportement de l'agent par défaut
Solutions :
- Validez votre JSON à l'aide d'un validateur ou d'un linter JSON
- Vérifiez les erreurs JSON courantes :
- Virgules manquantes entre les éléments d'un tableau ou les propriétés d'un objet
- Virgules superflues après le dernier élément
- Crochets ou accolades non appariés
- Guillemets non échappés dans les valeurs de chaîne
- Utilisez
/agent schemapour vérifier la structure de votre configuration
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 de champs obligatoires manquants
Solutions :
- Comparez votre configuration au schéma à l'aide de
/agent schema - Vérifiez les noms de champs pour détecter les fautes de frappe (p. ex.
allowedToolspar rapport àallowedTool) - Vérifiez que les types de données correspondent aux exigences du schéma (tableaux par rapport aux chaînes, valeurs booléennes par rapport aux chaînes)
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é- Retour à l'agent par défaut sans avertissement
Solutions :
- Vérifiez que le fichier de l'agent personnalisé se trouve au bon endroit :
- Global :
~/.kiro/agents/[name].json - Espace de travail :
.kiro/agents/[name].json
- Global :
- 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 a une extension
.json
Problème : Une version différente de votre agent personnalisé se charge par rapport à celle attendue.
Symptômes :
- Le comportement de l'agent personnalisé ne correspond pas à vos modifications récentes de configuration
- Message d'avertissement concernant des conflits d'agents personnalisés
- Disponibilité ou autorisations d'outils inattendues
Solutions :
- Vérifiez les conflits de noms d'agents personnalisés entre les répertoires local et global
- N'oubliez pas que les agents personnalisés locaux ont préséance sur les agents personnalisés globaux
- Utilisez
/agent listpour voir quelle version est chargée - Supprimez ou renommez les fichiers d'agents personnalisés en conflit si nécessaire
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 non disponibles
- L'agent personnalisé demande une autorisation pour des outils figurant dans
allowedTools - Les outils du serveur MCP ne fonctionnent pas
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 sont en cours d'exécution et 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 des outils intégrés
Problème : La commande /tools 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é semble n'avoir aucune capacité
Causes courantes :
- Tableau
toolsvide dans la configuration de l'agent personnalisé - Fautes de frappe dans les noms d'outils au sein 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
Solutions :
- Vérifiez que la configuration de votre agent personnalisé inclut un tableau
toolsavec des noms d'outils valides - Vérifiez que les noms des outils sont correctement orthographiés (sensible à la casse)
- Pour les outils MCP, assurez-vous d'utiliser le format préfixé par le serveur correct :
@server-name/tool-name - Testez avec l'agent par défaut pour confirmer que les outils sont disponibles à l'aide de
/tools - Vérifiez l'état du serveur MCP si vous utilisez des outils externes
Problème : L'agent personnalisé demande une autorisation pour des outils que vous pensiez déjà approuvés.
Symptômes :
- Invites d'autorisation pour des outils figurant dans
allowedTools - Interruptions du flux de travail malgré la configuration de l'agent personnalisé
Solutions :
- Assurez-vous que les outils figurent à la fois dans les tableaux
toolsetallowedTools - Vérifiez l'absence de 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 que les
toolAliasessont correctement appliqués
Problème : L'agent personnalisé ne semble pas avoir accès aux fichiers ou au contexte attendus.
Solutions :
- Vérifiez que les chemins de fichiers dans le tableau
resourcessont corrects et que les fichiers existent - Vérifiez que les motifs glob dans
resourcescorrespondent aux fichiers visés - Assurez-vous que les commandes des hooks s'exécutent avec succès et produisent une sortie
- Testez manuellement les commandes des hooks pour vérifier qu'elles fonctionnent dans votre environnement
- Vérifiez les paramètres de délai d'expiration des hooks si les commandes sont interrompues
Problème : Les serveurs MCP ne fonctionnent pas ou les outils ne sont pas disponibles.
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 façon indépendante pour vous assurer qu'ils fonctionnent
- Consultez les journaux du serveur MCP pour les messages d'erreur
- Augmentez les valeurs de délai d'expiration si les serveurs sont lents à démarrer
Pour tester systématiquement la configuration de votre agent personnalisé :
- Validez la syntaxe JSON à l'aide d'un validateur JSON
- Vérifiez la configuration par rapport au schéma à l'aide de
/agent schema - Testez le chargement de l'agent avec
/agent list - Passez à l'agent personnalisé avec
/agent swap [name] - Testez chaque outil individuellement pour vérifier l'accès et les autorisations
- Vérifiez que les ressources et les hooks fournissent le contexte attendu
- Testez les flux de travail courants pour vous assurer que l'agent personnalisé se comporte comme prévu
- Référence de configuration - consultez les options de champs détaillées
- Exemples - configurations fonctionnelles à consulter
- Création d'agents personnalisés - guide de création étape par étape
Résolution des problèmes liés aux agents personnalisés