Note de l'auteur : Un guide pas à pas pour activer et utiliser la fonction de collaboration multi-agents Claude 4.6 Agent Teams. Maîtrisez l'architecture Lead + Teammate, l'allocation des tâches, la communication par messages et les techniques pratiques.
Lors de la sortie de Claude Opus 4.6, Anthropic a simultanément lancé la fonctionnalité Agent Teams (Équipes d'agents), permettant à plusieurs instances de Claude de collaborer en parallèle comme une véritable équipe de développement. Beaucoup de développeurs s'interrogent : comment activer Agent Teams ? Comment le déclencher ? Quelle est la différence avec un Subagent ? Pour quels scénarios est-ce adapté ?
Valeur ajoutée : En lisant cet article, vous maîtriserez le flux de travail complet d'Agent Teams — de la configuration à l'activation, de la répartition des tâches à la collaboration d'équipe, pour vous lancer immédiatement dans la programmation multi-agents.
Qu'est-ce que Claude Agent Teams ?
Agent Teams est une fonctionnalité expérimentale de Claude Code (en phase de prévisualisation de recherche). Elle vous permet d'exécuter simultanément plusieurs instances indépendantes de Claude Code au sein d'un même projet, collaborant via un système de liste de tâches partagée et de messagerie.
En résumé : Agent Teams = un Lead (chef d'équipe) + plusieurs Teammates (coéquipiers), travaillant chacun de manière indépendante, communiquant entre eux et accomplissant ensemble des tâches complexes.
| Dimension de comparaison | Subagent (Sous-agent) | Agent Teams (Équipe) |
|---|---|---|
| Mode de communication | Rapporte uniquement au Lead | Les coéquipiers peuvent communiquer directement |
| Mode de coordination | Le Lead gère tout | Liste de tâches partagée + auto-attribution |
| Contexte | Contexte isolé, résultat renvoyé à l'appelant | Contexte isolé, autonomie totale |
| Meilleur scénario | Tâches ciblées nécessitant juste un résultat | Tâches complexes nécessitant discussion et collaboration |
| Consommation de Tokens | Plus faible (résultats agrégés au contexte principal) | Plus élevée (chaque coéquipier est une instance Claude indépendante) |
Architecture de base de Claude Agent Teams
Agent Teams est composé de 4 éléments clés :
| Composant | Responsabilité | Description |
|---|---|---|
| Lead Agent | Chef d'équipe | Votre session Claude Code principale, responsable de la création de l'équipe, de l'attribution des tâches et de la synthèse des résultats |
| Teammate | Coéquipier | Instances Claude Code indépendantes, exécutant chacune les tâches assignées |
| Task List | Liste de tâches partagée | Tableau de bord visible par tous, supportant l'attribution, les dépendances et le suivi d'état |
| Mailbox | Système de messagerie | Canal de communication entre coéquipiers, supportant les messages privés et les diffusions (broadcast) |
💡 Différence clé : Le Subagent fonctionne sur un mode "subordonné-rapport", tandis qu'Agent Teams fonctionne sur un mode "collaboration d'équipe". Si votre tâche nécessite des discussions entre plusieurs personnes, des remises en question de points de vue ou le traitement parallèle de différents modules, Agent Teams est le meilleur choix.
Comment activer Claude Agent Teams
Agent Teams est désactivé par défaut, il faut donc l'activer manuellement. Voici les 3 méthodes pour le faire :
Étape 1 : Activer la fonctionnalité expérimentale
Méthode A — Fichier de configuration (recommandé)
Ajoutez ceci dans le fichier settings.json de Claude Code :
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
Méthode B — Variable d'environnement
# À ajouter dans votre .bashrc ou .zshrc
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
Méthode C — Session unique
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude
Étape 2 : Déclencher Agent Teams en langage naturel
Il n'y a pas de commande slash comme /agent-teams. Une fois la fonction activée, il vous suffit de décrire l'équipe que vous souhaitez en langage naturel :
Crée une équipe d'agents pour réviser la PR #142. Génère trois réviseurs :
- Un focalisé sur les failles de sécurité
- Un pour vérifier l'impact sur les performances
- Un pour valider la couverture des tests
Demande-leur de faire leur révision respective puis de rapporter leurs conclusions.
Ou plus simplement :
Create a team with 4 teammates to refactor these modules in parallel.
Use Sonnet for each teammate.
Claude créera automatiquement l'équipe, générera les coéquipiers et attribuera les tâches. Claude peut aussi proposer de lui-même de créer une équipe s'il juge que votre tâche est adaptée à un traitement en parallèle, mais il vous demandera toujours confirmation avant.
Étape 3 : Choisir le mode d'affichage
| Mode d'affichage | Description | Environnement adapté |
|---|---|---|
| in-process (par défaut) | Tous les agents s'exécutent dans le terminal principal | N'importe quel terminal, y compris VS Code |
| tmux | Chaque agent a son propre panneau indépendant | Nécessite tmux ou iTerm2 |
| auto | Détection automatique | Utilise le split-screen si tmux est actif, sinon in-process |
# Spécifier via la ligne de commande
claude --teammate-mode tmux
# Ou configurer dans settings.json
{
"teammateMode": "tmux"
}
Conseil : Pour une première utilisation, je vous suggère le mode in-process. Une fois familiarisé, essayez le mode split-screen avec tmux. En utilisant les crédits API Claude via APIYI (apiyi.com), vous pourrez tester sereinement toutes les configurations d'Agent Teams en local.
Guide d'utilisation de Claude Agent Teams
Aide-mémoire des raccourcis clavier
Pendant que Agent Teams est en cours d'exécution, vous pouvez utiliser les raccourcis suivants :
| Raccourci | Fonction |
|---|---|
| Shift+Haut/Bas | Changer/sélectionner un coéquipier |
| Entrée | Voir les détails de la session du coéquipier sélectionné |
| Échap | Interrompre l'opération en cours du coéquipier |
| Ctrl+T | Basculer vers la vue de la liste des tâches |
| Shift+Tab | Basculer le mode délégation (le Lead coordonne sans coder) |
Mécanisme d'attribution et de récupération des tâches
Le système de tâches d'Agent Teams prend en charge 3 statuts et des relations de dépendance :
Statut des tâches : pending (en attente) → in_progress (en cours) → completed (terminé)
Mécanisme de dépendance : Les tâches peuvent définir une dépendance blockedBy. Une fois la tâche parente terminée, la tâche en aval est automatiquement débloquée, sans intervention manuelle.
Modes d'attribution :
- Assignation par le Lead : Dites explicitement au Lead d'attribuer une tâche spécifique à un coéquipier.
- Auto-attribution : Une fois sa tâche actuelle terminée, le coéquipier récupère automatiquement la prochaine tâche disponible non assignée.
- Verrouillage de fichier anti-concurrence : Si plusieurs coéquipiers tentent de récupérer la même tâche en même temps, le système utilise un verrouillage de fichier pour éviter les conflits.
Conseils sur la taille des tâches : La meilleure pratique consiste à attribuer 5 à 6 tâches par coéquipier. Si les tâches sont trop petites, les frais de coordination dépassent les bénéfices ; si elles sont trop grandes, le coéquipier mettra trop de temps à rapporter ses progrès.
Moyens de communication entre coéquipiers
| Type de communication | Description | Cas d'utilisation |
|---|---|---|
| write (message privé) | Envoie un message à un coéquipier spécifique | Coordonner un point précis |
| broadcast (diffusion) | Envoie un message à tous les coéquipiers | Annonces importantes (à utiliser avec parcimonie, le coût augmente avec la taille de l'équipe) |
La communication est point à point, elle n'a pas besoin de passer par le Lead. N'importe quel coéquipier peut envoyer directement un message à un autre.
Collaboration Git et évitement des conflits de fichiers
La règle d'or dans Agent Teams : deux coéquipiers modifiant le même fichier provoqueront des écrasements.
Stratégie de répartition des fichiers recommandée :
# Exemple de développement de fonctionnalité Full-stack
Coéquipier Backend → Responsable de src/api/ et src/migrations/
Coéquipier Frontend → Responsable de src/components/
Coéquipier Test → Responsable de tests/
⚠️ Important : Les coéquipiers d'Agent Teams partagent le même répertoire de travail et n'utilisent pas automatiquement
git worktree. S'assurer que chaque coéquipier est responsable d'un ensemble de fichiers différent est la clé pour éviter les conflits.
5 scénarios réels pour Claude Agent Teams
Scénario 1 : Revue de code multi-angle
Crée une équipe d'agents pour examiner cette PR :
- Réviseur sécurité : vérifie les injections, XSS, permissions et autres failles.
- Réviseur performance : analyse les requêtes N+1, les fuites de mémoire, les stratégies de cache.
- Réviseur de tests : valide la couverture de tests et les cas limites.
Demande-leur de rapporter leurs conclusions après leurs examens respectifs.
Pourquoi c'est adapté à Agent Teams : Les trois dimensions de revue sont totalement indépendantes, ne génèrent pas de conflits de fichiers et peuvent être exécutées en parallèle.
Scénario 2 : Développement parallèle de nouveaux modules
Crée une équipe pour construire le système de notification utilisateur :
- Coéquipier 1 : Construire l'API backend (src/api/notifications/)
- Coéquipier 2 : Construire les composants frontend (src/components/notifications/)
- Coéquipier 3 : Écrire les tests d'intégration (tests/notifications/)
Pourquoi c'est adapté : Chaque coéquipier est responsable d'un répertoire différent, ce qui assure une isolation naturelle. Il suffit de fusionner une fois terminé.
Scénario 3 : Débogage d'hypothèses concurrentes
Il y a un bug intermittent, crée une équipe pour déboguer avec différentes hypothèses :
- Coéquipier A : Cherche s'il s'agit d'une condition de concurrence (race condition).
- Coéquipier B : Cherche s'il s'agit d'une fuite de mémoire.
- Coéquipier C : Cherche s'il s'agit d'un timeout d'une API tierce.
Chacun valide son hypothèse indépendamment et fait son rapport.
Pourquoi c'est adapté : Débogage contradictoire, plusieurs pistes sont explorées en parallèle, le premier qui trouve la cause racine gagne.
Scénario 4 : Coordination de modifications multi-couches
Lorsqu'une modification traverse le frontend, le backend et la base de données, Agent Teams permet aux experts de chaque couche de faire leur travail tout en coordonnant les définitions d'interface via le système de messagerie.
Scénario 5 : Recherche exploratoire
Je conçois un outil CLI pour suivre les commentaires TODO dans le code.
Crée une équipe pour explorer sous différents angles :
- Un coéquipier responsable du design de l'expérience utilisateur (UX).
- Un coéquipier responsable de l'architecture technique.
- Un coéquipier jouant le rôle de "l'avocat du diable" (devil's advocate).
Pourquoi c'est adapté : Confrontation de points de vue, remise en question mutuelle des hypothèses et des conclusions.
Guide de sélection : Claude Agent Teams vs Subagent
| Dimension de décision | Choisir Subagent | Choisir Agent Teams |
|---|---|---|
| Les coéquipiers doivent-ils communiquer ? | ❌ Non | ✅ Oui |
| Les tâches sont-elles parallélisables ? | Partiellement | ✅ Hautement parallélisables |
| Édition multi-fichiers impliquée ? | ✅ Sûr pour le même fichier | ⚠️ Nécessite une répartition pour éviter les conflits |
| Complexité de la tâche ? | Focalisé sur un seul objectif | Multi-angles, multi-modules |
| Budget de tokens ? | 💰 Plus économique | 💸 Environ 3 à 7 fois plus de consommation |
| Besoin de discussion/remise en question ? | ❌ | ✅ |
Référence de coût : Une équipe Agent Teams de 3 personnes fonctionnant pendant 30 minutes consomme environ 3 à 4 fois plus de tokens qu'une session unique. En mode Plan, comptez environ 7 fois plus. Il est recommandé de gérer votre budget de tokens de manière flexible via APIYI (apiyi.com).
Astuces avancées pour Claude Agent Teams
Astuce 1 : Modèles mixtes pour réduire les coûts
Crée une équipe où le Lead utilise Opus et les 4 coéquipiers utilisent Sonnet.
Le Lead s'occupe des décisions stratégiques avec Opus 4.6 pour garantir la qualité, tandis que les coéquipiers exécutent les tâches spécifiques avec Sonnet pour maîtriser les coûts.
Astuce 2 : Workflow d'approbation de plan (Plan)
Génère un coéquipier architecte pour refactoriser le module d'authentification.
Exige qu'il soumette un plan pour approbation avant toute modification.
Le coéquipier passera d'abord en mode Plan (lecture seule). Une fois le plan terminé, il enverra une demande d'approbation au Lead. Le coéquipier ne commencera l'implémentation qu'après l'approbation du Lead.
Astuce 3 : Mode délégation pour éviter que le Lead ne "mette la main à la pâte"
Appuyez sur Shift+Tab pour activer le mode délégation. De cette façon, le Lead se contente de coordonner et d'attribuer les tâches, sans écrire de code lui-même. Cela évite que le Lead ne "pique le boulot" des autres.
Astuce 4 : Quality Gate Hooks (Barrières de qualité)
Utilisez le mécanisme de Hook pour contrôler automatiquement la qualité :
TeammateIdle: Se déclenche quand un coéquipier est sur le point de se mettre en veille. Un code de sortie 2 permet d'envoyer un feedback pour qu'il continue de travailler.TaskCompleted: Se déclenche quand une tâche est marquée comme terminée. Un code de sortie 2 permet de bloquer la finalisation et d'exiger des modifications.
Points d'attention sur Claude Agent Teams
Limitations connues
- Pas de reprise de session : Les commandes
/resumeet/rewindne restaurent pas les coéquipiers dont la session a été fermée. - Une équipe par session : Le Lead ne peut gérer qu'une seule équipe à la fois.
- Pas d'équipes imbriquées : Les coéquipiers ne peuvent pas créer leur propre équipe à leur tour.
- Héritage des permissions : Les coéquipiers héritent du mode de permission du Lead, mais celles-ci peuvent être ajustées individuellement après leur création.
- Limitations du mode écran scindé : Le partitionnement d'écran via tmux n'est pas supporté par le terminal intégré de VS Code, Windows Terminal ou Ghostty.
- Crash d'un coéquipier : Si un coéquipier plante, un délai d'attente (heartbeat) de 5 minutes est déclenché, après quoi ses tâches peuvent être reprises par d'autres membres de l'équipe.
Bonnes pratiques
- Taille de l'équipe : Nous recommandons entre 2 et 5 coéquipiers. Une équipe de 3 est souvent plus efficace qu'une équipe de 6.
- La décomposition des tâches prime sur le nombre : Une équipe de 6 personnes avec une mauvaise répartition des tâches sera moins performante qu'une équipe de 3 bien organisée.
- Tâches intensives en lecture (revue de code, recherche) : C'est le domaine de prédilection ("sweet spot") d'Agent Teams.
- Édition concurrente intensive en écriture : Cela reste un défi de taille qui nécessite une répartition très stricte des fichiers de travail.
Questions Fréquentes (FAQ)
Q1 : Quel abonnement faut-il pour utiliser Agent Teams ?
Agent Teams est une fonctionnalité expérimentale de Claude Code. Elle nécessite un abonnement Claude Max (entre 100 et 200 $/mois) pour bénéficier d'un quota suffisant d'utilisation d'Opus 4.6. Pour les utilisateurs de l'API, la facturation se fait au tarif standard d'Opus 4.6 (5 $ / 25 $ par million de tokens). Vous pouvez également passer par la plateforme APIYI (apiyi.com) pour obtenir des solutions de facturation plus flexibles.
Q2 : Agent Teams impose-t-il l’utilisation exclusive d’Opus 4.6 ?
Non. Bien qu'Agent Teams ait été lancé avec Opus 4.6, vous pouvez mélanger les modèles. La configuration recommandée est d'utiliser Opus 4.6 pour le Lead (prise de décision stratégique) et Sonnet pour les coéquipiers (exécution des tâches spécifiques). Cela permet de maintenir une excellente coordination tout en maîtrisant les coûts.
Q3 : Agent Teams fonctionne-t-il dans VS Code ?
Oui, mais avec certaines restrictions. Le terminal intégré de VS Code supporte le mode "in-process" (où tous les coéquipiers tournent dans le même terminal). Cependant, le mode écran scindé via tmux n'est pas disponible dans VS Code ; pour en profiter, vous devrez utiliser un terminal externe.
Résumé
Les points clés de Claude 4.6 Agent Teams :
- Mode d'activation : Définissez la variable d'environnement
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, puis décrivez votre équipe en langage naturel. - Modèle d'architecture : Un Lead Agent coordonne tandis que les Teammate Agents travaillent en parallèle, collaborant via une liste de tâches partagée et un système de messagerie.
- Meilleurs scénarios : Revue de code, développement parallèle de nouveaux modules, débogage d'hypothèses concurrentes, coordination multi-couches et recherche exploratoire.
- Principe fondamental : La décomposition des tâches est plus importante que le nombre d'agents ; 3 coéquipiers sont souvent plus efficaces que 6.
- Contrôle des coûts : Le modèle hybride (Opus pour le Lead + Sonnet pour les coéquipiers) représente le meilleur rapport performance-prix.
Agent Teams fait passer la programmation IA de l'ère du « combat en solo » à celle de la « collaboration d'équipe ». Bien qu'encore en phase de préversion (research preview), cette fonctionnalité démontre déjà une puissance de développement parallèle impressionnante.
Nous vous recommandons de passer par APIYI (apiyi.com) pour obtenir vos quotas d'API Claude. La plateforme propose une facturation flexible et supporte plusieurs modèles, ce qui facilite le test des différentes configurations d'Agent Teams.
📚 Ressources
⚠️ Note sur le format des liens : Tous les liens externes utilisent le format
Nom de la ressource : domain.com. Ils sont faciles à copier mais ne sont pas cliquables pour éviter la perte de poids SEO.
-
Documentation officielle de Claude Code Agent Teams : Guide complet d'utilisation d'Agent Teams.
- Lien :
code.claude.com/docs/en/agent-teams - Description : Documentation officielle incluant les méthodes d'activation, les détails de l'architecture et les meilleures pratiques.
- Lien :
-
Blog d'ingénierie d'Anthropic — Cas du compilateur C : 16 agents Claude construisant un compilateur C en parallèle.
- Lien :
anthropic.com/engineering/building-c-compiler - Description : Étude de cas réelle à grande échelle : plus de 2000 sessions pour produire 100 000 lignes de code.
- Lien :
-
Addy Osmani — Claude Code Swarms : Analyse approfondie d'Agent Teams par le responsable ingénierie de Google.
- Lien :
addyosmani.com/blog/claude-code-agent-teams - Description : Analyse de l'architecture et recommandations sur les meilleures pratiques.
- Lien :
-
Annonce de sortie de Claude Opus 4.6 : Note de version officielle.
- Lien :
anthropic.com/news/claude-opus-4-6 - Description : Présentation officielle de la fonctionnalité Agent Teams.
- Lien :
Auteur : Équipe APIYI
Échanges techniques : N'hésitez pas à discuter de votre expérience avec Claude Agent Teams dans la section commentaires. Pour plus de ressources, visitez la communauté technique d'APIYI sur apiyi.com.
