Accueil › Glossaire › Agency Swarm

Agency Swarm

Agency Swarm est un framework Python open source pour construire des « agences » d’agents IA collaboratifs, qui étend le SDK OpenAI Agents avec une couche d’orchestration structurée inspirée des organigrammes d’entreprise réels, permettant de définir des rôles d’agents (CEO, développeur, assistant) avec des flux de communication directionnels.

L’idée fondatrice d’Agency Swarm est de penser l’automatisation IA en termes de structures organisationnelles réelles. Vous ne construisez pas un agent monolithique : vous construisez une agence avec un CEO qui dirige, un développeur qui code, un assistant virtuel qui gère les tâches administratives, et chacun communique selon un organigramme défini. Cette métaphore organisationnelle rend la conception de systèmes multi-agents intuitive pour les utilisateurs qui pensent en termes d’équipes et de processus métier.

Créé par Arsenii Shatokhin (VRSEN), le framework a évolué en version 1.x pour cibler le SDK OpenAI Agents et l’API Responses, tout en supportant d’autres fournisseurs de modèles (Anthropic, Google, xAI) via LiteLLM. Il est conçu pour la fiabilité et le déploiement en production, avec un focus sur le contrôle total des prompts, des outils, et des flux de communication.

Architecture et concepts

Agents à rôles personnalisables

Chaque agent dans Agency Swarm est défini avec un rôle clair dans l’organisation. Vous spécifiez un nom (CEO, Developer, Virtual Assistant), une description, des instructions détaillées (qui peuvent être un fichier Markdown complet), des outils, et des paramètres de modèle. Contrairement à des frameworks plus rigides, Agency Swarm donne un contrôle total sur les prompts et instructions de chaque agent. Pas de prompts pré-définis cachés qui entrent en conflit avec vos intentions.

Flux de communication directionnels

Le concept distinctif d’Agency Swarm est le « agency chart » : un organigramme qui définit les flux de communication entre agents. Ces flux sont directionnels : dans la définition [ceo, dev, va], le CEO peut initier une conversation avec le développeur, le développeur peut répondre et initier une conversation avec l’assistant virtuel, mais l’assistant ne peut pas initier de conversation avec le CEO. Cette directionnalité impose une structure hiérarchique qui reflète les organisations réelles et empêche les boucles de communication non contrôlées.

Les agents communiquent via un outil « send message » spécialement conçu, basé sur les descriptions des agents. Chaque agent sait à qui il peut s’adresser et pour quels types de tâches, ce qui réduit les appels inutiles et améliore l’efficacité de l’orchestration.

Outils (Tools)

Agency Swarm propose deux manières de créer des outils :

Le décorateur @function_tool (recommandé en v1.x) : approche moderne et concise pour transformer une fonction Python en outil utilisable par un agent. La description de la fonction sert de documentation pour le LLM.

L’extension de BaseTool : approche compatible avec la v0.x, utilisant Pydantic pour la validation des types et la documentation des champs. Plus verbeux mais offrant un contrôle plus fin sur la structure des entrées.

Agency Swarm supporte aussi la conversion automatique de schémas OpenAPI en outils via ToolFactory.from_openapi_schema(). Vous pointez vers un fichier JSON de schéma OpenAPI, et le framework génère automatiquement les outils correspondants. C’est particulièrement utile pour intégrer des APIs existantes sans écrire de code d’outil manuellement. Par exemple, si vous avez un schéma OpenAPI pour votre API CRM interne, Agency Swarm peut le transformer en un ensemble d’outils que vos agents utiliseront pour créer, lire, mettre à jour et supprimer des enregistrements clients.

Les agents peuvent aussi utiliser des fichiers (uploadés vers OpenAI) et des schémas OpenAPI stockés dans des dossiers dédiés. Le framework gère automatiquement l’ingestion des fichiers et la création de vector stores pour la recherche documentaire, avec réutilisation des répertoires existants pour éviter les doublons.

Orchestration multi-agent

L’orchestration dans Agency Swarm s’appuie sur le SDK OpenAI Agents comme fondation, enrichi d’une couche de gestion des flux. Les agents peuvent déléguer des tâches, recevoir des résultats, et itérer collaborativement. Le système de handoffs (transferts entre agents) injecte un message système de rappel à chaque transfert pour maintenir le contexte et la cohérence. Ce mécanisme de rappel est automatique : quand un agent transfère le contrôle à un autre, le système injecte les informations nécessaires pour que l’agent récepteur comprenne le contexte de la demande sans avoir à relire l’intégralité de l’historique.

Agency Swarm gère aussi la terminaison de conversations de manière intelligente : les agents peuvent décider quand une tâche est complète et retourner le contrôle à l’agent appelant ou à l’utilisateur final. Le routing entre agents avec des noms similaires ou répétitifs est corrigé pour éviter les erreurs d’acheminement des messages.

Forces et faiblesses

Nouveautés de la v1.x

La version 1.x représente une refonte majeure d’Agency Swarm, migrant la base du framework vers le SDK OpenAI Agents et l’API Responses :

Streaming cancellable : quand vous streamez une réponse token par token, vous pouvez l’arrêter en cours de route (via un endpoint cancel en FastAPI, ou la touche ESC en terminal). Deux modes : « immediate » (arrêt instantané) ou « after_turn » (fin du tour en cours, puis arrêt). C’est utile pour économiser des tokens quand vous avez déjà la réponse.

Hot reload en développement : le terminal demo détecte automatiquement les changements dans vos fichiers .py et .md et redémarre. Comme le hot reload de FastAPI, mais pour votre agence d’agents. Cela accélère considérablement le cycle d’itération.

Suivi d’usage et de coûts : les réponses FastAPI et le terminal affichent un résumé de consommation avec le nombre de requêtes, la décomposition des tokens, et un coût estimé en USD. Le suivi est multi-agent : il inclut les tokens de l’agent principal et de tous les sous-agents appelés pendant l’exécution. Les prix réels des modèles sont utilisés, y compris pour les modèles via LiteLLM.

Historique fiabilisé : les messages conservent le timestamp d’émission, les appels d’outils orphelins (sans résultat correspondant) sont nettoyés automatiquement, et les IDs placeholder de LiteLLM sont normalisés pour éviter les erreurs de replay.

Support multi-modèle via LiteLLM : en plus d’OpenAI natif (GPT-5, GPT-4o), vous pouvez utiliser Anthropic (Claude), Google (Gemini), xAI (Grok), Azure OpenAI, et OpenRouter comme passerelle vers d’autres modèles. Chaque agent peut utiliser un modèle différent.

Déploiement

Agency Swarm fournit un endpoint FastAPI intégré pour déployer votre agence comme API REST. L’endpoint expose les métadonnées de l’agence (version du framework, agents configurés), un endpoint de chat pour interagir avec l’agence en mode streaming ou non-streaming, un endpoint de cancel pour arrêter des exécutions en cours, et le forwarding du user_context pour les applications multi-utilisateurs. Le tout avec support natif du streaming cancellable.

Le framework est aussi conçu pour être utilisé avec des outils de développement IA modernes. Un fichier .cursorrules à la racine du repo permet une intégration directe avec Cursor, Claude Code, ou d’autres agents de coding. Un guide dédié pour Cursor IDE est disponible dans la documentation. Vous pouvez prototyper des agences entières en décrivant la structure organisationnelle en langage naturel à votre IDE.

Le template Agency Starter est le point de départ recommandé pour tout nouveau projet : il fournit une structure de projet complète avec agents, outils, et configuration prêts à personnaliser. Des exemples exécutables dans le dossier ./examples couvrent différents patterns que vous pouvez adapter à vos besoins.

Pour les environnements IPython/Jupyter, un patch nest_asyncio est automatiquement appliqué pour simplifier l’exécution de fonctions asynchrones. Pour le déploiement en production, la combinaison FastAPI + un serveur ASGI (uvicorn, gunicorn) fournit une base solide et scalable.

Cas d’usage

Agences de développement IA : Un CEO reçoit les demandes client, les transmet à un architecte qui conçoit la solution, un développeur qui code, et un QA qui teste. Chaque agent a ses outils spécialisés et communique via l’organigramme défini. Le flux directionnel garantit que le CEO ne reçoit pas de requêtes techniques du QA, mais que le QA peut signaler des bugs au développeur.

Support client multi-niveaux : Un agent de premier niveau qualifie les demandes via un outil de classification, un agent technique résout les problèmes complexes avec accès aux bases de connaissances et aux systèmes internes (via OpenAPI), un agent d’escalade redirige vers un humain si nécessaire. Le suivi de coûts intégré permet de mesurer le coût par ticket et d’optimiser l’allocation des modèles par niveau.

Automatisation marketing : Un agent stratège planifie les campagnes, un agent rédacteur produit le contenu en utilisant des templates, un agent analytique mesure les KPIs et génère des rapports. La communication directionnelle assure que le stratège dirige le flux de travail.

Prototypage rapide avec vibe coding : Grâce à l’intégration Cursor/Claude Code via le fichier .cursorrules, vous pouvez prototyper des agences multi-agents en conversant avec votre IDE. Le template starter accélère encore la mise en place. Vous décrivez l’agence que vous voulez, l’IA génère la structure, et vous itérez en quelques minutes.

Recherche et analyse : Une agence composée d’un agent chercheur (web scraping, accès API), d’un agent analyste (traitement de données, statistiques), et d’un agent rapporteur (rédaction, visualisation) automatise des workflows de veille concurrentielle, d’analyse de marché, ou de due diligence.

Agency Swarm vs. alternatives

Agency Swarm se distingue par sa proximité avec le SDK OpenAI Agents (c’est une extension, pas un remplacement) et sa métaphore organisationnelle avec flux de communication directionnels. CrewAI est plus mature et mieux outillé pour la production enterprise (SOC2, SSO). LangGraph est plus flexible avec son approche graphe d’état. Agency Swarm est le meilleur choix si vous êtes déjà investi dans l’écosystème OpenAI et que vous voulez construire des agences multi-agents avec une structure organisationnelle claire.

Cas d’usage

Agences de développement IA : Un CEO reçoit les demandes client, les transmet à un architecte qui conçoit la solution, un développeur qui code, et un QA qui teste. Chaque agent a ses outils spécialisés et communique via l’organigramme défini.

Support client multi-niveaux : Un agent de premier niveau qualifie les demandes, un agent technique résout les problèmes complexes, un agent escalade vers un humain si nécessaire. Les flux directionnels garantissent que chaque demande suit le bon chemin.

Automatisation marketing : Un agent stratège planifie les campagnes, un agent rédacteur produit le contenu, un agent analytique mesure les performances. Chacun utilise des outils spécialisés (APIs marketing, bases de données, outils d’analyse).

Prototypage rapide avec vibe coding : Grâce à l’intégration Cursor/Claude Code via le fichier .cursorrules, vous pouvez prototyper des agences multi-agents en conversant avec votre IDE. Le template starter accélère encore la mise en place.

Prise en main

Puis créez votre première agence en définissant des agents, des outils, et un agency chart. Le template Agency Starter est recommandé pour démarrer avec une structure de projet complète. La documentation sur agency-swarm.ai fournit des guides pas à pas, des exemples, et des tutoriels vidéo pour chaque fonctionnalité.

Des consultations avec le créateur (Arsenii Shatokhin) sont disponibles via vrsen.ai pour les projets d’agences personnalisées ou les besoins spécifiques.

Verdict

Agency Swarm est un framework bien conçu pour les équipes qui pensent en structures organisationnelles et veulent construire des systèmes multi-agents calqués sur des organigrammes d’entreprise. Sa proximité avec le SDK OpenAI Agents (extension directe, pas de remplacement), le support multi-modèle via LiteLLM, le suivi de coûts natif, et l’endpoint FastAPI intégré en font un outil pratique et orienté production.

Comparé à CrewAI (plus mature, plus d’adopteurs enterprise, standalone) ou LangGraph (plus flexible, graphes d’état), Agency Swarm reste un framework de niche. Sa force est la métaphore organisationnelle avec flux directionnels, qui rend la conception d’agences multi-agents intuitive pour les non-experts en systèmes distribués. Sa faiblesse est la dépendance au SDK OpenAI Agents comme fondation, ce qui le lie à l’écosystème OpenAI (même si LiteLLM élargit le support modèles).

Notre recommandation : utilisez Agency Swarm si vous êtes dans l’écosystème OpenAI, que vous aimez la métaphore organisationnelle, et que vous voulez un contrôle total sur les prompts et les flux de communication. Pour un framework plus généraliste et mieux supporté, regardez CrewAI ou LangGraph.