Système de sous-agents
Aperçu
Le sous-agent (Subagent) est le mécanisme de décomposition et de délégation de tâches de l'espace de travail. L'Agent principal peut décomposer des tâches parallèles complexes en sous-tâches, créer des sous-agents spécialisés pour les exécuter de manière indépendante ; une fois le sous-agent terminé, il renvoie le résultat à l'Agent principal pour la suite du traitement.
Le système prend en charge trois types de sous-agents, avec une profondeur d'imbrication maximale de 3 niveaux.
Trois types de sous-agents
| Type | Nom de l'outil | Mode de création | Cas d'usage | Emplacement d'exécution |
|---|---|---|---|---|
| Création automatique | create_local_sub_agent |
Création autonome par l'Agent lors du raisonnement | Décomposition temporaire de sous-tâches | Nœud local |
| Répartition pré-enregistrée | dispatch_sub_agent |
Configuration préalable par l'utilisateur | Rôles spécialisés fixes réutilisés | Nœud local |
| Répartition inter-nœuds | dispatch_multi_node_agent |
Sélection d'un nœud distant par l'Agent | Besoin de ressources ou de capacités distantes | Nœud distant |
Sous-agent à création automatique (create_local_sub_agent)
Lorsque, au cours de son raisonnement, l'Agent juge que la tâche en cours doit être décomposée, il appelle de manière autonome l'outil create_local_sub_agent pour créer un sous-agent temporaire. L'utilisateur peut également, via une invite de conversation, demander à l'Agent de créer un sous-agent, par exemple :
« Veuillez créer un sous-agent chargé de rechercher des ressources pertinentes, puis créer un autre sous-agent chargé de rédiger la documentation »
Paramètres de création :
| Paramètre | Description | Obligatoire |
|---|---|---|
task |
Description de la tâche du sous-agent | Oui |
systemPrompt |
Définition de l'identité/du rôle du sous-agent | Oui |
cwd |
Répertoire de travail (hérité du parent par défaut) | Non |
maxSpawnDepth |
Profondeur d'imbrication (1-3), par défaut 1 | Non |
Flux d'exécution :
- L'Agent principal décide de créer un sous-agent et lui assigne une tâche
- Le système démarre une boucle d'Agent indépendante (par défaut 50 tours maximum)
- Le sous-agent dispose de sa propre boucle d'outils ; le processus d'exécution est visible dans la fenêtre de conversation parente
- Une fois terminé, le sous-agent renvoie le résultat final à l'Agent principal
- L'Agent principal poursuit son travail sur la base du résultat
Sous-agent à répartition pré-enregistrée (dispatch_sub_agent)
L'utilisateur peut pré-enregistrer dans les paramètres de l'APP des sous-agents dotés d'une configuration spécifique, que l'Agent appelle en cas de besoin via l'outil dispatch_sub_agent.
La description du sous-agent pré-enregistré est automatiquement injectée dans l'invite système de l'Agent principal ; lorsque le LLM détecte une tâche correspondante, il sélectionne automatiquement le sous-agent approprié.
Options de configuration :
| Configuration | Description |
|---|---|
name |
Nom du sous-agent |
description |
Description des capacités (injectée dans l'invite système de l'Agent parent) |
systemPrompt |
Définition de l'identité/du rôle |
tools |
Liste blanche d'outils (héritage complet si omise) |
disallowedTools |
Liste noire d'outils |
skills |
Liste des ID de compétences disponibles |
mcpServers |
Liste des noms de serveurs MCP disponibles |
model |
Remplace le modèle du parent |
maxTurns |
Remplace le nombre de tours maximal par défaut |
canSpawn |
Peut ou non créer des sous-agents de niveau inférieur |
maxSpawnDepth |
Profondeur d'imbrication maximale |
Pour l'interface de gestion, voir Enregistrement et gestion des sous-agents.
Répartition inter-nœuds (dispatch_multi_node_agent)
Lorsqu'une tâche nécessite les ressources ou les capacités d'un appareil distant, l'Agent peut, via l'outil dispatch_multi_node_agent, répartir la tâche vers d'autres nœuds pour exécution.
Flux de travail :
- L'Agent principal consulte la liste des nœuds en ligne (injectée dans l'invite système)
- Il sélectionne le nœud cible en fonction des déclarations de capacités des nœuds
- Il envoie
node.invoke.requestvia le WebSocket de la Gateway - Le nœud distant démarre une boucle d'Agent indépendante pour exécuter la tâche
- Une fois terminé, il renvoie le résultat via
node.invoke.result
Exemple de scénario :
- Une conversation est lancée depuis le client Web sur l'ordinateur A
- La tâche nécessite d'accéder à des fichiers locaux sur l'ordinateur B
- L'Agent répartit, via la Gateway, la sous-tâche d'opération sur fichiers vers le nœud APP de l'ordinateur B
- Le nœud B exécute puis renvoie le résultat, et la conversation continue de s'afficher sur l'ordinateur A
Contrôle de la profondeur d'imbrication
Les sous-agents prennent en charge la création imbriquée, avec une profondeur maximale de 3 niveaux :
深度 0: 主 Agent(用户对话)
└── 深度 1: 子代理 A
└── 深度 2: 子子代理 A-1
└── 深度 3: 最深层代理(不可再委派)
| Paramètre | Valeur | Description |
|---|---|---|
DEFAULT_MAX_SPAWN_DEPTH |
1 | Par défaut : le sous-agent ne peut pas créer de niveau inférieur |
MAX_ALLOWED_SPAWN_DEPTH |
3 | Limite absolue |
SUBAGENT_DEFAULT_MAX_TURNS |
50 | Nombre de tours maximal par défaut du sous-agent (supérieur aux 25 de l'Agent principal) |
Plus la profondeur est élevée, plus l'autonomie est grande, mais la consommation de tokens et le temps d'exécution augmentent d'autant.
Mécanisme d'héritage des outils
| Mode | Description |
|---|---|
| Héritage par défaut | Le sous-agent hérite de tous les outils disponibles de l'Agent parent |
| Liste blanche | Le paramètre tools spécifie la liste des outils autorisés |
| Liste noire | Le paramètre disallowedTools exclut des outils spécifiques |
| Héritage des compétences | Peut hériter ou remplacer les compétences et les serveurs MCP du parent |
| Remplacement du modèle | Le sous-agent peut utiliser un modèle LLM différent de celui du parent |
Affichage dans l'interface
Les sous-agents sont affichés avec un marquage particulier dans la fenêtre de conversation Work :

| Élément d'affichage | Description |
|---|---|
| SubagentToolRow | Ligne d'appel d'outil dédiée au sous-agent, avec une couleur d'identification particulière (émeraude) |
| Transmission de l'activité | Le processus d'appel d'outil du sous-agent s'affiche en temps réel dans la fenêtre de conversation parente |
| Affichage du résultat | Une fois le sous-agent terminé, le résultat final est présenté en tant que sortie d'outil |
L'utilisateur peut voir clairement quelles opérations sont exécutées par l'Agent principal et lesquelles le sont par le sous-agent.
Comment créer un sous-agent via la conversation
Vous pouvez, dans la conversation, demander à l'Agent de créer un sous-agent en langage naturel. Voici quelques exemples d'invites :
| Invite | Effet |
|---|---|
| « Crée un sous-agent pour rechercher et organiser des ressources pertinentes » | L'Agent crée un sous-agent dédié à la recherche |
| « Divise cette tâche entre deux sous-agents : un pour le code, un pour la documentation » | L'Agent crée deux sous-agents ayant chacun sa spécialité |
| « Crée-moi un sous-agent de profondeur 2 pour traiter cette tâche complexe » | L'Agent crée un sous-agent pouvant lui-même déléguer davantage |
| « Utilise un nœud distant pour exécuter cette tâche de traitement de fichiers » | L'Agent utilise dispatch_multi_node_agent |
Comprendre l'interface pendant l'exécution d'un sous-agent

| Élément d'interface | Signification |
|---|---|
| Ligne d'outil marquée en émeraude | Il s'agit d'un appel d'outil en cours d'exécution par le sous-agent |
| Appel d'outil « create_local_sub_agent » | L'Agent principal est en train de créer un sous-agent |
| Appel d'outil au sein du sous-agent | Outil que le sous-agent décide d'appeler de manière autonome, affiché en temps réel |
| Résultat final | Sortie récapitulative une fois le sous-agent terminé |
Impact sur les coûts
La consommation de tokens des sous-agents est calculée de manière indépendante :
| Scénario | Consommation de tokens estimée |
|---|---|
| Agent principal seul (sans sous-agent) | 1x |
| Agent principal + 1 sous-agent | 1,5x ~ 2,5x |
| Agent principal + 2 sous-agents | 2x ~ 4x |
| Imbrication sur 3 niveaux (principal + enfant + petit-enfant + arrière-petit-enfant) | 3x ~ 6x |
Recommandation : les sous-agents conviennent aux tâches réellement complexes qui nécessitent une décomposition. Pour les tâches simples, laissez l'Agent principal les traiter directement, sans créer de sous-agent.
Quand utiliser ou ne pas utiliser un sous-agent
| Convient à l'usage d'un sous-agent | Pas besoin de sous-agent |
|---|---|
| La tâche se divise naturellement en parties indépendantes (ex. : recherche de ressources + rédaction de documentation) | Tâche linéaire unique (ex. : lire un fichier et le résumer) |
| Besoin de perspectives spécialisées différentes (ex. : revue de code + audit de sécurité) | Questions-réponses simples |
| Besoin des ressources d'un nœud distant (ex. : fichiers sur un serveur distant) | Opérations sur fichiers locaux |
| Charge de travail importante, parallélisable pour accélérer | Tâche simple et rapide |
Il n'est pas recommandé d'attribuer aux SubAgents des rôles différents pour les faire collaborer et se répartir le travail ; à l'ère de l'IA, la collaboration réduit au contraire l'efficacité et la qualité. Ils conviennent davantage aux scénarios d'exécution de tâches en parallèle, afin de gagner du temps et d'améliorer l'efficacité.
Documents connexes
- Enregistrement et gestion des sous-agents — Configuration des sous-agents pré-enregistrés
- Architecture multi-nœuds — Mécanisme sous-jacent de la répartition inter-nœuds
- Moteur de boucle d'Agent — Boucle d'Agent utilisée par les sous-agents
