Cette référence documente le format de configuration de l'agent pour l'IDE 1.0 et le CLI 3.0. Si vous avez des configurations d'agent plus anciennes, utilisez la commande /upgrade-agent pour les migrer.
Nouveau dans l'IDE 1.0 / CLI 3.0 :
| Champ | Description |
|---|---|
permissions | Règles de contrôle d'accès basées sur les capacités (remplace toolsSettings) |
excludedTools | Exclut des outils spécifiques même lorsque tools les autorise |
includeMcpJson | Inclut automatiquement les serveurs MCP de l'espace de travail |
includePowers | Inclut automatiquement les Powers installés dans l'IDE |
welcomeMessage | Message 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 tools | Noms courts : read, write, shell, web, @builtin, * |
Obsolète :
| Champ | Remplacement |
|---|---|
toolsSettings (règles shell/write) | permissions.rules avec des motifs basés sur les capacités |
Inchangé : name, description, prompt, model, mcpServers, toolAliases, allowedTools, keyboardShortcut, hooks (CLI uniquement - l'IDE ignore ce champ)
Utilisez /upgrade-agent pour migrer les champs pris en charge dans les configurations plus anciennes.
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 des noms d'outils pour gérer les collisions de noms.allowedTools - Les outils qui peuvent être utilisés sans demande de confirmation.permissions - Règles de contrôle d'accès basées sur les capacités, en ligne.toolsSettings - Configuration par outil (obsolète pour les règles shell/fs).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 clavier pour passer rapidement à cet agent.welcomeMessage - Message affiché lors du passage à cet agent.Le champ name spécifie le nom de l'agent. Il est utilisé à des fins d'identification et d'affichage.
{ "name": "aws-expert" }
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.
{ "description": "An agent specialized for AWS infrastructure tasks" }
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.
{ "prompt": "You are an expert AWS infrastructure specialist" }
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.
{ "prompt": "file://./my-agent-prompt.md" }
"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"file:///home/user/prompts/agent.md" - Chemin absolu vers le fichier{ "prompt": "file://./prompts/aws-expert.md" }
{ "prompt": "file:///Users/developer/shared-prompts/rust-specialist.md" }
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.
{ "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 MCPurl (pour les serveurs distants) : Le point de terminaison HTTP, avec des headers optionnels pour les points de terminaison authentifiésargs (optionnel) : Arguments à passer à la commandeenv (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 configurationtimeout (optionnel) : Délai d'expiration de la poignée de main de connexion pour les serveurs stdio 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.Pour les serveurs MCP basés sur HTTP qui nécessitent une authentification OAuth, vous pouvez configurer des portées OAuth :
{ "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 :
{ "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 :
{ "mcpServers": { "slack": { "type": "http", "url": "https://mcp.slack.com/mcp", "oauth": { "clientId": "your-slack-app-client-id" }, "oauthScopes": ["search:read", "channels:read"] } } }
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.
read, shell)@ suivi du nom du serveur (p. ex., @git)@server_name/tool_name* comme caractère générique spécial pour inclure tous les outils disponibles (intégrés et provenant de serveurs MCP)@builtin pour inclure tous les outils intégrés@server_name pour inclure tous les outils d'un serveur MCP spécifiqueLe champ accepte également des balises de catégorie. Chaque balise regroupe des capacités liées afin que vous n'ayez pas besoin d'énumérer les outils individuels :
| Balise | Ce qu'elle inclut |
|---|---|
read | Lecture de fichiers, listage de répertoires, recherche |
write | Écriture, modification, suppression de fichiers |
shell | Exécution de commandes et gestion des processus |
web | Récupération Web |
subagent | Délégation aux sous-agents |
knowledge | Outils de base de connaissances |
todo_list | Suivi des tâches |
@mcp | Tous les outils MCP de mcp.json |
@builtin | Tous les outils intégrés |
* | Tout |
Lorsque de nouveaux outils sont livrés sous une catégorie, les agents utilisant cette balise les récupèrent automatiquement.
{ "tools": [ "read", "write", "shell", "@git", "@rust-analyzer/check_code" ] }
Pour inclure tous les outils disponibles, utilisez :
{ "tools": ["*"] }
Le champ toolAliases est une fonctionnalité avancée qui vous permet de remapper les noms d'outils. Elle est principalement utilisée pour résoudre les collisions de noms entre les outils de différents serveurs MCP, ou pour créer des noms plus intuitifs pour des outils spécifiques.
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 :
{ "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 :
{ "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.
Le champ allowedTools spécifie quels outils peuvent être utilisés sans demander la permission à l'utilisateur. Il s'agit d'une fonctionnalité de sécurité qui aide à prévenir l'utilisation non autorisée des outils.
{ "allowedTools": [ "read", "write", "@git/git_status", "@server/read_*", "@fetch" ] }
Vous pouvez autoriser des outils en utilisant plusieurs motifs :
"read", "shell", "knowledge""@server_name/tool_name" (p. ex., "@git/git_status")"@server_name" (p. ex., "@fetch")Le champ allowedTools prend en charge les motifs génériques de style glob utilisant * et ? :
"@server/read_*" - correspond à @server/read_file, @server/read_config"@server/*_get" - correspond à @server/issue_get, @server/data_get"@*-mcp/read_*" - correspond à @git-mcp/read_file, @db-mcp/read_data"@git-*/*" - correspond à tout outil des serveurs correspondant à git-*Facultativement, vous pouvez également préfixer les outils natifs avec l'espace de noms @builtin.
{ "allowedTools": [ "read", "knowledge", "@server/specific_tool", "r*", "w*", "@builtin", "@server/api_*", "@server/read_*", "@git-server/get_*_info", "@*/status", "@fetch", "@git-*" ] }
* correspond à toute séquence de caractères (y compris aucun)? correspond exactement à un caractère@server_name) autorisent tous les outils de ce serveurContrairement 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.
Le champ toolsSettings fournit une configuration par outil. Dans les versions antérieures, il était utilisé pour les listes d'autorisation/refus de commandes shell et les restrictions de chemins de fichiers. Ces cas d'usage sont désormais gérés par le champ permissions.
Le champ est encore pris en charge pour les paramètres spécifiques aux outils MCP :
{ "toolsSettings": { "@git/git_status": { "git_user": "$GIT_USER" }, "subagent": { "availableAgents": ["reviewer", "tester"], "trustedAgents": ["reviewer"] } } }
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.
{ "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 :
| Champ | Description |
|---|---|
capability | La capacité à contrôler : fs_read, fs_write, shell, web_fetch, web_search, mcp, subagent, all |
match | Motifs glob délimitant la règle (chemins de fichiers pour fs, préfixes de commandes pour shell, noms de serveur/outil pour MCP) |
effect | allow (procéder silencieusement), ask (demander à l'utilisateur), ou deny (bloquer toujours) |
exclude | Motifs 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.
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.
{ "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émarrageskill:// - Skills avec métadonnées chargées au démarrage, contenu complet chargé à la demandeLes deux prennent en charge :
file://README.md ou skill://my-skill.mdfile://.kiro/**/*.md ou skill://.kiro/skills/**/SKILL.mdLes 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.
{ "resources": [ "file://README.md", "file://docs/**/*.md" ] }
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 :
--- 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 ...
{ "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.
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.
{ "resources": [ { "type": "knowledgeBase", "source": "file://./docs", "name": "ProjectDocs", "description": "Project documentation and guides", "indexType": "best", "autoUpdate": true } ] }
Champs :
| Champ | Requis | Description |
|---|---|---|
type | Oui | Doit être "knowledgeBase" |
source | Oui | Chemin à indexer. Utilisez le préfixe file:// pour les chemins locaux |
name | Oui | Nom d'affichage de la base de connaissances |
description | Non | Brève description du contenu |
indexType | Non | Stratégie d'indexation : "best" (par défaut, meilleure qualité) ou "fast" (indexation plus rapide) |
autoUpdate | Non | Réindexe lorsque l'agent démarre. Par défaut : false |
Cas d'usage :
autoUpdate: trueLe champ hooks définit les commandes à exécuter à des points de déclenchement spécifiques pendant le cycle de vie de l'agent et l'exécution des outils.
Le CLI et l'IDE acceptent tous deux les hooks écrits dans ce format, de sorte qu'un profil d'agent conçu pour Kiro CLI se charge dans l'IDE sans réécriture de ses hooks.
Pour des informations détaillées sur le comportement des hooks, les formats d'entrée/sortie et des exemples, consultez la documentation des Hooks.
{ "hooks": { "agentSpawn": [ { "command": "git status" } ], "userPromptSubmit": [ { "command": "ls -la" } ], "preToolUse": [ { "matcher": "execute_bash", "command": "{ echo \"$(date) - Bash command:\"; cat; echo; } >> /tmp/bash_audit_log" }, { "matcher": "use_aws", "command": "{ echo \"$(date) - AWS CLI call:\"; cat; echo; } >> /tmp/aws_audit_log" } ], "postToolUse": [ { "matcher": "fs_write", "command": "cargo fmt --all" } ] } }
Chaque hook est défini avec :
command (requis) : La commande à exécutermatcher (optionnel) : Motif pour faire correspondre les noms d'outils pour les hooks preToolUse et postToolUse. Les correspondances de hook utilisent les noms internes des outils (fs_read, fs_write, execute_bash, use_aws) plutôt que les noms simplifiés. Consultez la documentation des outils intégrés pour les noms d'outils disponibles.Déclencheurs de hooks disponibles :
agentSpawn : Déclenché à l'initialisation de l'agent.userPromptSubmit : Déclenché lorsque l'utilisateur soumet un message.preToolUse : Déclenché avant l'exécution d'un outil. Peut bloquer l'utilisation de l'outil.postToolUse : Déclenché après l'exécution d'un outil.stop : Déclenché lorsque l'assistant termine sa réponse.Le champ includeMcpJson déterminine 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).
{ "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.
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.
{ "model": "claude-sonnet-4" }
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, l'agent reviendra au modèle par défaut et affichera un avertissement.
Le champ keyboardShortcut configure un raccourci clavier pour passer rapidement à cet agent pendant une session de clavardage.
{ "keyboardShortcut": "ctrl+a" }
Les raccourcis se composent d'un modificateur et d'une touche, séparés par + :
Modificateurs (optionnels) :
ctrl - Touche Contrôleshift - Touche MajTouches :
a-z (insensible à la casse)0-9Exemples :
"keyboardShortcut": "ctrl+a" "keyboardShortcut": "shift+b"
Comportement de bascule :
Lorsque vous appuyez sur un raccourci clavier :
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.
Le champ welcomeMessage spécifie un message affiché lors du passage à cet agent.
{ "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.
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ètre | chat.disableInheritingDefaultResources |
| Type | Booléen |
| Par défaut | false (les agents personnalisés héritent des ressources par défaut) |
| Portée | Globale ou remplaçable par espace de travail |
Définissez-le via le CLI :
kiro-cli settings chat.disableInheritingDefaultResources true
Ou limitez-le à un espace de travail :
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.
{ "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" ], "toolAliases": { "@git/git_status": "status", "@fetch/fetch_url": "get" }, "allowedTools": [ "read", "@git/git_status" ], "permissions": { "rules": [ { "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": { "agentSpawn": [ { "command": "git status" } ], "postToolUse": [ { "matcher": "fs_write", "command": "cargo fmt --all" } ] }, "includeMcpJson": true, "model": "claude-sonnet-4", "keyboardShortcut": "ctrl+r", "welcomeMessage": "Ready to help with AWS and Rust development!" }
Utilisez des agents locaux pour :
Utilisez des agents globaux pour :
allowedToolspermissions.rules pour restreindre les opérations sensiblesPar défaut, l'agent Kiro n'a accès qu'aux outils en lecture seule. Aucune opération d'écriture n'est autorisée à moins que vous ne les activiez explicitement dans allowedTools ou que vous ne les approuviez au moment de l'exécution.
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 :
~/.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.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 :
"write" mais pas "shell").permissions.rules en utilisant des motifs match étroits.preToolUse pour auditer ou bloquer les opérations sensibles.Si vous avez des configurations d'agent créées avant l'IDE 1.0 ou le CLI 3.0, /upgrade-agent identifie les configurations nécessitant une migration, sauvegarde les originaux et convertit les champs pris en charge sur place.
# 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 restent visibles et sélectionnables dans le sélecteur /agent de la V3. /upgrade-agent convertit les hooks au format objet vers le format tableau requis par la V3.
Avant :
{ "hooks": { "agentSpawn": { "command": "git status" } } }
Après :
{ "hooks": { "agentSpawn": [ { "command": "git status" } ] } }
| Ancien motif | Nouvel équivalent |
|---|---|
toolsSettings.shell.allowedCommands | permissions.rules avec capability: shell, effect: allow |
toolsSettings.shell.deniedCommands | permissions.rules avec capability: shell, effect: deny |
toolsSettings.write.allowedPaths | permissions.rules avec capability: fs_write, effect: allow |
Entrées allowedTools | Règles d'autorisation au niveau des capacités |
Noms d'outils (fs_read, execute_bash) | Balises (read, shell) - les deux fonctionnent toujours |
autoAllowReadonly | Règle de politique shell en lecture seule |
| Hooks au format objet | Hooks au format tableau requis par le schéma V3 |
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 Quoi de neuf dans le CLI 3.0 - Configuration de l'agent.
Référence de configuration de l'agent