Accueil › Glossaire › Swarm

Swarm (OpenAI)

Swarm est un framework expérimental et éducatif publié par l’équipe Solutions d’OpenAI en octobre 2024, qui explore l’orchestration multi-agents légère via deux primitives minimalistes : des agents (instructions + outils) et des handoffs (transferts explicites de contrôle entre agents). Il a été officiellement remplacé par le SDK OpenAI Agents en mars 2025.

Swarm n’a jamais été conçu comme un outil de production. C’est un « design de référence » : un framework volontairement minimaliste qui capture l’essence de l’orchestration multi-agents dans un code simple et lisible. Son objectif est pédagogique. Il montre comment coordonner des agents spécialisés qui se passent le relais (handoffs) pour résoudre des tâches complexes, le tout alimenté par l’API Chat Completions d’OpenAI, sans état persistant entre les appels.

L’importance de Swarm ne réside pas dans sa robustesse technique (il n’en a pas), mais dans les concepts qu’il a popularisés : le handoff comme primitive de coordination multi-agents, les variables de contexte partagées, et l’idée qu’un « agent » peut aussi bien être un personnage (« l’agent de support ») qu’un workflow spécialisé (« l’étape de validation »). Ces concepts sont aujourd’hui au cœur du SDK OpenAI Agents, d’Agency Swarm, et de nombreux autres frameworks.

Architecture et fonctionnement

Deux primitives, pas de magie

Swarm repose sur exactement deux concepts :

Agent : un ensemble d’instructions (prompt système), de fonctions (outils), et de paramètres par défaut. Un agent encapsule un comportement spécialisé. Le CEO gère la communication client, le développeur écrit du code, le support technique résout des problèmes. Mais un agent peut aussi représenter un workflow ou une étape spécifique (la validation, le routage, l’enrichissement de données).

Handoff : un transfert explicite de contrôle d’un agent à un autre. Quand un agent détermine qu’un autre agent est mieux placé pour traiter la requête, il effectue un handoff. Le nouvel agent reçoit l’historique de conversation complet et prend le relais. C’est le mécanisme central de coordination dans Swarm : pas de superviseur global, pas de graphe d’état, juste des agents qui se passent le ballon.

Stateless by design

Swarm est entièrement alimenté par l’API Chat Completions et ne stocke aucun état entre les appels. La fonction client.run() est analogue à chat.completions.create() : elle prend des messages en entrée, les traite (potentiellement avec plusieurs tours, handoffs, et appels d’outils), et retourne une réponse avec les messages mis à jour, le dernier agent actif, et les variables de contexte.

Pour maintenir une conversation multi-tours, vous passez manuellement les messages et les variables de contexte de la réponse précédente dans l’appel suivant. C’est comme un jeu vidéo sans sauvegarde automatique : vous devez gérer l’état vous-même. Ce choix de design est volontaire : il garde le framework simple et compréhensible, mais le rend inadapté à la production où la persistance est indispensable.

Variables de contexte

Les variables de contexte sont un dictionnaire partagé entre les agents d’un même appel run(). Elles permettent de passer des informations (identifiant utilisateur, préférences, données de session) entre les agents sans les injecter dans les messages de conversation. Les outils peuvent lire et modifier les variables de contexte, et les modifications sont reflétées dans la réponse finale.

La boucle d’exécution

Au cœur de client.run(), Swarm implémente une boucle simple :

1. L’agent courant reçoit l’historique de conversation et ses instructions. 2. Le modèle génère une réponse, potentiellement avec des appels d’outils. 3. Si un outil est appelé, Swarm l’exécute et ajoute le résultat aux messages. 4. Si l’outil retourne un autre Agent (handoff), cet agent devient l’agent courant. 5. La boucle continue jusqu’à ce que le modèle retourne une réponse textuelle sans appel d’outil.

C’est élégant dans sa simplicité. Toute la complexité de l’orchestration multi-agents se réduit à des fonctions Python qui retournent soit une réponse, soit un autre agent. Pas de graphe, pas de machine à états, pas de bus de messages.

Pattern typique : le triage agent

Le cas d’usage le plus emblématique de Swarm est le pattern de triage. Un agent « trieur » reçoit la requête de l’utilisateur, détermine l’intention (facturation, support technique, gestion de compte), et effectue un handoff vers l’agent spécialisé correspondant. L’agent spécialisé traite la demande et peut retourner le contrôle au trieur ou transférer à un autre spécialiste.

Ce pattern s’aligne directement avec le pattern orchestrateur-worker utilisé en production dans les systèmes de support client, les assistants virtuels, et les pipelines de traitement de demandes. Swarm montre les mécanismes sous-jacents de ce pattern dans un code lisible et minimal. Le trieur n’a pas besoin d’être intelligent : il doit juste identifier l’intention et router vers le bon spécialiste. La spécialisation est dans les agents de destination, pas dans le routeur.

D’autres cas d’usage explorés dans les exemples officiels incluent la gestion de comptes bancaires (agents pour les transferts, l’historique, le service client), le support technique multi-niveaux (triage, diagnostic, escalade), et l’automatisation de workflows simples (collecte d’informations, validation, exécution). Chaque exemple illustre comment décomposer un problème complexe en agents spécialisés qui collaborent via des handoffs.

Le pattern fonctionne bien jusqu’à environ 5 à 8 agents spécialisés. Au-delà, la complexité des routes de handoff augmente et il devient difficile de maintenir une vue d’ensemble cohérente du système. C’est l’une des raisons pour lesquelles les frameworks de production (LangGraph, CrewAI) proposent des abstractions d’orchestration plus structurées (graphes, crews, workflows).

Swarm → SDK OpenAI Agents

Le SDK OpenAI Agents, publié en mars 2025, est l’évolution production-ready de Swarm. Il conserve les mêmes primitives fondamentales (Agents, Handoffs) mais ajoute tout ce qui manquait à Swarm pour la production :

Guardrails : validation des entrées et sorties des agents, avec des règles de sécurité et de conformité configurables. C’est l’équivalent des guardrails de safety que Swarm n’avait pas du tout.

Tracing intégré : visualisation, débogage et monitoring des workflows agentiques avec le dashboard OpenAI. Chaque appel, chaque handoff, chaque utilisation d’outil est tracé et visualisable. Swarm n’avait qu’un flag debug basique.

Agents vocaux temps réel : construction d’agents vocaux avec détection automatique d’interruption, gestion du contexte, guardrails, et plus. C’est une fonctionnalité entièrement nouvelle absente de Swarm.

Sessions et persistance : gestion de l’état entre les tours de conversation, avec sessions persistantes. Le problème stateless fondamental de Swarm est résolu.

Évaluation et fine-tuning : les traces du SDK Agents alimentent directement les outils d’évaluation, de fine-tuning, et de distillation d’OpenAI. Vous pouvez améliorer vos agents de manière continue à partir des données de production. C’est un avantage significatif de l’écosystème OpenAI : le cycle observation → évaluation → amélioration → déploiement est intégré dans une seule plateforme.

Le SDK Agents a aussi étendu les capacités avec AgentKit, annoncé lors du DevDay d’octobre 2025, qui fournit un toolkit enterprise élargi pour les déploiements à grande échelle. Le SDK reste Python-first (pas de support TypeScript officiel), mais son intégration étroite avec les modèles GPT-5.4 et les API Responses d’OpenAI en fait le chemin le plus direct pour les équipes investies dans l’écosystème OpenAI.

Swarm vs. alternatives

Swarm est un outil d’apprentissage, pas un concurrent des frameworks de production. Si vous voulez comprendre le concept de handoff multi-agent, Swarm est le meilleur point de départ grâce à sa simplicité. Pour construire des agents en production, utilisez le SDK OpenAI Agents (écosystème OpenAI), CrewAI (multi-agents avec rôles, multi-modèle), ou LangGraph (orchestration flexible avec checkpointing).

Limites fondamentales

Pas de persistance : aucun état n’est sauvegardé entre les appels. Vous devez gérer manuellement la continuité des conversations, ce qui devient rapidement ingérable pour des cas réels.

Pas de guardrails : aucun mécanisme de validation des entrées/sorties, de filtrage de contenu, ou de limite de sécurité. Un agent peut théoriquement appeler n’importe quel outil sans restriction.

Pas de tracing : pas de dashboard, pas de span data, pas de replay d’exécution. Le débogage se fait via la console Python avec le flag debug.

OpenAI uniquement : alimenté exclusivement par l’API Chat Completions d’OpenAI. Pas de support pour Anthropic, Google, Mistral, ou des modèles locaux. C’est un framework dans l’écosystème OpenAI, pour l’écosystème OpenAI.

Scalabilité limitée : le pattern handoff fonctionne bien avec 2 à 5 agents spécialisés, mais devient complexe à gérer au-delà de 8 à 10 types d’agents. Les chaînes de handoffs longues peuvent perdre le contexte et dégrader la qualité des réponses.

Client-side uniquement : Swarm tourne entièrement côté client. Pas de service managé, pas de scaling automatique, pas de haute disponibilité. C’est un script Python, pas une infrastructure.

L’héritage de Swarm

Malgré son statut éducatif, Swarm a eu un impact considérable sur l’écosystème des agents IA :

Agency Swarm (VRSEN) a construit un framework de production complet en étendant les concepts de Swarm avec des flux de communication directionnels, un déploiement FastAPI, un suivi de coûts, et un support multi-modèle via LiteLLM. En v1.x, Agency Swarm est directement basé sur le SDK OpenAI Agents (le successeur de Swarm), démontrant la continuité conceptuelle entre le projet éducatif et les solutions de production.

Le pattern handoff est devenu un standard dans les frameworks multi-agents. Le Microsoft Agent Framework l’intègre comme pattern d’orchestration (à côté du séquentiel, parallèle et group chat). CrewAI l’implémente dans ses Flows. Le SDK Anthropic pour Claude reprend des concepts similaires avec les sub-agents. Le concept d’agent comme « ensemble d’instructions + outils » est devenu la norme dans toute l’industrie.

Les variables de contexte partagées de Swarm ont inspiré des mécanismes similaires dans d’autres frameworks, bien que la plupart aient opté pour des solutions plus robustes : état typé avec checkpointing dans LangGraph, mémoire multi-types (court-terme, long-terme, entités, contextuelle) dans CrewAI, sessions persistantes dans le SDK OpenAI Agents.

Le choix de design « deux primitives, pas de magie » a aussi influencé la philosophie de plusieurs frameworks qui ont adopté une approche minimaliste et composable. L’idée que vous pouvez construire des systèmes multi-agents complexes à partir de primitives simples (agents et transferts) est devenue un principe de design respecté.

Enfin, Swarm a démontré que l’orchestration multi-agents ne nécessite pas forcément un framework lourd avec des dizaines d’abstractions. Un script Python de quelques centaines de lignes peut capturer l’essence du concept. Cette leçon a encouragé de nombreux développeurs à construire leurs propres solutions légères plutôt que d’adopter des frameworks complexes quand leur cas d’usage ne l’exige pas.

Prise en main (éducatif)

Cet exemple crée un système de triage minimal : le premier agent analyse la demande et peut la transférer à l’agent de support via un handoff (la fonction transfer_to_support retourne un autre Agent). C’est le pattern fondamental de Swarm en 10 lignes de code.

Verdict

Swarm est le meilleur outil pédagogique pour comprendre l’orchestration multi-agents par handoffs. En deux primitives et quelques dizaines de lignes de code, il capture l’essence d’un système où des agents spécialisés collaborent en se passant le contrôle de la conversation. C’est élégant, lisible, et intellectuellement satisfaisant.

Mais c’est tout ce que c’est. Swarm n’a pas de persistance, pas de guardrails, pas de tracing, pas de support multi-modèle, et n’est plus maintenu. OpenAI l’a explicitement remplacé par le SDK Agents, qui reprend les mêmes concepts avec la robustesse nécessaire pour la production.

Notre recommandation : étudiez le code de Swarm pour comprendre les concepts (30 minutes bien investies), puis construisez vos agents avec le SDK OpenAI Agents (pour l’écosystème OpenAI), CrewAI (pour le multi-agent généraliste), ou LangGraph (pour l’orchestration avancée). L’héritage conceptuel de Swarm vit dans tous ces frameworks.