> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt

# 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](https://mastra.zisheng.pro/fr/docs/capabilities/subagents).

## Démarrage rapide

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

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

```typescript
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](https://mastra.zisheng.pro/fr/reference/file-based-agents/tools) : 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.

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

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

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

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

```markdown
You coordinate research and writing.

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

```typescript
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.',
})
```

```typescript
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.',
})
```