En bref

Claude Code propose deux mécanismes pour faire travailler plusieurs agents en parallèle : Agent Tool (sous-agents) et Agent Teams (teammates). Ils ne font pas la même chose et ne s’utilisent pas dans les mêmes situations.

Agent Tool lance des agents indépendants depuis votre session principale. Chaque agent reçoit un prompt, exécute sa tâche, retourne un résultat. Simple, rapide, observable.

Agent Teams crée une équipe de sessions coordonnées qui peuvent se parler entre elles via une mailbox. La session principale joue le rôle de lead, les autres sont des teammates.

La règle de départ : si vos tâches sont indépendantes les unes des autres, utilisez Agent Tool. Si vos agents ont besoin de se transmettre des informations pendant l’exécution, envisagez Agent Teams.

Prérequis

  • Claude Code installé (v2.1.77 minimum recommandé)
  • Un compte avec Tier 2 minimum pour le dispatch multi-agents
  • Pour Agent Teams : activer la feature expérimentale via CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 dans votre settings.json (documentation officielle)
  • Pour Agent Tool : aucune configuration supplémentaire — disponible par défaut (documentation officielle)

Étapes

1. Identifier le type de parallélisme dont vous avez besoin

La première question à poser n’est pas “lequel est le meilleur” — c’est “est-ce que mes sous-tâches sont interdépendantes ?”.

Tâche embarrassingly parallel : chaque agent travaille sur sa portion sans avoir besoin des résultats des autres. Exemple : analyser 6 fichiers de documentation indépendants, extraire des données de 10 sources distinctes, générer des résumés en parallèle.

Tâche avec dépendances inter-agents : un agent a besoin du résultat d’un autre pour continuer. Exemple : agent A conçoit l’architecture → agent B implémente en se basant sur la sortie d’A → agent C teste en se basant sur l’implémentation de B.

2. Choisir le mécanisme

CritèreAgent ToolAgent Teams
Tâches indépendantes (parallèle pur)RecommandéSurdimensionné
Dépendances inter-agents réellesNon adaptéRecommandé
Communication bidirectionnelle nécessaireNonOui (mailbox)
Contrôle du modèle (Haiku / Sonnet / Opus)OuiNon — Opus forcé
Signal d’erreur exploitableOui — texte retournéPartiel
Métriques de tokens mesurablesOuiNon
Feature stableOuiExpérimentale

3. Comprendre les performances réelles

Nos tests montrent des écarts significatifs entre les deux mécanismes sur une tâche de croisement documentaire (même type de travail, même volume de données) :

Vitesse : Agent Tool complète en 97 secondes, Agent Teams en 201 secondes — soit 2,07x plus lent pour Agent Teams.

Qualité : sur une tâche d’identification d’incohérences entre fichiers, Agent Tool a trouvé 53 incohérences contre 32 pour Agent Teams. Agent Teams a produit 40 % de résultats en moins.

Communication inter-agents : sur cette même tâche, le nombre de messages échangés entre les teammates via la mailbox était de 0. La feature de communication — l’argument principal pour utiliser Agent Teams — n’a pas été activée, car la tâche ne la nécessitait pas.

Interprétation : Agent Teams n’améliore pas la qualité sur les tâches parallèles pures. Il introduit un overhead (TeamCreate, spawn, réveil des teammates) sans gain observable.

4. Utiliser Agent Tool — les points clés

Agent Tool permet de contrôler le modèle par sous-tâche. C’est utile pour optimiser coût et vitesse :

  • Haiku : tâches d’extraction simple, résumé, catégorisation. Temps de réponse 1-5 secondes. Attention : Haiku consomme environ 25 K tokens par appel contre 14 K pour Sonnet/Opus sur un prompt identique — son contexte système est plus lourd.
  • Sonnet : analyse, synthèse, conception, comparaison de sources. Temps de réponse 2-10 secondes.
  • Opus : uniquement pour les tâches de raisonnement complexe ou les sessions longues (>100 K tokens). Nos tests ne montrent aucun gain de qualité Opus vs Sonnet sur les tâches analytiques documentaires standard.

Chaque sous-agent a un budget contexte indépendant d’environ 100 K tokens. Ce n’est pas un pool partagé : 10 agents parallèles ne se disputent pas un budget commun.

Agent Tool supporte sans problème les tâches longues (146 secondes confirmées, 27 appels d’outils, sans timeout). La limite haute n’est pas documentée.

5. Utiliser Agent Teams — les conditions réelles

Agent Teams est pertinent quand la communication entre agents pendant l’exécution est réellement nécessaire. La documentation officielle identifie quatre cas d’usage forts : recherche multi-angle, développement de modules distincts, débogage par hypothèses concurrentes, coordination cross-couche (frontend / backend / tests).

Deux contraintes à intégrer avant de choisir Agent Teams :

Éphémère : les tâches complétées sont purgées du disque après la session. Les teammates sont retirés de la configuration après shutdown. /resume ne restaure pas l’équipe.

Modèle non contrôlable : les teammates utilisent Opus, indépendamment du modèle demandé. Le contrôle modèle par agent — possible avec Agent Tool — n’est pas disponible en Agent Teams.

6. Arbre de décision rapide

Mes tâches sont-elles indépendantes ?
├── Oui → Agent Tool
│   ├── Tâche simple (extraction, résumé) → modèle Haiku
│   ├── Tâche analytique (comparaison, synthèse) → modèle Sonnet
│   └── Tâche complexe / long run → modèle Opus
└── Non (dépendances inter-agents)
    ├── Dépendances linéaires → séquencer plusieurs Agent Tool
    └── Communication bidirectionnelle nécessaire → Agent Teams

Pièges courants

Utiliser Agent Teams par défaut sur du parallélisme pur. C’est le piège le plus fréquent. Agent Teams est conçu pour la coordination, pas pour accélérer des tâches indépendantes. Sur ces tâches, il est plus lent et produit moins de résultats.

Supposer que la mailbox sera utilisée automatiquement. Les agents ne se parlent pas spontanément. La communication inter-agents doit être explicitement orchestrée dans le prompt. Sur une tâche qui ne nécessite pas de coordination, la mailbox ne sera pas activée.

Ne pas vérifier les livrables après exécution. Agent Tool retourne un signal textuel exploitable en cas d’échec (fichier absent, commande refusée). Agent Teams peut terminer sans erreur mais sans avoir produit le résultat attendu — son observabilité est inférieure.

Supposer un budget partagé entre agents parallèles. Chaque sous-agent Agent Tool a son propre budget (~100 K tokens). Lancer 10 agents en parallèle ne réduit pas le budget disponible par agent.

Isoler des branches avec Sonnet ou Haiku en worktree. Le paramètre isolation: "worktree" d’Agent Tool fonctionne uniquement avec Opus. Sonnet et Haiku finissent par committer sur main malgré le worktree — nos tests l’ont confirmé sur 3 exécutions.

Ce qu’il faut retenir

  • Agent Tool est adapté aux tâches indépendantes (parallèle pur) ; Agent Teams est conçu pour les workflows avec dépendances inter-agents réelles.
  • Agent Teams est 2 fois plus lent qu’Agent Tool sur des tâches parallèles et produit 40 % de résultats en moins dans nos mesures.
  • La mailbox de communication ne s’active pas spontanément : elle doit être orchestrée explicitement dans le prompt.
  • Agent Teams est une feature expérimentale : les teammates disparaissent après shutdown et le modèle est fixé à Opus sans paramètre configurable.
  • L’isolation worktree d’Agent Tool n’est fiable qu’avec Opus ; Sonnet et Haiku commitent sur main tout en rapportant être dans leur worktree isolé.

Sources