Déléguer une tâche à un sous-agent

Un sous-agent reçoit une consigne, travaille dans sa propre session et rend un rapport final à l’agent qui l’a lancé. Cette page montre comment utiliser les deux sous-agents livrés avec le produit, écrire le vôtre, lancer une délégation, lire le rapport et reconnaître ce qui a arrêté un sous-agent. Le modèle mental (ce qui passe d’une session à l’autre, pourquoi les droits ne s’élargissent pas) est sur Déléguer à des sous-agents.

Un sous-agent n’a rien de plus que la session qui le lance : il travaille dans le même bac à sable, sur la même copie du dépôt et sous la même politique, sans réseau, sans identité et sans secret (livre blanc sécurité V3, section 4.3).

Utiliser les sous-agents intégrés

Deux sous-agents sont disponibles sans rien installer :

Nom	Ce qu’il fait	Ses outils
general	mène une tâche en plusieurs étapes et rend compte	ceux de la session qui le lance, au plus
explore	lit et cherche dans le dépôt pour répondre à une question	Read, List, Search, et aucun autre

Choisissez explore pour une question sur le code : il ne peut ni écrire, ni exécuter une commande. Choisissez general pour un travail qui modifie des fichiers ou lance des commandes.

Ces deux noms sont réservés. Un fichier general.md ou explore.md trouvé dans un dossier d’agents est écarté et signalé, et lemni --agent general est refusé : les sous-agents intégrés se lancent par délégation seulement.

Écrire un sous-agent

Un sous-agent est un fichier Markdown. Son en-tête YAML porte la configuration, son corps est le prompt système.

1. Créez le fichier dans .lemniscate/agents/ à la racine du dépôt git, pour le partager avec l’équipe, ou dans ~/.lemniscate/agents/, pour le garder sur votre poste. L’extension est .md ou .markdown.
2. Nommez le fichier du nom que vous voulez donner au sous-agent : le nom du fichier, sans son extension, est le nom de l’agent. relecture.md déclare l’agent relecture.
3. Déclarez mode: subagent dans l’en-tête. Sans clé mode, le fichier n’est pas délégable.
4. Écrivez dans le corps ce que le sous-agent doit faire et ce que son rapport doit contenir. Son dernier message est le rapport rendu.

---
description: Relit une modification et liste les défauts trouvés, sans rien écrire.
mode: subagent
tools: Read, List, Search
sessionMaxActions: 40
---

Tu relis la modification décrite dans la consigne.

Lis les fichiers concernés et leurs tests. Ne modifie rien.

Ton dernier message est ton rapport : liste chaque défaut avec le chemin du
fichier et la ligne, classe-les par gravité, et dis-le clairement si tu n'en
trouves aucun.

Les clés de l’en-tête :

Clé	Effet
mode	subagent : délégable, pas invocable par --agent. all : les deux. primary ou absent : invocable par --agent seulement
description	la ligne que le modèle lit dans la liste des sous-agents disponibles. C’est elle qui lui fait choisir ce sous-agent
tools	noms d’outils séparés par des virgules. La liste ferme le catalogue : un outil qui n’y figure pas est retiré au sous-agent
rules	règles séparées par des virgules, ajoutées au prompt système du sous-agent
model	nom d’un modèle de votre configuration. Absent, le sous-agent utilise le modèle de la session qui le lance
sessionMaxActions	plafond d’actions de ce sous-agent. Absent ou à 0, il n’a pas de plafond d’actions
disable	true retire l’agent sans supprimer le fichier
hidden	true masque l’agent de l’autocomplétion. Sans effet sur la délégation

Ce qu’il faut savoir en écrivant le fichier :

• Une valeur de mode inconnue, ou un sessionMaxActions qui n’est pas un entier positif ou nul, fait refuser le fichier au chargement. Le sous-agent est alors introuvable, et le refus de délégation nomme le fichier et la cause.
• Une liste tools ne donne aucun droit. Un outil que la session ne peut pas utiliser reste refusé au sous-agent, même si la liste le nomme.
• Une liste tools qui ne nomme pas Task retire au sous-agent la possibilité de déléguer à son tour.
• Sans clé tools, le sous-agent garde les outils intégrés de la session, mais aucun outil de serveur MCP : nommez dans tools le serveur ou l’outil MCP dont il a besoin.
• Un model qui ne figure pas parmi les modèles configurés fait échouer la délégation avec un message qui le nomme. Le sous-agent ne se replie pas sur un autre modèle.
• Si le même nom existe dans le dépôt et sur le poste, le fichier du dépôt l’emporte.

Le fichier est lu à chaque tour : un sous-agent ajouté pendant une session est disponible sans relancer le terminal.

Dans les extensions d’éditeur, un fichier mode: subagent n’apparaît pas dans la liste des agents à activer. Déclarez mode: all si le même fichier doit servir aux deux usages.

Faire déléguer l’agent

L’agent délègue avec l’outil Task. Il y voit la liste des sous-agents disponibles, avec leur description.

1. Lancez une session dans le dépôt.

   lemni

2. Dans votre consigne, nommez le sous-agent et dites ce que le rapport doit contenir. Par exemple : « Délègue au sous-agent relecture : qu’il relise src/facturation/, puis résume-moi les défauts bloquants. »

3. Laissez le tour se terminer. L’agent reçoit le rapport et poursuit.

Par défaut, l’outil Task est autorisé sans question : la délégation elle-même ne vous demande pas d’accord. Chaque action du sous-agent passe par la politique, comme celles de l’agent.

Si l’agent lance plusieurs délégations dans le même tour, elles s’exécutent en parallèle, et le tour reprend quand tous les rapports sont revenus.

Pour un travail long, demandez à l’agent de déléguer en arrière-plan. Il appelle alors Task avec background: true, reçoit un identifiant de tâche et continue. Les conséquences sont décrites dans Déléguer vous-même par une mention : une tâche d’arrière-plan suit les mêmes règles, qu’elle vienne de l’agent ou de vous.

La délégation fonctionne aussi en exécution ponctuelle (lemni -p). Deux différences : une action du sous-agent qui demanderait votre accord est refusée, faute de personne pour répondre, et background: true s’exécute de façon synchrone, ce que le rapport annonce en première ligne.

Répondre à une demande d’accord

Quand un sous-agent lancé par l’agent veut utiliser un outil soumis à votre accord, la demande s’affiche au même endroit que celles de la session. Une ligne nomme le sous-agent qui demande :

Requested by subagent 'relecture' — its delegation is paused until you answer.

Le sous-agent attend votre réponse. Le nom affiché est le nom du fichier d’agent : vérifiez-le avant d’accepter quand le dépôt apporte ses propres agents.

Déléguer vous-même par une mention

Dans une session interactive, vous lancez un sous-agent sans passer par l’agent.

1. Tapez @, le nom du sous-agent, une espace, puis la consigne :

   @explore Où le montant d'une facture est-il arrondi ? Donne les fichiers et les fonctions.

2. Lisez la ligne de confirmation, qui porte l’identifiant de la tâche :

   [Delegated to subagent 'explore' in the background (task_id 'task-1'). Its report will be announced here when it completes.]

3. Continuez à travailler. La fin de la tâche est annoncée dans la conversation :

   [Background task 'task-1' (agent 'explore') completed. Use the TaskResult tool to read its report.]

4. Demandez à l’agent de lire le rapport de la tâche, en la désignant par son identifiant. Il le lit avec l’outil TaskResult.

La mention ne lance une délégation que si le mot qui suit @ est exactement le nom d’un sous-agent délégable. Dans tous les autres cas, @ garde son sens habituel de mention de fichier.

Une tâche lancée par une mention tourne toujours en arrière-plan. Tenez-en compte avant de lui confier un travail :

• Elle ne vous demande aucun accord. Une action soumise à votre accord, comme une écriture de fichier ou une commande sous la politique par défaut, lui est refusée. Cela vaut aussi pour les sous-agents qu’elle lance à son tour. Réservez la mention aux tâches de lecture, ou aux actions que la politique autorise sans question.
• Elle continue quand vous interrompez le tour en cours.
• Elle s’arrête sans annonce quand vous fermez le terminal. Lisez son rapport avant de quitter.

Pour entendre la cloche du terminal à la fin d’une tâche d’arrière-plan, lancez le terminal avec la variable LEMNISCATE_NOTIFY_BELL à 1 :

LEMNISCATE_NOTIFY_BELL=1 lemni

Lire le rapport

Le rapport est le dernier message du sous-agent. Il revient à l’agent comme résultat de l’outil Task, ou de l’outil TaskResult pour une tâche d’arrière-plan. Il se termine par une ligne qui nomme la session du sous-agent :

(subagent session: 3f2a9c1e-sub1-relecture — its full transcript is persisted and can be inspected)

L’identifiant est celui de la session qui a délégué, suivi de -sub, d’un rang et du nom du sous-agent.

Un rapport qui commence par l’une de ces mentions rend compte d’un travail incomplet :

Le rapport commence par	Ce qui s’est passé
[SUBAGENT STOPPED BY A GUARDRAIL — session bound reached.	le sous-agent a atteint sa borne de durée ou d’actions
[SUBAGENT STOPPED BY A GUARDRAIL — tool loop detected	le sous-agent répétait le même appel d’outil
[SUBAGENT INTERRUPTED — the parent turn was interrupted	vous avez interrompu le tour pendant une délégation synchrone

Le texte qui suit la mention est ce que le sous-agent a produit avant l’arrêt. Sans mention, le sous-agent a terminé de lui-même.

Le rapport est un résumé. Pour vérifier ce que le sous-agent a fait, ouvrez sa session : elle est enregistrée comme une session ordinaire, dans le fichier ~/.lemniscate/sessions/<identifiant>.json, avec la consigne reçue, chaque appel d’outil et son résultat.

L’outil TaskResult ne bloque pas. Pour une tâche en cours, il répond qu’elle tourne encore ; pour une tâche en échec, il rend l’erreur.

Ce qui arrête un sous-agent

Les droits, plus étroits que ceux de la session

Un sous-agent part des droits effectifs de la session qui le lance, et ne peut que les restreindre :

• un outil retiré à la session lui est retiré aussi, quoi que dise son en-tête ;
• si la session est en mode plan, il n’a que les outils de lecture ;
• sa liste tools, s’il en déclare une, retire tout le reste ;
• un outil de serveur MCP qu’il ne déclare pas lui est retiré ;
• les outils Question et Exit lui sont toujours retirés : il ne vous pose pas de question ouverte et ne peut pas terminer le processus.

Un outil retiré n’est pas décrit au sous-agent. Face à une ambiguïté, il choisit une interprétation et l’énonce dans son rapport.

Les bornes de sa session

• La durée. Chaque sous-agent a sa propre borne de durée, celle de la configuration (45 minutes par défaut, clé execution.sessionMaxMinutes). Elle ne se prolonge pas : à l’échéance, le sous-agent s’arrête et rend un rapport marqué.
• Les actions. Un sous-agent n’a pas de plafond d’actions, sauf si son en-tête déclare sessionMaxActions. La délégation coûte une action à la session qui délègue.
• La boucle. La détection de boucle arrête un sous-agent qui répète le même appel d’outil.
• L’interruption. Interrompre le tour arrête les délégations synchrones de ce tour. Les tâches d’arrière-plan continuent.

Le détail de ces garde-fous est sur Garde-fous d’exécution.

Les filets de la cascade

Un sous-agent peut déléguer à son tour. Trois limites bornent l’ensemble :

Clé sous execution	Défaut	Ce qu’elle borne
subagentMaxDepth	3	le nombre d’étages de délégation. 1 interdit toute imbrication
subagentMaxPerSession	200	le nombre de sous-agents lancés par une session, sur toute sa durée
subagentMaxConcurrent	20	le nombre de sous-agents qui tournent en même temps

Les délégations que vous lancez par une mention comptent dans les mêmes limites que celles de l’agent.

Pour les régler, ajoutez les clés au fichier de configuration :

execution:
  subagentMaxDepth: 1
  subagentMaxConcurrent: 4

La valeur 0 est refusée : ces limites se règlent et ne se retirent pas. Les clés sont décrites dans la référence du fichier de configuration.

Quand une délégation est refusée

Un refus est rendu à l’agent comme résultat de l’outil, et l’agent finit le travail lui-même. Pour une mention, le refus s’affiche dans la conversation.

Le message commence par	Cause	Ce que vous faites
Delegation refused: no delegable agent named	le nom ne désigne aucun sous-agent délégable	vérifiez le nom du fichier, son dossier et sa clé mode
No delegable agent named	la même cause, pour une mention	le message liste les noms délégables
Delegation refused: the maximum subagent depth	le dernier étage de délégation est atteint	laissez l’agent finir, ou relevez subagentMaxDepth
Delegation refused: this session already spawned	la session a lancé le nombre maximal de sous-agents	ouvrez une nouvelle session, ou relevez subagentMaxPerSession
Delegation refused: suivi de subagents are already running	trop de sous-agents tournent en même temps	attendez la fin des tâches en cours
Subagent '<nom>' declares model	la clé model nomme un modèle absent de la configuration	corrigez le nom du modèle, ou retirez la clé
Agent '<nom>' declares 'mode: subagent'	vous avez lancé le fichier avec lemni --agent	déléguez-lui une tâche, ou déclarez mode: all
The '@<nom>' subagent mention is not available in remote mode yet	la mention a été saisie dans lemni remote	lancez la tâche depuis une session locale

Au dernier étage de délégation, l’outil Task n’est pas offert au sous-agent : le premier refus de profondeur ne se voit que si le modèle appelle quand même l’outil.