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.
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-agentoukiro-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 :
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.
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.
# 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
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 :
# 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.
Lorsque vous sélectionnez un groupe d'agents à mettre à niveau :
- Chaque fichier original est copié vers
<filename>.json.bakcomme sauvegarde - Les champs de permission du nouveau format sont ajoutés en plus de votre configuration existante
- 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
- 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.
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.
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 :
- Noms d'outils : Les anciens noms (comme
fs_read,execute_bash) sont mappés vers des balises de capacité v3 (commeread,shell). Les deux sont préservés pour la compatibilité. toolsSettings: Les règles d'autorisation/refus par outil deviennent des entréespermissions.rulesavec 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: Sitoolscontientsubagent, la migration le remplace par une entréesubagent/<name>pour chaque agent de la liste. Sitoolscontient aussi@builtinou*, l'agent peut tout de même démarrer n'importe quel agent au moyen deinvoke_sub_agent; remplacez donc ces entrées par des balises de catégorie commereadetshellpour 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
allowedCommandsouweb_fetch.trusteddevient un glob lorsqu'un glob y correspond exactement; dans une autorisation, un.isolé est lu comme un point littéral, de sorte quecat package.jsonreste 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 avertissementunconvertible-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_readpour./**, 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 rapportentskill-read-restrictions.
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 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)
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 ⚠ unconvertible-pattern: sleep [0-9]+ 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 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'outil | Pour 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-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 |
skill-read-restrictions | Les restrictions de lecture V2 pourraient atteindre des fichiers de Skills, de sorte que les Skills demandent une approbation dans V3 | Vérifiez la permission skill générée avant d'utiliser l'agent |
deny-by-default-trusted-shell | allowedTools fait confiance au shell, de sorte que V2 exécutait chaque commande ; V3 refuse toute commande absente de allowedCommands | Retirez denyByDefault, ou retirez shell de allowedTools et listez les commandes à autoriser |
hidden-tool | Un refus couvre tout ce que l'outil peut faire, de sorte que V3 retire l'outil de l'agent | Restreignez le refus, ou ajoutez les commandes ou les chemins à autoriser |
allow-read-only-dropped | allowReadOnly 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 approbation | Faites 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.
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.
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
Tous 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. 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.
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.
- Référence de configuration d'agent pour le format actuel de configuration d'agent, y compris le format Markdown
- Autorisations pour les règles de permission basées sur les capacités
- Agents personnalisés pour créer et gérer des agents
Mise à niveau des configs d'agent