Passer au contenu principal
Afficher en Markdown

Référence de configuration de l'agent

Cette référence documente le format de configuration de l'agent pour l'IDE 1.0 et la CLI V3. Si vous avez des configurations d'agent plus anciennes, utilisez la commande /upgrade-agent pour les migrer.

Comparaison des versions

Nouveau dans l'IDE 1.0 / CLI V3 :

ChampDescription
permissionsRègles de contrôle d'accès basées sur les capacités (remplace toolsSettings)
excludedToolsExclut des outils spécifiques même lorsque tools les autorise
includeMcpJsonInclut automatiquement les serveurs MCP de l'espace de travail
includePowersInclut automatiquement les Powers installés dans l'IDE
welcomeMessageMessage d'accueil personnalisé au démarrage de la session
resources (élargi)Prend maintenant en charge skill:// et knowledgeBase en plus de file://
Format Markdown (.md)Frontmatter pour la configuration, corps pour la requête système
Balises dans toolsNoms courts : read, write, shell, web, @builtin, *

Champs de migration de CLI 2.x :

ChampTraitement par la CLI V3
toolsSettings/upgrade-agent convertit les paramètres shell, de fichiers et subagent pris en charge en permissions.rules et tools
allowedTools/upgrade-agent convertit les entrées en règles allow au niveau des capacités; les nouveaux profils utilisent permissions
toolAliasesNe fait pas partie du schéma de la CLI V3; utilisez des sélecteurs d'outils complets
keyboardShortcutNe fait pas partie du schéma de la CLI V3

Inchangé : name, description, prompt, model, mcpServers

Les hooks en ligne ont des formes actuelle et héritée distinctes; consultez Champ Hooks. Pour l'automatisation commune à plusieurs surfaces, utilisez des fichiers de Hooks autonomes.

Utilisez /upgrade-agent pour migrer les champs pris en charge dans les configurations plus anciennes.

Format Markdown

Une configuration d'agent peut être un fichier JSON ou un fichier Markdown avec un en-tête YAML. En Markdown, l'en-tête contient les champs de configuration actuels pris en charge, et le corps du document est la requête système. En JSON, la requête système se trouve dans le champ prompt. Utilisez Markdown lorsque la requête système est longue ou que vous voulez la lire comme de la prose; JSON convient aux configurations générées.

.kiro/agents/backend-dev.md :

markdown
--- name: backend-dev description: Backend development agent model: claude-sonnet-4.6 tools: ["read", "write", "shell", "web"] excludedTools: ["knowledge"] includeMcpJson: true includePowers: false mcpServers: postgres: command: npx args: ["-y", "@modelcontextprotocol/server-postgres"] env: DATABASE_URL: "${DATABASE_URL}" resources: - file://./ARCHITECTURE.md - skill://backend-patterns permissions: rules: - capability: shell match: ["npm *", "node *"] effect: allow welcomeMessage: "Ready to work on backend code." --- You are a backend developer focused on Node.js and TypeScript. Always use async/await. All database queries must be parameterized.

Le champ tools décide quels outils l'agent peut voir et appeler; le champ permissions décide ce que ces outils peuvent faire lorsqu'ils sont appelés. Les deux utilisent des noms différents : tools prend des sélecteurs comme read, write, shell, web, @mcp, @builtin et *, tandis que permissions prend des noms de capacités comme fs_read, fs_write et shell. Pour les outils couverts par chaque sélecteur, consultez Configuration de l'accès aux outils.

Référence des champs

Chaque fichier de configuration d'agent peut inclure les sections suivantes :

  • name - Le nom de l'agent (optionnel, dérivé du nom de fichier si non spécifié).
  • description - Une description de l'agent.
  • prompt - Contexte de haut niveau pour l'agent.
  • mcpServers - Les serveurs MCP auxquels l'agent a accès.
  • tools - Les outils disponibles pour l'agent.
  • toolAliases - Remappage hérité des noms d'outils de CLI 2.x.
  • allowedTools - Entrées de préapprobation héritées de CLI 2.x; migrez-les vers permissions.
  • permissions - Règles de contrôle d'accès basées sur les capacités, en ligne.
  • toolsSettings - Configuration par outil héritée de CLI 2.x; ignorée par la CLI V3.
  • resources - Ressources disponibles pour l'agent.
  • hooks - Commandes exécutées à des points de déclenchement spécifiques.
  • includeMcpJson - Indique s'il faut inclure les serveurs MCP des fichiers mcp.json.
  • model - L'ID du modèle à utiliser pour cet agent.
  • keyboardShortcut - Raccourci hérité de CLI 2.x pour changer d'agent.
  • welcomeMessage - Message affiché lors du passage à cet agent.

Champ Name

Le champ name spécifie le nom de l'agent. Il est utilisé à des fins d'identification et d'affichage.

json
{ "name": "aws-expert" }

Champ Description

Le champ description fournit une description de ce que fait l'agent. Ceci est principalement destiné à la lisibilité humaine et aide les utilisateurs à distinguer les différents agents.

json
{ "description": "An agent specialized for AWS infrastructure tasks" }

Champ Prompt

Le champ prompt est destiné à fournir un contexte de haut niveau à l'agent, similaire à une requête système. Il prend en charge à la fois le texte en ligne et les URI file:// pour référencer des fichiers externes.

Requête en ligne

json
{ "prompt": "You are an expert AWS infrastructure specialist" }

Requête par URI de fichier

Vous pouvez référencer des fichiers externes à l'aide d'URI file://. Cela vous permet de maintenir des requêtes longues et complexes dans des fichiers séparés pour une meilleure organisation et un meilleur contrôle des versions, tout en gardant la configuration de votre agent propre et lisible.

json
{ "prompt": "file://./my-agent-prompt.md" }

Résolution des chemins d'URI de fichier

  • Chemins relatifs : Résolus par rapport au répertoire du fichier de configuration de l'agent
    • "file://./prompt.md" - prompt.md dans le même répertoire que la configuration de l'agent
    • "file://../shared/prompt.md" - prompt.md dans un répertoire parent
  • Chemins absolus : Utilisés tels quels
    • "file:///home/user/prompts/agent.md" - Chemin absolu vers le fichier

Exemples d'URI de fichier

json
{ "prompt": "file://./prompts/aws-expert.md" }
json
{ "prompt": "file:///Users/developer/shared-prompts/rust-specialist.md" }

Champ McpServers

Le champ mcpServers spécifie les serveurs Model Context Protocol (MCP) auxquels l'agent a accès. Chaque serveur est défini avec une commande et des arguments optionnels.

json
{ "mcpServers": { "fetch": { "command": "fetch3.1", "args": [] }, "git": { "command": "git-mcp", "args": [], "env": { "GIT_CONFIG_GLOBAL": "/dev/null" }, "timeout": 120000 } } }

Chaque configuration de serveur MCP peut inclure :

  • command (requis pour les serveurs locaux) : La commande à exécuter pour démarrer le serveur MCP
  • url (pour les serveurs distants) : Le point de terminaison HTTP, avec des headers optionnels pour les points de terminaison authentifiés
  • args (optionnel) : Arguments à passer à la commande
  • env (optionnel) : Variables d'environnement à définir pour le serveur. Les valeurs prennent en charge la syntaxe ${VAR} et se développent au moment de l'exécution, gardant les secrets hors du fichier de configuration
  • timeout (optionnel) : Délai d'expiration de la poignée de main de connexion pour les serveurs stdio et HTTP en millisecondes (par défaut : 60000)
  • requestTimeout (optionnel) : Délai d'expiration de requête par appel en millisecondes (par défaut : 120000)
  • oauth (optionnel) : Configuration OAuth pour les serveurs MCP basés sur HTTP
    • clientId (optionnel) : ID client OAuth préenregistré utilisé comme solution de repli lorsque l'enregistrement dynamique de client (DCR) échoue. Requis pour les services comme Slack, GitHub et Figma qui ne prennent pas en charge le DCR et émettent des identifiants OAuth via un enregistrement d'application manuel.
    • redirectUri (optionnel) : URI de redirection personnalisé pour le flux OAuth (p. ex., « 127.0.0.1:7778 »)
  • oauthScopes (optionnel) : Tableau de portées OAuth à demander (p. ex., ["read", "write"]). Il s'agit d'un champ de premier niveau sur l'entrée du serveur — un frère de oauth, non imbriqué à l'intérieur.

Configuration OAuth

Pour les serveurs MCP basés sur HTTP qui nécessitent une authentification OAuth, vous pouvez configurer des portées OAuth :

json
{ "mcpServers": { "github": { "type": "http", "url": "https://api.github.com/mcp", "oauth": { "redirectUri": "127.0.0.1:8080" }, "oauthScopes": ["repo", "user"] } } }

Si vous rencontrez des erreurs liées aux portées OAuth, vous pouvez configurer un tableau vide pour contourner les exigences de portée dans la configuration du serveur MCP :

json
{ "mcpServers": { "github": { "type": "http", "url": "https://api.github.com/mcp", "oauth": { "redirectUri": "127.0.0.1:8080" }, "oauthScopes": [] } } }

Pour les services qui nécessitent une application OAuth préenregistrée, définissez oauth.clientId sur l'ID de votre application :

json
{ "mcpServers": { "slack": { "type": "http", "url": "https://mcp.slack.com/mcp", "oauth": { "clientId": "your-slack-app-client-id" }, "oauthScopes": ["search:read", "channels:read"] } } }

Champ Tools

Le champ tools répertorie tous les outils que l'agent peut potentiellement utiliser. Les outils incluent les outils intégrés et les outils des serveurs MCP.

  • Les outils intégrés sont spécifiés par leur nom (p. ex., read, shell)
  • Les outils de serveur MCP sont préfixés par @ suivi du nom du serveur (p. ex., @git)
  • Pour spécifier un outil précis d'un serveur MCP, utilisez @server_name/tool_name
  • Utilisez * comme caractère générique spécial pour inclure tous les outils disponibles (intégrés et provenant de serveurs MCP)
  • Utilisez @builtin pour inclure tous les outils intégrés
  • Utilisez @server_name pour inclure tous les outils d'un serveur MCP spécifique

Les balises de catégorie comprennent read, write, shell, web et subagent. Les outils intégrés comme knowledge sont sélectionnés par leur ID d'outil direct. Utilisez @mcp pour tous les outils MCP, @builtin pour tous les outils intégrés ou * pour tout. Consultez Outils intégrés pour l'appartenance aux catégories et le comportement des sélecteurs qui font autorité.

json
{ "tools": [ "read", "write", "shell", "@git", "@rust-analyzer/check_code" ] }

Pour inclure tous les outils disponibles, utilisez :

json
{ "tools": ["*"] }

Champ ToolAliases

Le champ toolAliases est un champ hérité de CLI 2.x et n'est pas appliqué par la CLI V3. Les exemples de cette section documentent des profils plus anciens; les profils actuels doivent utiliser des sélecteurs d'outils complets.

Par exemple, si les serveurs @github-mcp et @gitlab-mcp fournissent tous deux un outil appelé get_issues, vous aurez une collision de noms. Vous pouvez utiliser toolAliases pour les distinguer :

json
{ "toolAliases": { "@github-mcp/get_issues": "github_issues", "@gitlab-mcp/get_issues": "gitlab_issues" } }

Avec cette configuration, les outils seront disponibles pour l'agent sous les noms github_issues et gitlab_issues au lieu d'avoir une collision sur get_issues.

Vous pouvez également utiliser des alias pour créer des noms plus courts ou plus intuitifs pour les outils fréquemment utilisés :

json
{ "toolAliases": { "@aws-cloud-formation/deploy_stack_with_parameters": "deploy_cf", "@kubernetes-tools/get_pod_logs_with_namespace": "pod_logs" } }

La clé est le nom d'outil original (y compris le préfixe du serveur pour les outils MCP), et la valeur est le nouveau nom à utiliser.

Champ AllowedTools

Le champ allowedTools appartient à CLI 2.x. Les nouveaux profils de la CLI V3 utilisent des permissions.rules basées sur les capacités. Un profil JSON CLI 2.x contenant allowedTools sans bloc permissions est ignoré par la V3 jusqu'à ce que /upgrade-agent le convertisse. Les motifs ci-dessous documentent le champ hérité.

json
{ "allowedTools": [ "read", "write", "@git/git_status", "@server/read_*", "@fetch" ] }

Vous pouvez autoriser des outils en utilisant plusieurs motifs :

Correspondances exactes

  • Outils intégrés : "read", "shell", "knowledge"
  • Outils MCP spécifiques : "@server_name/tool_name" (p. ex., "@git/git_status")
  • Tous les outils d'un serveur MCP : "@server_name" (p. ex., "@fetch")

Motifs génériques

Le champ allowedTools prend en charge les motifs génériques de style glob utilisant * et ? :

Motifs d'outils MCP

  • Préfixe d'outil : "@server/read_*" - correspond à @server/read_file, @server/read_config
  • Suffixe d'outil : "@server/*_get" - correspond à @server/issue_get, @server/data_get
  • Motif de serveur : "@*-mcp/read_*" - correspond à @git-mcp/read_file, @db-mcp/read_data
  • Tout outil des serveurs correspondant au motif : "@git-*/*" - correspond à tout outil des serveurs correspondant à git-*

Facultativement, vous pouvez également préfixer les outils natifs avec l'espace de noms @builtin.

Exemples

json
{ "allowedTools": [ "read", "knowledge", "@server/specific_tool", "r*", "w*", "@builtin", "@server/api_*", "@server/read_*", "@git-server/get_*_info", "@*/status", "@fetch", "@git-*" ] }

Règles de correspondance de motifs

  • * correspond à toute séquence de caractères (y compris aucun)
  • ? correspond exactement à un caractère
  • Les correspondances exactes ont priorité sur les motifs
  • Les permissions au niveau du serveur (@server_name) autorisent tous les outils de ce serveur
  • Correspondance sensible à la casse

Contrairement au champ tools, le champ allowedTools ne prend pas en charge le caractère générique "*" pour autoriser tous les outils. Pour autoriser des outils, vous devez utiliser des motifs spécifiques ou des permissions au niveau du serveur.

Champ ToolsSettings

Le champ toolsSettings fournit une configuration par outil dans CLI 2.x, comme les listes d'autorisation et de refus de commandes shell, les restrictions de chemins de fichiers et l'accès aux sous-agents. La CLI V3 ignore toolsSettings. Un profil JSON CLI 2.x contenant toolsSettings sans bloc permissions est ignoré par la V3 jusqu'à ce que /upgrade-agent le convertisse.

json
{ "toolsSettings": { "@git/git_status": { "git_user": "$GIT_USER" }, "subagent": { "availableAgents": ["reviewer", "tester"], "trustedAgents": ["reviewer"] } } }

Dans la CLI V3, exprimez plutôt les paramètres subagent avec tools et permissions. Consultez Configuration de l'accès aux sous-agents.

json
{ "tools": ["read", "write", "shell", "web", "subagent/reviewer", "subagent/tester"], "permissions": { "rules": [ { "capability": "subagent", "match": ["reviewer"], "effect": "allow" } ] } }

Champ Permissions

Le champ permissions fournit des règles de politique en ligne basées sur les capacités, intégrées dans le profil de l'agent. Cela remplace l'ancienne approche toolsSettings pour contrôler ce que les outils peuvent faire.

Les règles utilisent la même syntaxe que les fichiers permissions.yaml (voir Permissions) mais sont limitées à cet agent uniquement.

json
{ "permissions": { "rules": [ { "capability": "shell", "match": ["npm *", "git *"], "effect": "allow" }, { "capability": "fs_write", "match": ["src/**", "tests/**"], "effect": "allow" }, { "capability": "shell", "match": ["rm -rf *", "sudo *"], "effect": "deny" } ] } }

Chaque règle comprend :

ChampDescription
capabilityLa capacité à contrôler : fs_read, fs_write, shell, web_fetch, web_search, mcp, subagent, skill, power, context, diagnostics, sandbox_network; ou les métacapacités all, builtin et filesystem. Consultez Autorisations.
matchMotifs glob délimitant la règle (chemins de fichiers pour fs, préfixes de commandes pour shell, noms de serveur/outil pour MCP)
effectallow (procéder silencieusement), ask (demander à l'utilisateur), ou deny (bloquer toujours)
excludeMotifs glob optionnels qui ne doivent PAS correspondre

Les permissions à l'échelle de l'agent prennent en charge les trois effets (allow, ask, deny). L'algorithme de priorité au refus s'applique : un deny dans n'importe quelle portée l'emporte, indépendamment des règles allow ailleurs.

Lorsque cet agent s'exécute comme sous-agent dans la CLI V3 ou l'IDE, Kiro vérifie aussi chacun de ses appels d'outils par rapport à la politique de la session parente, et le résultat le plus strict l'emporte. Les règles allow de l'agent n'accordent rien que la session parente n'autorise pas. Consultez Autorisations des sous-agents.

Champ Resources

Le champ resources donne à un agent l'accès à des ressources locales. Les ressources peuvent être des fichiers, des skills ou des bases de connaissances.

json
{ "resources": [ "file://README.md", "file://.kiro/steering/**/*.md", "skill://.kiro/skills/**/SKILL.md" ] }

Les ressources prennent en charge différents types via des schémas d'URI :

  • file:// - Fichiers chargés directement dans le contexte au démarrage
  • skill:// - Skills avec métadonnées chargées au démarrage, contenu complet chargé à la demande

Les deux prennent en charge :

  • Chemins spécifiques : file://README.md ou skill://my-skill.md
  • Motifs glob : file://.kiro/**/*.md ou skill://.kiro/skills/**/SKILL.md
  • Chemins absolus ou relatifs

Ressources de fichiers

Les ressources de fichiers sont chargées directement dans le contexte de l'agent au démarrage de l'agent. Utilisez-les pour le contenu dont l'agent a toujours besoin.

Dans Kiro CLI 3.1.0 ou une version ultérieure, un agent charge au plus 32 fichiers de ressources file:// et 100 000 caractères au total. Kiro charge au plus 50 000 caractères d'un même fichier, en tronquant les fichiers plus longs, et ignore tout fichier de plus de 1 Mio. Lorsque la limite du nombre de fichiers ou du nombre total de caractères est atteinte, il cesse de charger les fichiers de ressources suivants.

json
{ "resources": [ "file://README.md", "file://docs/**/*.md" ] }

Dans Kiro IDE 1.4.86 et les versions ultérieures, un agent charge au plus 32 fichiers de ressources file:// et 100 000 caractères de ceux-ci. Chaque fichier est limité à 1 Mio et à 50 000 caractères.

  • Un fichier de plus de 1 Mio n'est pas chargé. Un marqueur à sa place nomme le fichier.
  • Un fichier de plus de 50 000 caractères est coupé pour tenir dans la limite et se termine par un marqueur qui l'indique.
  • Lorsque le total de 32 fichiers ou de 100 000 caractères est atteint, Kiro s'arrête au premier fichier qui ne tient pas et ne charge pas les fichiers de ressources restants. Un marqueur explique que les fichiers restants n'ont pas été chargés.

Chaque marqueur indique à l'agent de lire le fichier directement pour voir le reste.

Un agent personnalisé qui s'exécute comme sous-agent et déclare ses propres ressources file:// charge ces fichiers à la place des ressources file:// de l'agent parent. Un sous-agent qui ne déclare aucune ressource file:// hérite des ressources file:// de l'agent parent.

Ressources de skills

Les skills sont chargés progressivement - seules les métadonnées (nom et description) sont chargées au démarrage, le contenu complet étant chargé à la demande lorsque l'agent détermine que c'est nécessaire. Cela permet de garder le contexte allégé tout en donnant aux agents accès à une documentation étendue.

Les fichiers de skill doivent commencer par un frontmatter YAML contenant name et description :

markdown
--- name: dynamodb-data-modeling description: Guide for DynamoDB data modeling best practices. Use when designing or analyzing DynamoDB schema. --- # DynamoDB Data Modeling ... full content here ...
json
{ "resources": [ "skill://.kiro/skills/**/SKILL.md" ] }

Rédigez des descriptions précises afin que l'agent puisse déterminer de manière fiable quand charger le contenu complet.

Ressources de base de connaissances

Les ressources de base de connaissances permettent aux agents de rechercher dans de la documentation et du contenu indexés. Avec la prise en charge de millions de jetons de contenu indexé et le chargement incrémentiel, les agents peuvent rechercher efficacement dans de grands ensembles de documentation.

json
{ "resources": [ { "type": "knowledgeBase", "source": "file://./docs", "name": "ProjectDocs", "description": "Project documentation and guides", "indexType": "best", "autoUpdate": true } ] }

Champs :

ChampRequisDescription
typeOuiDoit être "knowledgeBase"
sourceOuiChemin à indexer. Utilisez le préfixe file:// pour les chemins locaux
nameOuiNom d'affichage de la base de connaissances
descriptionNonBrève description du contenu
indexTypeNonStratégie d'indexation : "best" (par défaut, meilleure qualité) ou "fast" (indexation plus rapide)
autoUpdateNonRéindexe lorsque l'agent démarre. Par défaut : false

Cas d'usage :

  • Partager la documentation d'équipe entre les agents
  • Donner aux agents accès à un contexte propre au projet (specs, décisions, notes de réunion)
  • Indexer de grandes bases de code et de la documentation
  • Garder les connaissances de l'agent à jour avec autoUpdate: true

Champ Hooks

Le champ hooks ajoute des Hooks en ligne à la portée du profil dans la CLI V3. Utilisez le format de tableau actuel avec des déclencheurs en PascalCase. Pour l'automatisation qui doit fonctionner indépendamment d'un profil d'agent particulier ou à la fois dans l'IDE et la CLI, utilisez plutôt un fichier autonome .kiro/hooks/*.json.

json
{ "hooks": [ { "name": "git-status", "trigger": "SessionStart", "action": { "type": "command", "command": "git status" } }, { "name": "audit-shell", "trigger": "PreToolUse", "matcher": "^(execute_bash|execute_pwsh)$", "action": { "type": "command", "command": "{ echo \"$(date) - Shell call:\"; cat; echo; } >> /tmp/shell_audit_log" } }, { "name": "format-writes", "trigger": "PostToolUse", "matcher": "^(fs_write|fs_append|str_replace|delete_file)$", "action": { "type": "command", "command": "cargo fmt --all" } } ] }

Chaque Hook en ligne utilise les mêmes champs de définition qu'un Hook autonome :

  • name (requis) : Identifiant lisible par un humain.
  • trigger (requis) : Nom de déclencheur en PascalCase, comme SessionStart, PreToolUse ou PostToolUse.
  • matcher (optionnel) : Sélecteur d'outil (ID d'outil, balise de catégorie comme shell, @mcp, @<server> ou le caractère générique *) ou expression régulière comparée à l'ID d'outil pour les déclencheurs d'utilisation d'outil. Consultez Types de Hooks.
  • action (requis) : Une action de type commande ou agent. Consultez Actions des Hooks.

Les Hooks intégrés de CLI 2.x utilisaient un objet dont les clés étaient des noms d'événements en camelCase comme agentSpawn, preToolUse et postToolUse. La CLI V3 reconnaît toujours cette forme héritée en entrée à des fins de compatibilité, et /upgrade-agent convertit les Hooks en forme d'objet vers le format de tableau actuel.

Dans un profil CLI 2.x hérité, un matcher use_aws ciblait l'outil AWS structuré intégré; aws était son alias privilégié. Cet outil n'est pas un outil intégré de la V3, de sorte que conserver le matcher ne le rend pas disponible. Remplacez la référence à l'outil AWS pendant la migration et utilisez le nom actuel de l'outil shell ou MCP dans le Hook converti.

Champ includeMcpJson

Le champ includeMcpJson détermine s'il faut inclure les serveurs MCP définis dans les fichiers de configuration MCP (~/.kiro/settings/mcp.json pour la portée globale et <cwd>/.kiro/settings/mcp.json pour l'espace de travail).

json
{ "includeMcpJson": true }

Lorsqu'il est défini à true, l'agent aura accès à tous les serveurs MCP définis dans les configurations globales et locales, en plus de ceux définis dans le champ mcpServers de l'agent.

Champ Model

Le champ model spécifie l'ID du modèle à utiliser pour cet agent. Si non spécifié, l'agent utilisera le modèle par défaut.

json
{ "model": "claude-sonnet-4.6" }

L'ID du modèle doit correspondre à l'un des modèles disponibles retournés par le service de modèles de Kiro. Vous pouvez voir les modèles disponibles en utilisant la commande /model dans une session de clavardage active.

Si le modèle spécifié n'est pas disponible, la première requête peut échouer au lieu de revenir automatiquement à un autre modèle. Kiro restaure le modèle qui était actif avant l'application de l'épinglage de l'agent; réessayez pour utiliser ce modèle restauré, ou choisissez un autre modèle avec /model ou mettez à jour le champ model de l'agent.

Champ KeyboardShortcut

Le champ keyboardShortcut appartient à CLI 2.x et ne fait pas partie du schéma de profil de la CLI V3. Les détails ci-dessous documentent les profils hérités.

json
{ "keyboardShortcut": "ctrl+a" }

Les raccourcis se composent d'un modificateur et d'une touche, séparés par + :

Modificateurs (optionnels) :

  • ctrl - Touche Contrôle
  • shift - Touche Maj

Touches :

  • Lettre unique : a-z (insensible à la casse)
  • Chiffre unique : 0-9

Exemples :

json
{ "keyboardShortcut": "ctrl+a" }
json
{ "keyboardShortcut": "shift+b" }

Comportement de bascule :

Lorsque vous appuyez sur un raccourci clavier :

  • Si vous êtes sur un agent différent : passe à cet agent
  • Si vous êtes déjà sur cet agent : revient à votre agent précédent

Gestion des conflits :

Si plusieurs agents ont le même raccourci clavier, un avertissement est journalisé et le raccourci est désactivé. Utilisez /agent swap pour changer manuellement dans ce cas.

Champ WelcomeMessage

Le champ welcomeMessage spécifie un message affiché lors du passage à cet agent.

json
{ "welcomeMessage": "What would you like to build today?" }

Ce message apparaît après la confirmation du changement d'agent, aidant à orienter les utilisateurs vers le but de l'agent.

Désactivation de l'héritage des ressources par défaut

Par défaut, les agents personnalisés héritent des ressources par défaut (fichiers de steering, skills et AGENTS.md) en plus de leurs propres ressources configurées. Vous pouvez désactiver ce comportement avec le paramètre CLI chat.disableInheritingDefaultResources.

PropriétéValeur
Clé de paramètrechat.disableInheritingDefaultResources
TypeBooléen
Par défautfalse (les agents personnalisés héritent des ressources par défaut)
PortéeGlobale ou remplaçable par espace de travail

Définissez-le via la CLI :

bash
kiro-cli settings chat.disableInheritingDefaultResources true

Ou limitez-le à un espace de travail :

bash
kiro-cli settings --workspace chat.disableInheritingDefaultResources true

Lorsqu'il est défini à true, les agents personnalisés (définis par l'utilisateur) ne recevront pas le steering par défaut, les skills, ni AGENTS.md dans leur contexte. Les agents intégrés héritent toujours des ressources par défaut, indépendamment de ce paramètre.

Exemple complet

json
{ "name": "aws-rust-agent", "description": "A specialized agent for AWS and Rust development tasks", "mcpServers": { "fetch": { "command": "fetch3.1", "args": [] }, "git": { "command": "git-mcp", "args": [] } }, "tools": [ "read", "write", "shell", "@git", "@fetch/fetch_url" ], "permissions": { "rules": [ { "capability": "mcp", "match": ["git/git_status"], "effect": "allow" }, { "capability": "shell", "match": ["cargo *", "git *"], "effect": "allow" }, { "capability": "fs_write", "match": ["src/**", "tests/**", "Cargo.toml"], "effect": "allow" }, { "capability": "shell", "match": ["rm -rf *"], "effect": "deny" } ] }, "resources": [ "file://README.md", "file://docs/**/*.md" ], "hooks": [ { "name": "git-status", "trigger": "SessionStart", "action": { "type": "command", "command": "git status" } }, { "name": "format-writes", "trigger": "PostToolUse", "matcher": "^(fs_write|fs_append|str_replace|delete_file)$", "action": { "type": "command", "command": "cargo fmt --all" } } ], "includeMcpJson": true, "model": "claude-sonnet-4.6", "welcomeMessage": "Ready to help with AWS and Rust development!" }

Bonnes pratiques

  1. Commencez de façon restrictive : Commencez avec un accès minimal aux outils et élargissez-le selon les besoins
  2. Nommez clairement : Utilisez des noms descriptifs qui indiquent le but de l'agent
  3. Documentez l'usage : Ajoutez des descriptions claires pour aider les membres de l'équipe à comprendre l'agent
  4. Contrôle des versions : Stockez les configurations d'agent dans le dépôt de votre projet
  5. Testez minutieusement : Vérifiez que les permissions d'outils fonctionnent comme prévu avant de les partager

Agents locaux vs globaux

Utilisez des agents locaux pour :

  • Les configurations propres à un projet
  • Les agents nécessitant des fichiers/outils du projet
  • Les environnements de développement avec des exigences uniques
  • Le partage avec l'équipe via le contrôle des versions

Utilisez des agents globaux pour :

  • Les agents à usage général sur plusieurs projets
  • Les agents de productivité personnelle
  • Les agents sans contexte propre à un projet
  • Les outils et flux de travail couramment utilisés

Bonnes pratiques de sécurité

  • Examinez soigneusement les permissions.rules au niveau des capacités
  • Préférez des motifs spécifiques aux caractères génériques
  • Utilisez permissions.rules pour restreindre les opérations sensibles
  • Testez les agents dans des environnements sûrs d'abord

Permissions des outils d'écriture

Utilisez permissions.rules pour préapprouver seulement les opérations d'écriture dont l'agent a besoin. Les autres opérations d'écriture nécessitent une approbation au moment de l'exécution et demeurent soumises à toute règle deny correspondante.

Lorsque vous activez des outils d'écriture (comme write, shell, ou des outils MCP avec des capacités d'écriture), l'agent fonctionne avec les mêmes permissions de système de fichiers que votre compte utilisateur. Cela signifie :

  • L'agent peut lire et modifier tous les fichiers sous ~/.kiro, y compris les fichiers de contexte de skills, les fichiers de steering, les configurations de serveur MCP (mcp.json), et d'autres configurations d'agent.
  • Tous les skills et ressources installés partagent les mêmes permissions. Il n'y a pas d'isolation entre les skills individuels - le contexte de n'importe quel skill peut être lu ou modifié par l'agent lorsque les outils d'écriture sont activés.
  • Un skill ne peut pas exécuter de code par lui-même. Les skills sont des fichiers texte qui fournissent des instructions à l'agent. Cependant, si des outils d'écriture comme shell sont autorisés, l'agent pourrait exécuter des commandes référencées dans n'importe quel skill chargé.

Pour réduire les risques lors de l'utilisation d'outils d'écriture :

  • Activez uniquement les outils d'écriture spécifiques dont vous avez besoin (p. ex., "write" mais pas "shell").
  • Définissez des restrictions de chemins et de commandes avec permissions.rules en utilisant des motifs match étroits.
  • Examinez les skills et les ressources avant de les installer, en particulier de sources non fiables.
  • Utilisez les Hooks PreToolUse pour auditer ou bloquer les opérations sensibles.

Migration depuis des configurations plus anciennes

Si vous avez des configurations d'agent créées avant l'IDE 1.0 ou la CLI V3, /upgrade-agent identifie les configurations nécessitant une migration, sauvegarde les originaux et convertit les champs pris en charge sur place.

bash
# Scan agents and open the selection menu /upgrade-agent # Review previously upgraded agents and any conversion warnings /upgrade-agent diagnostics

La commande 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 nécessitant une mise à niveau apparaissent.

Les profils CLI 2.x hérités peuvent apparaître dans le sélecteur /agent de la V3, mais les profils comportant des champs de confiance non pris en charge se replient sur un autre agent jusqu'à ce que /upgrade-agent les convertisse. /upgrade-agent aplatit les Hooks en forme d'objet en un tableau de documents de Hooks. Il préserve la chaîne de déclencheur camelCase héritée comme alias de compatibilité; utilisez PascalCase lorsque vous rédigez à la main ou révisez le Hook migré.

Avant :

json
{ "hooks": { "agentSpawn": [ { "command": "git status" } ] } }

Après /upgrade-agent :

json
{ "hooks": [ { "name": "agentSpawn-0", "trigger": "agentSpawn", "action": { "type": "command", "command": "git status" }, "timeout": 10 } ] }

La V3 de Kiro accepte l'alias agentSpawn émis. Pour une nouvelle configuration, renommez-le SessionStart et remplacez le nom généré par un nom qui décrit le but du Hook.

Ce qui est converti

Ancien motifNouvel équivalent
toolsSettings.shell.allowedCommandspermissions.rules avec capability: shell, effect: allow
toolsSettings.shell.deniedCommandspermissions.rules avec capability: shell, effect: deny
toolsSettings.write.allowedPathspermissions.rules avec capability: fs_write, effect: allow
Entrées allowedToolsRègles d'autorisation au niveau des capacités
toolsSettings.subagent.trustedAgentspermissions.rules avec capability: subagent, effect: allow. Saute seulement l'invite de démarrage du sous-agent
toolsSettings.subagent.availableAgentsEntrées subagent/<name> dans tools, en remplacement de subagent. Ne limite pas la création si tools contient aussi @builtin ou *
Noms d'outils de CLI 2.x (fs_read, execute_bash)Sélecteurs actuels (read, shell) choisis par /upgrade-agent
autoAllowReadonlyRègle de politique shell en lecture seule
Hooks au format objetTableau plat de documents de Hooks; les alias de déclencheurs hérités restent acceptés

Les fichiers originaux sont sauvegardés dans <filename>.json.bak. Pour revenir en arrière, renommez la sauvegarde.

Pour le guide complet de mise à niveau, y compris les diagnostics et le dépannage, consultez Mise à niveau des configurations d'agent.

Prochaines étapes

Page mise à jour : 6 novembre 2026