Les profils d'agent CLI 3.0 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
La sous-commande run (par défaut) analyse .kiro/agents/ dans votre espace de travail et ~/.kiro/agents/ globalement, puis affiche un menu de sélection regroupé par portée. Seuls les agents qui doivent être mis à niveau apparaissent. Les agents déjà dans le dernier format sont masqués.
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.).
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