Résolution des problèmes liés aux agents personnalisés

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 schema pour 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. allowedTools par 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 list n'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
• 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 list pour 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 :

• /tools renvoie une liste vide
• Les outils attendus sont absents de la liste des outils
• L'agent personnalisé semble n'avoir aucune capacité

Causes courantes :

• Tableau tools vide 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 tools avec 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 tools et allowedTools
• 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 toolAliases sont 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 resources sont corrects et que les fichiers existent
• Vérifiez que les motifs glob dans resources correspondent 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é :

1. Validez la syntaxe JSON à l'aide d'un validateur JSON
2. Vérifiez la configuration par rapport au schéma à l'aide de /agent schema
3. Testez le chargement de l'agent avec /agent list
4. Passez à l'agent personnalisé avec /agent swap [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

• 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