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.
Nouveau dans l'IDE 1.0 / CLI V3 :
| 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, * |
Champs de migration de CLI 2.x :
| Champ | Traitement 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 |
toolAliases | Ne fait pas partie du schéma de la CLI V3; utilisez des sélecteurs d'outils complets |
keyboardShortcut | Ne 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.
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 :
--- 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.
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 verspermissions.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.
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" }
- Chemins relatifs : Résolus par rapport au répertoire du fichier de configuration de l'agent
"file://./prompt.md"-prompt.mddans le même répertoire que la configuration de l'agent"file://../shared/prompt.md"-prompt.mddans un répertoire parent
- Chemins absolus : Utilisés tels quels
"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 desheadersoptionnels 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 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 HTTPclientId(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 deoauth, 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.
- 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
@builtinpour inclure tous les outils intégrés - Utilisez
@server_namepour 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é.
{ "tools": [ "read", "write", "shell", "@git", "@rust-analyzer/check_code" ] }
Pour inclure tous les outils disponibles, utilisez :
{ "tools": ["*"] }
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 :
{ "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 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é.
{ "allowedTools": [ "read", "write", "@git/git_status", "@server/read_*", "@fetch" ] }
Vous pouvez autoriser des outils en utilisant plusieurs motifs :
- 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")
Le champ allowedTools prend en charge les motifs génériques de style glob utilisant * et ? :
- 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.
{ "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- 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.
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.
{ "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.
{ "tools": ["read", "write", "shell", "web", "subagent/reviewer", "subagent/tester"], "permissions": { "rules": [ { "capability": "subagent", "match": ["reviewer"], "effect": "allow" } ] } }
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, skill, power, context, diagnostics, sandbox_network; ou les métacapacités all, builtin et filesystem. Consultez Autorisations. |
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.
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.
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 demande
Les deux prennent en charge :
- Chemins spécifiques :
file://README.mdouskill://my-skill.md - Motifs glob :
file://.kiro/**/*.mdouskill://.kiro/skills/**/SKILL.md - Chemins absolus ou relatifs
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.
{ "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.
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 :
- 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
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.
{ "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, commeSessionStart,PreToolUseouPostToolUse.matcher(optionnel) : Sélecteur d'outil (ID d'outil, balise de catégorie commeshell,@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.
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).
{ "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.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.
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.
{ "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 Maj
Touches :
- Lettre unique :
a-z(insensible à la casse) - Chiffre unique :
0-9
Exemples :
{ "keyboardShortcut": "ctrl+a" }
{ "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.
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 la 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" ], "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!" }
- Commencez de façon restrictive : Commencez avec un accès minimal aux outils et élargissez-le selon les besoins
- Nommez clairement : Utilisez des noms descriptifs qui indiquent le but de l'agent
- Documentez l'usage : Ajoutez des descriptions claires pour aider les membres de l'équipe à comprendre l'agent
- Contrôle des versions : Stockez les configurations d'agent dans le dépôt de votre projet
- Testez minutieusement : Vérifiez que les permissions d'outils fonctionnent comme prévu avant de les partager
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
- Examinez soigneusement les
permissions.rulesau niveau des capacités - Préférez des motifs spécifiques aux caractères génériques
- Utilisez
permissions.rulespour restreindre les opérations sensibles - Testez les agents dans des environnements sûrs d'abord
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
shellsont 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.rulesen utilisant des motifsmatchétroits. - Examinez les skills et les ressources avant de les installer, en particulier de sources non fiables.
- Utilisez les Hooks
PreToolUsepour auditer ou bloquer les opérations sensibles.
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.
# 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 :
{ "hooks": { "agentSpawn": [ { "command": "git status" } ] } }
Après /upgrade-agent :
{ "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.
| 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 |
toolsSettings.subagent.trustedAgents | permissions.rules avec capability: subagent, effect: allow. Saute seulement l'invite de démarrage du sous-agent |
toolsSettings.subagent.availableAgents | Entré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 |
autoAllowReadonly | Règle de politique shell en lecture seule |
| Hooks au format objet | Tableau 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.
- Création d'agents personnalisés
- Exemples - configurations d'agent réelles
- Dépannage - résoudre les problèmes courants
- Documentation des Hooks
Référence de configuration de l'agent