Sous-agents

Un agent basé sur des fichiers peut déclarer des sous-agents, des agents enfants spécialisés auxquels il délègue des tâches. Le modèle parent voit chaque sous-agent comme un outil de délégation nommé d’après le répertoire du sous-agent et appelle cet outil pour lui confier une tâche. Le résultat du sous-agent revient dans la conversation parente.

Utilisez cette page pour la convention basée sur des fichiers. Pour des modèles de délégation plus larges, les hooks, l’isolation de la mémoire, la propagation des approbations d’outils et l’évaluation, consultez les agents superviseurs.

Démarrage rapide

Déclarez un répertoire par sous-agent sous subagents/ :

Subagent layout

src/mastra/agents/
└── supervisor/
    ├── config.ts
    ├── instructions.md
    └── subagents/
        └── researcher/
            ├── config.ts
            ├── instructions.md
            └── tools/
                └── search.ts

Mastra assemble researcher en tant qu’agent distinct et le raccorde à la mappe agents du superviseur. Le modèle parent peut lui déléguer une tâche en utilisant l’outil de délégation researcher généré.

Le fichier config.ts d’un sous-agent doit définir une description non vide. Le modèle parent la lit lorsqu’il décide de déléguer ou non.

src/mastra/agents/supervisor/subagents/researcher/config.ts

import { agentConfig } from '@mastra/core/agent'

export default agentConfig({
  model: 'openai/gpt-5.6-sol',
  description: 'Researches a topic and returns cited findings.',
})

Comment le modèle délègue

La description d’un sous-agent est un texte de routage destiné au modèle parent. Rédigez-la comme une description d’outil : expliquez ce que fait le sous-agent et quand lui déléguer une tâche.

La compilation échoue lorsqu’un sous-agent détecté ne fournit pas de description non vide.

Isolation

Les sous-agents sont isolés. Un sous-agent n’hérite pas des outils, skills, espace de travail, mémoire, processeurs ou sous-agents de son parent. Chaque enfant est un agent autonome doté de son propre répertoire.

Si plusieurs agents doivent partager la même dépendance, définissez-la dans le code et affectez-la via la configuration de chaque agent.

Imbrication

Les sous-agents peuvent déclarer leurs propres répertoires subagents/, avec une imbrication allant jusqu’à trois niveaux sous l’agent de niveau supérieur. Un répertoire subagents/ imbriqué plus profondément est ignoré avec un avertissement.

Nested subagents

src/mastra/agents/
└── supervisor/            # depth 0
    └── subagents/
        └── researcher/    # depth 1
            └── subagents/
                └── summarizer/ # depth 2

Règles de nommage

• Un identifiant de sous-agent qui entre en conflit avec l’une des clés d’outils du parent provoque une erreur de compilation.
• Un identifiant de sous-agent dupliqué sous le même parent provoque une erreur de compilation.
• Si un identifiant de sous-agent existe également dans config.agents du parent, l’entrée config.agents est prioritaire et un avertissement est journalisé.
• Si config.agents est une fonction, les sous-agents détectés sont ignorés avec un avertissement car ils ne peuvent pas être fusionnés statiquement.

Exemple

Ce superviseur coordonne un flux de recherche et de rédaction. Le sous-agent researcher possède les outils de recherche, tandis que le sous-agent writer possède un espace de travail pour rédiger des fichiers.

Research supervisor

src/mastra/agents/
└── research-supervisor/
    ├── config.ts
    ├── instructions.md
    └── subagents/
        ├── researcher/
        │   ├── config.ts
        │   ├── instructions.md
        │   └── tools/
        │       └── search_web.ts
        └── writer/
            ├── config.ts
            ├── instructions.md
            └── workspace/
                └── draft-template.md

src/mastra/agents/research-supervisor/config.ts

import { agentConfig } from '@mastra/core/agent'

export default agentConfig({
  model: 'openai/gpt-5.6-sol',
})

src/mastra/agents/research-supervisor/instructions.md

You coordinate research and writing.

Delegate fact gathering to `researcher`. Delegate final drafting to `writer`.

src/mastra/agents/research-supervisor/subagents/researcher/config.ts

import { agentConfig } from '@mastra/core/agent'

export default agentConfig({
  model: 'openai/gpt-5-mini',
  description: 'Use to gather facts, sources, and concise research notes for a topic.',
})

src/mastra/agents/research-supervisor/subagents/writer/config.ts

import { agentConfig } from '@mastra/core/agent'

export default agentConfig({
  model: 'openai/gpt-5.6-sol',
  description: 'Use to turn research notes into a structured draft.',
})