Chargement de l'image...Kiro

Produit

  • À propos de Kiro
  • IDE
  • CLI
  • Web
  • Mobile
  • Crew
  • Tarification
  • Téléchargements

Pour

  • Entreprise
  • Startups
  • Étudiants

Communauté

  • Aperçu
  • Ambassadeurs
  • Discord
  • Événements
  • Powers
  • Boutique
  • Vitrine

Ressources

  • Docs
  • Blogue
  • Journal des modifications
  • FAQ
  • Signaler un bogue
  • Suggérer une idée
  • Soutien à la facturation

Réseaux sociaux

Conditions d'utilisation du siteLicencePolitique d'IA responsableMentions légalesPolitique de confidentialitéPréférences relatives aux témoins
Chargement de l'image...Kiro
  • Entreprise
  • Tarification
  • Docs
SE CONNECTERTÉLÉCHARGER
Chargement de l'image...Kiro

Pour commencer

InstallationAuthentificationVotre premier projet

Modèles

AperçuModèles disponiblesEffort de raisonnement

Fonctionnalités

Comment fonctionne Kiro
Specs
Steering
Hooks
MCP
Autorisations
Agents personnalisés
Agents intégrés
Création d'agents personnalisés
Référence de configuration
Invocation en tant que sous-agents
Exemples
Dépannage
Agent Skills
Powers
Sessions cloudCompactionKiroignorePoints de contrôle et rewind
Outils intégrés
Portées de configuration

IDE 1.x

Nouveautés de la version 1.0
Configuration et premier lancement
Éditeur
Chat
Expérimental
DépannageRéférence 0.x

CLI

Nouveautés de la version 3.0
Configuration et première exécution
Interface utilisateur du terminal
Clavardage
Mode vocalMode sans interfaceACPAutocomplétion
Expérimental
Référence 2.x

Crew

Démarrage rapideInstallationFonctionnement 24/7
Chat
Agent Capabilities
Fonctionnalités
Interfaces
Applications
ConfigurationSécuritéDépannage

Web - Aperçu

Configuration et première exécutionIdentity Center
Connectez vos dépôts
Utilisation de l'agent
Mode autonomeAutomatisationsMémoire
Sandbox

Mobile - Aperçu

Aperçu

Commandes et référence

Commandes CLICommandes à barre obliqueOutils intégrésCodes de sortieParamètres

Facturation

AperçuGestion de votre abonnementMise à niveau de votre forfaitRétrogradation de votre forfaitAnnulation de votre forfaitAchat de crédits supplémentairesGestion de vos paiementsGestion des notifications d'utilisationGestion de vos impôtsCommuniquer avec le soutien à la facturationSuppression de votre compteQuestions connexes

Entreprise

ConceptsDémarrage rapide de l'intégration
Connexion de votre fournisseur d'identité
Abonnez votre équipeGérer les abonnements
Governance
Surveillance et suivi
ParamètresMises à jour géréesFacturationIAMRégions prises en charge

Confidentialité et sécurité

AperçuProtection des donnéesRéférences de codeValidation de la conformitéSécurité de l'infrastructureAutorisations IAMPare-feu, mandataires et périmètres de donnéesPoints de terminaison VPC (AWS PrivateLink)

Guides

Aperçu
Prise en charge des langages
Apprendre en jouant

Migration

Migration depuis Q DeveloperMigration depuis VSCodeMise à niveau depuis Q CLI
  1. Docs
  2. Fonctionnalités
  3. Agents personnalisés
  4. Référence de configuration
Afficher en Markdown

Référence de configuration de l'agent

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et la version anglaise originale, la version anglaise prévaudra.
Afficher en Markdown

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.

Comparaison des versions

Nouveau dans l'IDE 1.0 / CLI 3.0 :

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, *

Obsolète :

ChampRemplacement
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.

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 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.

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 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

Le 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 :

BaliseCe qu'elle inclut
readLecture de fichiers, listage de répertoires, recherche
writeÉcriture, modification, suppression de fichiers
shellExécution de commandes et gestion des processus
webRécupération Web
subagentDélégation aux sous-agents
knowledgeOutils de base de connaissances
todo_listSuivi des tâches
@mcpTous les outils MCP de mcp.json
@builtinTous 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.

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 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 :

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 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.

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.

Avertissement

Lorsque vous autorisez des outils d'écriture (comme write, shell, ou des outils MCP avec accès en écriture), l'agent peut modifier n'importe quel fichier auquel les outils ont accès - y compris toutes les ressources sous ~/.kiro telles que les skills, les fichiers de steering, les configurations MCP et d'autres configurations d'agent. Tous les skills et ressources installés fonctionnent avec les mêmes permissions que l'agent. Consultez la section Bonnes pratiques de sécurité avant d'activer les outils d'écriture.

Champ ToolsSettings

Avertissement

toolsSettings est obsolète dans le CLI 3.0 et l'IDE 1.0. Utilisez plutôt le champ permissions pour le contrôle d'accès basé sur les capacités. Consultez Migration des permissions pour le guide complet.

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 :

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

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, all
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.

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.

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

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 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.

json
{ "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écuter
  • matcher (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.

Champ includeMcpJson

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).

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" }

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.

Champ KeyboardShortcut

Le champ keyboardShortcut configure un raccourci clavier pour passer rapidement à cet agent pendant une session de clavardage.

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" "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 le 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" ], "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!" }

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 allowedTools
  • 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

Par 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 :

  • 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 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.

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 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 :

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

Après :

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

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
Noms d'outils (fs_read, execute_bash)Balises (read, shell) - les deux fonctionnent toujours
autoAllowReadonlyRègle de politique shell en lecture seule
Hooks au format objetHooks 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.

Prochaines étapes

  • Création d'agents personnalisés
  • Exemples - configurations d'agent réelles
  • Dépannage - résoudre les problèmes courants
  • Documentation des Hooks
Page mise à jour : 11 août 2026
Création d'agents personnalisés
Invocation en tant que sous-agents