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-la une fois, choisissez les agents à mettre à niveau, et le tour est joué. Vous pouvez l'exécuter à tout moment lorsque vous repérez des champs plus anciens comme toolsSettings ou allowedTools dans vos configs.
# 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
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.
Lorsque vous sélectionnez un groupe d'agents à mettre à niveau :
<filename>.json.bak comme sauvegardeSi 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.
Si vous souhaitez annuler la mise à niveau, renommez le fichier .json.bak en .json :
mv .kiro/agents/my-agent.json.bak .kiro/agents/my-agent.json
La mise à niveau traduit vos paramètres de permission existants dans le format v3 :
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é.autoAllowReadonly : Se convertit en une politique de shell en lecture seule.Tous les autres champs (name, description, model, prompt, resources, mcpServers, welcomeMessage) passent sans changement.
Voici une première exécution typique. Vous avez 3 agents d'espace de travail et 1 agent global dans des formats plus anciens :
/upgrade-agent
Menu de sélection :
V2 [3 agents] Workspace Upgrade to universal (V2 + V3) config V2 [1 agent] Global Upgrade to universal (V2 + V3) config
Sélectionnez « V2 [3 agents] - Workspace » pour mettre à niveau les 3 agents au niveau de l'espace de travail. L'étiquette « universal (V2 + V3) » signifie que la config mise à niveau 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)
Exécutez les diagnostics pour vérifier les avertissements de conversion, les modèles qui n'ont pas pu être parfaitement traduits :
/upgrade-agent diagnostics
2 Universal agents my-agent Workspace ⚠ regex-shell-pattern: ^git\s strict-dev Global ⚠ deny-by-default-readonly
| Avertissement | Signification | Que faire |
|---|---|---|
regex-shell-pattern | Un regex de shell a été approximé en tant que glob | Vérifiez le modèle converti dans permissions.rules |
regex-web-pattern | Un regex d'URL a été approximé en tant que glob | Vérifiez le modèle d'URL converti |
unconvertible-pattern | Un regex n'a pas pu être converti de façon sûre | Ajoutez manuellement la règle à permissions.rules |
unmapped-allowed-tool | Une 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-tool | L'outil aws / use_aws est déprécié | Supprimez la référence à l'outil déprécié |
deny-by-default-readonly | Paramètres de refus par défaut et d'autorisation automatique en lecture seule en conflit | Vérifiez votre intention de permission et ajustez manuellement |
file-prompt | Les chemins de requête de fichier absolus ou ~/ peuvent ne pas se résoudre dans tous les environnements | Utilisez plutôt des chemins relatifs |
unconvertible-hook | Un Hook n'a pas pu être converti au nouveau format | Recréez le Hook en utilisant le format de déclenchement pris en charge |
Les éléments suivants sont exclus de l'analyse :
.bak) sont exclus de l'analyseprompt, tools, hooks, ou champs de permission) sont ignorésTous vos agents sont déjà dans le dernier format. Exécutez /upgrade-agent diagnostics pour examiner leur état actuel.
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.
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.
Mise à niveau des configs d'agent