Passer au contenu principal
Afficher en Markdown

Invocation en tant que sous-agents

Les sous-agents vous permettent de déléguer des tâches ciblées à des agents qui s'exécutent dans leur propre contexte isolé. L'agent principal génère des sous-agents lorsqu'une tâche profite du parallélisme, d'outils spécialisés ou de l'isolation du contexte, puis regroupe les résultats une fois ceux-ci terminés.

CapacitéIDECLIWebMobile
Invocation automatique de sous-agents✓✓✓✓
Invocation explicite de sous-agents✓✓✓✓
Agents personnalisés en tant que sous-agents✓✓✓✓
Exécution parallèle✓✓✓✓

Sur Web, les agents personnalisés commis dans .kiro/agents/ peuvent être invoqués comme sous-agents, en plus des sous-agents intégrés de Kiro. Les sessions que vous démarrez depuis Mobile peuvent utiliser les mêmes agents personnalisés que Kiro Web.

Comment fonctionnent les sous-agents

  1. Attribution de la tâche - Vous décrivez une tâche (ou l'agent principal en repère une qui profite de la délégation)
  2. Sélection de l'agent - Kiro sélectionne la configuration d'agent appropriée en fonction de la tâche et des agents disponibles
  3. Exécution isolée - Le sous-agent s'exécute avec sa propre fenêtre de contexte, ses propres outils et permissions
  4. Retour des résultats - Une fois terminé, le sous-agent retourne ses constatations à l'agent principal

Tout agent personnalisé peut être invoqué comme sous-agent. L'agent principal sélectionne automatiquement les agents en fonction de leur champ description, ou vous pouvez en demander un explicitement :

Use the code-reviewer agent to analyze src/auth/ for security issues

Ce que les sous-agents héritent

Les sous-agents partagent l'environnement de l'espace de travail, mais s'exécutent avec un contexte de conversation isolé :

Partagé avec l'agent principalIsolé par sous-agent
Fichiers SteeringHistorique de conversation
Serveurs MCPFenêtre de contexte
Accès aux fichiers de l'espace de travailÉtat des Specs
Configuration des permissionsDéclencheurs des Hooks

Sous-agents intégrés

Kiro comprend des sous-agents internes utilisés automatiquement lorsque cela convient :

  • Collecte de contexte - Explore la structure de votre projet et rassemble les fichiers et le contexte pertinents
  • Usage général - Traite des tâches parallélisées de tout type en utilisant la configuration d'agent par défaut
  • Validation - Vérifie une modification terminée par rapport à votre requête (déploiement progressif). Consultez Sous-agent de validation
  • Introspect - Répond aux questions sur Kiro à partir de sa documentation (CLI V3). Consultez Sous-agent Introspect

Vous n'avez pas besoin de configurer ces éléments - l'agent principal les utilise selon les besoins.

Exécution parallèle

Les sous-agents s'exécutent en parallèle, chacun travaillant de façon indépendante. Cela est utile pour :

  • Refactoriser plusieurs fichiers simultanément
  • Faire des recherches sur plusieurs sujets en parallèle
  • Exécuter des pistes d'analyse indépendantes
Refactor these three services to use the new auth middleware - do them in parallel

Dépendances entre tâches

Les sous-agents prennent en charge les graphes orientés acycliques (DAG) où les tâches dépendent les unes des autres. L'agent principal planifie l'ensemble du graphe de tâches à l'avance, puis exécute dans le bon ordre - en exécutant les tâches indépendantes en parallèle et en attendant les dépendances avant de démarrer les tâches dépendantes.

┌─────────────┐ │ 1. Analyze │ │ dependencies │ └──────┬───────┘ │ ┌──────▼───────┐ │ 2. Refactor │ │ modules │ └──────┬───────┘ │ ┌──────▼───────┐ │ 3. Run and │ │ fix tests │ └──────────────┘

Boucles de révision

Une étape peut revenir à une étape antérieure lorsque son résultat indique que du travail supplémentaire est nécessaire - par exemple, un réviseur renvoie le travail à un exécutant pour des révisions.

Implement the feature, then have a reviewer check it and send it back for fixes until it passes

L'agent construit un pipeline en boucle avec :

  • target - l'étape à réexécuter lorsque la boucle se déclenche
  • trigger - le texte dans le résultat de l'étape qui déclenche la boucle (p. ex., NEEDS_CHANGES)
  • max_iterations - plafond de sécurité (entre 1 et 10)

Contraintes :

  • Une étape ne peut pas revenir à elle-même
  • Les boucles mutuelles (A → B → A) sont rejetées
  • Le déclencheur doit comporter au moins quatre caractères

Disponibilité des outils

Le sous-agent par défaut dispose des mêmes outils intégrés que l'agent principal - read, write, shell, web_search, web_fetch, et tout outil MCP configuré.

Lorsque vous déléguez à un agent personnalisé, le sous-agent utilise la configuration tools et permissions de cet agent. Les outils non répertoriés dans la configuration de l'agent personnalisé ne seront pas disponibles pour le sous-agent. Dans la CLI V3 et l'IDE, les permissions de la session parente s'appliquent aussi aux appels d'outils du sous-agent. Consultez Permissions des sous-agents.

Configuration de l'accès aux sous-agents

Dans la CLI 2.x, contrôlez quels agents peuvent être générés et lesquels s'exécutent sans invites d'approbation en utilisant toolsSettings.subagent dans votre configuration d'agent :

json
{ "toolsSettings": { "subagent": { "availableAgents": ["reviewer", "tester", "docs-*"], "trustedAgents": ["reviewer", "tester"] } } }
ChampDescription
availableAgentsMotifs génériques (glob) pour les agents que cet agent peut générer. Omettre pour tous les autoriser.
trustedAgentsAgents qui démarrent sans invite de permission.

La CLI V3 ignore toolsSettings. Pour limiter les agents qu'un agent peut générer dans la CLI V3, inscrivez des entrées subagent/<name> dans son tableau tools au lieu de subagent. N'ajoutez pas @builtin ni * au tableau tools de cet agent, car les deux incluent invoke_sub_agent, qui peut démarrer n'importe quel agent. Pour démarrer un sous-agent sans invite, ajoutez une règle subagent à ses permissions :

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

Pour restreindre les outils qu'un sous-agent peut utiliser, configurez tools dans le fichier de configuration du sous-agent lui-même plutôt que dans le parent.

Permissions des sous-agents

La façon dont Kiro approuve les appels d'outils d'un sous-agent dépend de la version de la CLI.

CLI 2.xCLI V3
Champs d'agent lusallowedTools et toolsSettingspermissions (allowedTools et toolsSettings sont ignorés)
Démarrer un sous-agent sans inviteAjoutez l'agent à toolsSettings.subagent.trustedAgentsAjoutez une règle allow pour la capacité subagent
Outils du sous-agent lui-même approuvés au préalableS'exécutent sans invite, même si le parent ne les autorise pasS'exécutent sans invite seulement lorsque la session parente les autorise aussi

Dans la CLI V3 et l'IDE, Kiro vérifie chaque appel d'outil d'un sous-agent par rapport à deux politiques :

  • La politique de la session parente. Il s'agit de vos fichiers permissions.yaml utilisateur et d'espace de travail, des permissions de l'agent parent et des approbations que vous avez accordées plus tôt dans la session.
  • Les permissions propres au sous-agent.

Le résultat le plus strict l'emporte :

  • Un deny dans l'une ou l'autre politique refuse l'appel.
  • Une règle ask dans l'une ou l'autre politique vous demande une confirmation.
  • Si la politique de la session parente n'a aucune règle pour l'appel, Kiro vous demande une confirmation, même lorsque les règles propres au sous-agent l'autorisent.

Les règles allow d'un sous-agent prennent effet seulement lorsque cet agent s'exécute comme agent de premier niveau, par exemple avec kiro-cli chat --agent <name>. Un appel que les règles du sous-agent ne mentionnent pas suit la politique de la session parente. Un sous-agent sans bloc permissions s'exécute sous la politique de la session parente.

Pour permettre aux appels d'outils d'un sous-agent de s'exécuter sans invites dans la CLI V3, ajoutez les règles allow du sous-agent à l'un de ces emplacements :

  • Les permissions.rules de l'agent parent. L'agent parent n'a pas besoin du serveur MCP ni de l'outil lui-même.
  • Votre fichier ~/.kiro/settings/permissions.yaml de portée utilisateur. Ces règles s'appliquent à tous les agents.
  • Votre fichier permissions.yaml de portée espace de travail. Ces règles s'appliquent à tous les agents de cet espace de travail.

Par exemple, un sous-agent nommé data-analyst qui autorise tous les outils du serveur MCP analytics a besoin de la même règle dans l'agent parent :

json
{ "tools": ["read", "write", "shell", "subagent/data-analyst"], "permissions": { "rules": [ { "capability": "subagent", "match": ["data-analyst"], "effect": "allow" }, { "capability": "mcp", "match": ["analytics/*"], "effect": "allow" } ] } }

Dans une session où vous faites confiance à tous les outils, --trust-all-tools approuve les appels d'outils des sous-agents qui demanderaient autrement une confirmation. Les règles deny s'appliquent toujours.

Comportement propre à chaque surface

Lorsque les workflows sont désactivés, les sous-agents s'exécutent en parallèle et l'agent principal attend qu'ils soient tous terminés avant de poursuivre. Lorsque les workflows sont activés, l'agent principal lance plutôt la délégation aux agents personnalisés en tant qu'exécution de workflow en arrière-plan, afin que vous puissiez poursuivre le clavardage parent et surveiller l'exécution sous Workflows. Chaque agent délégué dispose de sa propre fenêtre de contexte.

Vous pouvez accélérer le développement en exploitant les sous-agents pour effectuer plusieurs tâches simultanément - par exemple, en récupérant et en analysant plusieurs tickets en parallèle.

Bonnes pratiques

  1. Utiliser pour les tâches complexes - Le plus utile pour les opérations à plusieurs étapes qui profitent de l'isolation ou du parallélisme
  2. Fournir des instructions claires - Des descriptions de tâches précises entraînent une meilleure sélection d'agent et de meilleurs résultats
  3. Surveiller la progression - Dans la CLI, utilisez Ctrl+G pour vérifier l'état des sous-agents de longue durée
  4. Configurer l'accès - Limitez les agents qu'un agent orchestrateur peut générer et décidez lesquels démarrent sans invite. Consultez Configuration de l'accès aux sous-agents

Dépannage

ProblèmeSolution
Le sous-agent ne démarre pasVérifiez que la description de la tâche est claire et exploitable
Agent inconnuVérifiez le nom de l'agent avec kiro-cli agent list; une requête qui nomme un agent inconnu échoue au lieu de revenir à l'agent par défaut
Accès aux outils manquantVérifiez le champ tools de la configuration de l'agent
Invites d'approbation bloquantesDans la CLI 2.x, ajoutez l'agent à trustedAgents pour ignorer l'invite de démarrage, et approuvez au préalable ses outils dans ses propres allowedTools. Dans la CLI V3, ajoutez une règle allow pour subagent afin d'ignorer l'invite de démarrage, et ajoutez les règles allow du sous-agent à la politique de la session parente. Consultez Permissions des sous-agents
L'agent principal ne peut pas générer de sous-agentsAjoutez subagent au tableau tools de l'agent orchestrateur
Résultats incompletsFournissez des instructions plus précises ou divisez en tâches plus petites
Page mise à jour : 13 novembre 2026