Passer au contenu principal
Afficher en Markdown

Mise à niveau des configs d'agent

Les profils d'agent CLI V3 utilisent des outils basés sur des balises et des permissions unifiées. Si vous avez des agents créés avant l'introduction de ce format, la commande /upgrade-agent les convertit sur place. Elle ajoute les nouveaux champs de permission en plus de votre configuration existante et sauvegarde les originaux avant l'écriture.

Exécutez /upgrade-agent chaque fois que vous repérez des champs plus anciens comme toolsSettings ou allowedTools, ou après avoir modifié les paramètres de confiance V2 dans un agent mis à niveau. Kiro enregistre l'état V3 généré dans un marqueur kiroUpgrade dans chaque fichier mis à niveau, de sorte qu'une exécution ultérieure peut déterminer quels agents ont besoin d'une première mise à niveau, d'une actualisation ou de votre examen.

Mise à niveau automatique au démarrage de V3

Dans Kiro CLI 2.37 ou une version ultérieure, une session V3 met à niveau les agents au format V2 en attente lorsqu'elle démarre, de sorte que vous avez rarement besoin d'exécuter /upgrade-agent vous-même. Avant 2.37, la migration au lancement ne s'exécutait pas d'elle-même lorsque le paramètre chat.enableAutoAgentUpgrade n'était pas défini; elle s'exécute maintenant chaque fois que le paramètre n'est pas défini, et un false explicite la garde toujours désactivée. La mise à niveau automatique applique la même conversion que celle décrite sur cette page.

L'analyse au lancement couvre les mêmes répertoires que /upgrade-agent run : par défaut, .kiro/agents/ dans votre espace de travail et ~/.kiro/agents/ globalement. Lorsque KIRO_AGENT_CONFIG_DIR est défini, Kiro analyse ce répertoire au lieu du répertoire global et ignore l'analyse de l'espace de travail. L'analyse ne cherche pas dans d'autres répertoires. Un lien symbolique .json analysé peut tout de même pointer à l'extérieur du répertoire analysé; consultez Sécurité et confiance. Utilisez kiro-cli agent upgrade <directory> pour mettre à niveau directement un répertoire distinct.

Le paramètre chat.enableAutoAgentUpgrade a deux états :

  • Enabled (non défini ou true) : Chaque lancement V3 met à niveau les agents au format V2 en attente dans les répertoires analysés sans demander. Chaque fichier réécrit reçoit d'abord une sauvegarde .json.bak.
  • Disabled (false) : Les lancements laissent les fichiers d'agent inchangés. Un lancement V3 interactif affiche un avis indiquant combien d'agents sont encore au format V2, et vous les mettez à niveau avec /upgrade-agent ou kiro-cli agent upgrade <directory> au moment de votre choix.

Préférez Enabled lorsque vous voulez que les agents personnalisés V2 continuent de fonctionner sur V3 sans étape manuelle; préférez Disabled lorsque les fichiers d'agent sont partagés ou sous gestion de versions et que vous voulez examiner chaque conversion avant qu'elle soit appliquée.

Pour désactiver la mise à niveau automatique :

bash
kiro-cli settings chat.enableAutoAgentUpgrade false

Le paramètre est global; le fichier .kiro/settings/cli.json d'un espace de travail ne peut pas le remplacer.

Pour confirmer quels agents ont été mis à niveau, exécutez /upgrade-agent diagnostics et vérifiez qu'ils apparaissent comme agents Universal.

Sécurité et confiance

La mise à niveau automatique réécrit sur place les fichiers d'agent au format V2, sans invite, dans les répertoires qu'elle analyse : .kiro/agents/ dans votre espace de travail et ~/.kiro/agents/ globalement, ou seulement le répertoire KIRO_AGENT_CONFIG_DIR lorsque cette variable est définie. Avant d'écrire, elle copie chaque original vers <filename>.json.bak, de sorte que vous pouvez annuler une mise à niveau. Elle ignore les agents qui sont déjà au format V3 ou universel. Si un fichier .json analysé est un lien symbolique, Kiro suit le lien et réécrit sur place la cible liée, même lorsque cette cible se trouve à l'extérieur du répertoire analysé. Pour l'arrêter, exécutez kiro-cli settings chat.enableAutoAgentUpgrade false; Kiro se contente alors de signaler les agents en attente et laisse chaque fichier tel quel.

Utilisation

bash
# Scan agents and open the selection menu /upgrade-agent # Same as above (explicit subcommand) /upgrade-agent run # Review previously upgraded agents and any conversion warnings /upgrade-agent diagnostics

Mettre à niveau un répertoire à partir du shell

Utilisez la commande CLI lorsque les fichiers d'agent se trouvent dans un répertoire central ou que vous voulez un aperçu non interactif :

bash
# Preview changes and warnings without writing files kiro-cli agent upgrade <directory> --dry-run # Upgrade the files and keep backups kiro-cli agent upgrade <directory>

La commande vérifie les fichiers *.json de premier niveau du répertoire. Elle ne parcourt pas les sous-répertoires. Par défaut, chaque fichier modifié reçoit une sauvegarde .bak. Ajoutez --no-backup seulement lorsqu'une autre copie de récupération existe déjà.

Une exécution à blanc rapporte ce qui changerait et inclut les avertissements de conversion. Dans Kiro CLI 2.36 ou une version ultérieure, la commande avertit aussi lorsque les règles mises à niveau refusent, masquent ou demandent une approbation pour quelque chose que V2 autorisait, et le tableau de résultats note (N warnings) à côté de chaque fichier mis à niveau. Sur macOS et Linux, elle rapporte aussi les fichiers que l'exécution réelle ne pourrait pas écrire. Elle laisse chaque fichier inchangé. La commande ignore les JSON qui ne sont pas des agents, les agents gérés de l'extérieur, les fichiers non réguliers, les configs universelles désynchronisées, les chemins en double vers le même fichier et les liens symboliques dont la cible est à l'extérieur du répertoire sélectionné.

Le code de sortie 0 signifie que chaque fichier a été mis à niveau, laissé inchangé ou ignoré. Le code de sortie 1 signifie qu'au moins un fichier a échoué. Le code de sortie 2 signifie que le chemin est manquant, illisible ou n'est pas un répertoire.

Dans Kiro CLI 2.37 ou une version ultérieure, une exécution V3 --no-interactive qui s'arrête parce que son agent nommé est au format V2 se termine avec le code 4 et nomme cette commande avec le répertoire de l'agent, de sorte qu'un script peut convertir l'agent et réessayer. Consultez Codes de sortie.

Par défaut, la sous-commande run analyse .kiro/agents/ dans votre espace de travail et ~/.kiro/agents/ globalement. Si ces répertoires n'existent pas, Kiro vérifie .amazonq/cli-agents/ dans l'espace de travail et ~/.aws/amazonq/cli-agents/ globalement. Lorsque KIRO_AGENT_CONFIG_DIR est défini, Kiro utilise ce répertoire pour l'analyse globale et ignore l'analyse de l'espace de travail. Le menu de sélection regroupe les résultats par portée, et seuls les agents qui doivent être mis à niveau apparaissent.

Ce qui se passe pendant la mise à niveau

Lorsque vous sélectionnez un groupe d'agents à mettre à niveau :

  1. Chaque fichier original est copié vers <filename>.json.bak comme sauvegarde
  2. Les champs de permission du nouveau format sont ajoutés en plus de votre configuration existante
  3. Vos paramètres originaux (noms d'outils, commandes autorisées, restrictions de chemin) sont préservés avec des règles équivalentes dans le nouveau format
  4. Une alerte de confirmation indique le nombre d'agents mis à niveau

Si un fichier de sauvegarde existe déjà, des suffixes numérotés sont utilisés (.bak.1, .bak.2, etc.). Lorsqu'une config d'agent est un lien symbolique, Kiro écrit le contenu mis à niveau dans le fichier lié et laisse le lien symbolique en place.

Actualiser les agents mis à niveau

Kiro actualise les permissions, les outils et les Hooks V3 générés lorsqu'ils ne correspondent plus aux paramètres de confiance V2 du même fichier, ou lorsque la migration elle-même a été révisée. Si vous n'avez pas modifié ces champs générés, l'agent apparaît de nouveau dans le menu de sélection et la mise à niveau les remplace par des valeurs fraîchement générées.

Si vous modifiez à la main les champs V3 générés, Kiro cesse de les actualiser automatiquement. L'agent apparaît sous Universal · Out of Sync dans le menu de sélection. Sélectionner ce groupe reconstruit V3 à partir des paramètres V2 et écrase vos modifications manuelles de V3. Kiro enregistre le fichier précédent comme sauvegarde .bak.

Annuler une mise à niveau

Si vous souhaitez annuler la mise à niveau, renommez le fichier .json.bak en .json :

bash
mv .kiro/agents/my-agent.json.bak .kiro/agents/my-agent.json

Ce qui est converti

La mise à niveau traduit vos paramètres de permission existants dans le format v3 :

  • Noms d'outils : Les anciens noms (comme fs_read, execute_bash) sont mappés vers des balises de capacité v3 (comme read, shell). Les deux sont préservés pour la compatibilité.
  • toolsSettings : Les règles d'autorisation/refus par outil deviennent des entrées permissions.rules avec une capacité, un modèle de correspondance et un effet.
  • allowedTools : Les entrées d'outils de confiance deviennent des règles d'autorisation au niveau de la capacité.
  • toolsSettings.subagent.trustedAgents : Devient une règle { "capability": "subagent", "match": [...], "effect": "allow" }. La règle supprime seulement l'invite au démarrage de ces sous-agents. Elle n'approuve pas leurs appels d'outils. Consultez Permissions des sous-agents.
  • toolsSettings.subagent.availableAgents : Si tools contient subagent, la migration le remplace par une entrée subagent/<name> pour chaque agent de la liste. Si tools contient aussi @builtin ou *, l'agent peut tout de même démarrer n'importe quel agent au moyen de invoke_sub_agent; remplacez donc ces entrées par des balises de catégorie comme read et shell pour conserver la restriction.
  • Modèles Regex : V3 fait correspondre les commandes et les URL avec des globs, et non avec des regex. Un regex dans allowedCommands ou web_fetch.trusted devient un glob lorsqu'un glob y correspond exactement; dans une autorisation, un . isolé est lu comme un point littéral, de sorte que cat package.json reste une autorisation exacte. Dans Kiro CLI 3.3.0 ou version ultérieure, un regex d'autorisation auquel aucun glob ne correspond exactement est supprimé avec un avertissement unconvertible-pattern, de sorte que V3 demande une approbation avant d'exécuter ce qu'il autorisait au lieu d'approuver automatiquement un glob plus large; un regex de refus qui peut être approximé devient un glob plus large, tandis qu'un regex de refus sans forme V3 bloque toute utilisation de l'outil. Les agents qu'une mise à niveau antérieure a écrits et que personne n'a modifiés sont dérivés de nouveau au prochain lancement.
  • autoAllowReadonly : Se convertit en une politique de shell en lecture seule.
  • Hooks de forme objet : Convertis au format tableau requis par le schéma v3.
  • Lectures de l'espace de travail : Les configs migrées autorisent fs_read pour ./**, de sorte que l'agent peut lire les fichiers de l'espace de travail sans demander. Les règles de refus ont toujours la priorité.
  • Confiance des Skills : Si la config V2 fait confiance à tous les outils intégrés, ou inclut à la fois un outil de lecture et fait confiance à fs_read, la migration fait aussi confiance au chargement des Skills. Lorsque les restrictions de lecture V2 (deniedPaths) pourraient atteindre des fichiers de Skills, les Skills demandent plutôt une approbation dans V3, et les diagnostics rapportent skill-read-restrictions.

Tous les autres champs (name, description, model, prompt, resources, mcpServers, welcomeMessage) passent sans changement.

Exemple

Voici une première exécution typique. Vous avez 3 agents d'espace de travail et 1 agent global dans des formats plus anciens :

bash
/upgrade-agent

Menu de sélection :

V2 or earlier upgrade [3 agents] Workspace Upgrade or refresh the universal (V2 + V3) config V2 or earlier upgrade [1 agent] Global Upgrade or refresh the universal (V2 + V3) config

Sélectionnez « V2 or earlier upgrade [3 agents] - Workspace » pour mettre à niveau les 3 agents au niveau de l'espace de travail. Une config universelle (V2 + V3) conserve vos champs originaux pour la rétrocompatibilité tout en ajoutant les règles de permission plus récentes.

Alerte post-mise à niveau :

Upgraded 3 agents (backed up to .json.bak)

Examen des diagnostics

Exécutez les diagnostics pour vérifier les avertissements de conversion, les modèles qui n'ont pas pu être parfaitement traduits :

bash
/upgrade-agent diagnostics
2 Universal agents my-agent Workspace ⚠ unconvertible-pattern: sleep [0-9]+ strict-dev Global ⚠ deny-by-default-readonly

Types d'avertissement

AvertissementSignificationQue faire
regex-shell-patternUn regex de shell a été approximé en tant que globVérifiez le modèle converti dans permissions.rules
regex-web-patternUn regex d'URL a été approximé en tant que globVérifiez le modèle d'URL converti
unconvertible-patternUn regex n'a aucun glob V3 exact. Dans Kiro CLI 3.3.0 ou version ultérieure, un motif d'autorisation portant cet avertissement est supprimé, de sorte que V3 demande une approbation avant d'exécuter ce qu'il autorisait; un motif de refus non convertible bloque toute utilisation de l'outilPour un motif d'autorisation, réécrivez-le avec seulement .* et du texte littéral : un . isolé est lu comme un point, échappez les autres caractères regex comme + sous la forme \+ et omettez *. Pour un motif de refus, réécrivez-le comme un glob plus étroit dans permissions.rules ou supprimez-le
unmapped-allowed-toolUne entrée d'outil n'a pas pu être mappée à une capacitéVérifiez si l'outil a un nouveau nom ou a été supprimé
deprecated-aws-toolL'outil aws / use_aws est dépréciéSupprimez la référence à l'outil déprécié
deny-by-default-readonlyParamètres de refus par défaut et d'autorisation automatique en lecture seule en conflitVérifiez votre intention de permission et ajustez manuellement
file-promptLes chemins de requête de fichier absolus ou ~/ peuvent ne pas se résoudre dans tous les environnementsUtilisez plutôt des chemins relatifs
unconvertible-hookUn Hook n'a pas pu être converti au nouveau formatRecréez le Hook en utilisant le format de déclenchement pris en charge
skill-read-restrictionsLes restrictions de lecture V2 pourraient atteindre des fichiers de Skills, de sorte que les Skills demandent une approbation dans V3Vérifiez la permission skill générée avant d'utiliser l'agent
deny-by-default-trusted-shellallowedTools fait confiance au shell, de sorte que V2 exécutait chaque commande ; V3 refuse toute commande absente de allowedCommandsRetirez denyByDefault, ou retirez shell de allowedTools et listez les commandes à autoriser
hidden-toolUn refus couvre tout ce que l'outil peut faire, de sorte que V3 retire l'outil de l'agentRestreignez le refus, ou ajoutez les commandes ou les chemins à autoriser
allow-read-only-droppedallowReadOnly laissait V2 lire n'importe quel fichier sans demander ; V3 n'a aucune règle pour cela, de sorte que les lectures à l'extérieur de l'espace de travail demandent une approbationFaites confiance à l'outil de lecture dans allowedTools, ou ajoutez les chemins à allowedPaths

Kiro CLI 2.36 ou une version ultérieure rapporte les trois derniers avertissements, qui marquent un conflit de permission : les règles V3 mises à niveau refusent, masquent ou demandent une approbation pour quelque chose que V2 autorisait.

Avis de conflit dans les sessions V3

Dans Kiro CLI 2.36 ou une version ultérieure, une session V3 affiche un avis une fois par session pour chaque agent actif dont les règles de permission V3 bloquent quelque chose que ses paramètres V2 autorisaient. L'avis apparaît au démarrage de la session, lorsque vous changez d'agent avec /agent ou lorsque vous chargez une session enregistrée. Il nomme l'agent, liste jusqu'à trois constats et se termine par le chemin de retour vers V2 : kiro-cli settings chat.agentEngine v2 pour toutes les sessions, ou kiro-cli --v2 pour une seule session. Les sessions V2 n'affichent aucun avis.

Pour faire disparaître l'avis, modifiez les règles de permission de l'agent, ou demandez à son propriétaire de le faire. Un agent géré de l'extérieur doit être mis à jour par son propriétaire. Pour vérifier, démarrez une nouvelle session V3 avec cet agent ; l'avis n'apparaît plus une fois que ses règles autorisent ce que V2 autorisait.

Agents qui sont ignorés

Les éléments suivants sont exclus de l'analyse :

  • Les fichiers de sauvegarde (.bak) sont exclus de l'analyse
  • Les fichiers qui ne sont pas des configs d'agent valides (fichiers JSON sans prompt, tools, hooks, ou champs de permission) sont ignorés

Dépannage

Aucun agent n'apparaît dans le menu de sélection

Tous vos agents sont déjà dans le dernier format. Exécutez /upgrade-agent diagnostics pour examiner leur état actuel.

Avertissements après la mise à niveau

Certains modèles ne peuvent pas être parfaitement traduits du format regex au format glob. Exécutez /upgrade-agent diagnostics, examinez les agents signalés, et modifiez manuellement les permissions.rules dans la config mise à niveau si nécessaire. Dans Kiro CLI 3.3.0 ou version ultérieure, un motif d'autorisation signalé unconvertible-pattern est exclu de la config mise à niveau; les commandes ou les URL qu'il autorisait demandent donc une approbation jusqu'à ce que vous le réécriviez.

Agent manquant dans l'analyse

Vérifiez que le fichier est un JSON valide et contient au moins un champ prompt, tools, ou hooks. Les fichiers qui ne ressemblent pas à des configurations d'agent sont ignorés.

Voir aussi

Page mise à jour : 12 novembre 2026