AgentSwarm — Guide Utilisateur Complet

Projet multi-agents rédigé par des agents CLI : OpenCode (chef d'orchestre), GitHub Copilot CLI, Claude Code, Cursor — en collaboration via fichier COLLAB.md.

⚠️ Projet en cours de développement — fonctionnel et livable, mais pas encore totalement au point. Contributions et retours bienvenus.

Qu'est-ce qu'AgentSwarm ?

AgentSwarm est un panel de contrôle qui fait travailler plusieurs agents IA en parallèle sur votre ordinateur. Chaque agent a son propre bureau virtuel et peut :

Naviguer sur le web (rechercher, remplir des formulaires, télécharger via Playwright + Chromium)
Utiliser des applications de bureau (LibreOffice, terminal, gestionnaire de fichiers via PyAutoGUI)
Voir son écran et interagir (vision LLM + clavier/souris)

Vous décrivez une tâche en français, vous choisissez combien d'agents (1 à 12) et leurs modèles, et vous les regardez bosser en direct depuis votre navigateur.

Prérequis

Élément	Requis
OS	Windows, macOS ou Linux (avec Docker Desktop)
Docker Desktop	Installé et démarré
RAM	16 Go recommandé (8 Go minimum pour 2-3 agents)
Navigateur	N'importe lequel (Firefox, Chrome, Edge...)
Connexion internet	Pour télécharger les images Docker et les APIs cloud

Pas besoin de : Python, Node.js, Redis, ou quoi que ce soit d'autre installé sur votre machine. Seul Docker est requis.

Installation (2 minutes, 4 commandes)

Étape 1 — Cloner le projet

cd ~
git clone <url-du-repo> agentswarm
cd agentswarm

Étape 2 — Créer le fichier d'environnement

cp .env.example .env
# Éditer .env pour coller au moins une clé API (GROQ_API_KEY, GOOGLE_API_KEY...)
nano .env

Étape 3 — Lancer (télécharge + build + démarre automatiquement)

docker compose up --build -d

Cette commande unique va :

Télécharger redis:7-alpine (~30 Mo)
Télécharger ghcr.io/berriai/litellm:main-latest (~400 Mo)
Builder agentswarm-orchestrator (code Python)
Builder agentswarm-dashboard (React + nginx)
Démarrer les 4 conteneurs

La première installation prend ~2 min selon votre connexion.

Étape 4 — Ouvrir le dashboard

http://localhost:3000

C'est prêt. Vous pouvez lancer des tâches immédiatement.

Note : les images agents (agentswarm-browser-agent ~3.4 Go, agentswarm-desktop-agent ~1 Go) sont buildées automatiquement au premier run d'une tâche par l'orchestrateur, ou manuellement avec :
docker compose build browser-agent desktop-agent

Usage quotidien

cd ~/agentswarm
docker compose up -d          # Démarrer tous les services (~30s)
# ou
docker compose up -d --build  # Reconstruire les images puis démarrer

Puis ouvrir http://localhost:3000.

Pour arrêter :

docker compose down

Premier lancement — Configurer un fournisseur IA

Au premier lancement, aucun fournisseur n'est actif. Ajoutez au moins une clé API dans .env puis :

docker compose restart litellm-proxy

Providers gratuits recommandés :

Provider	Clé API	Modèles vision (✅) / texte (❌)
Groq	`GROQ_API_KEY`	`groq/llama-4-scout` ✅, `groq/llama-3.3-70b-versatile` ❌
Google Gemini	`GOOGLE_API_KEY`	`gemini-2.0-flash` ✅, `gemini-2.5-pro` ✅

Note importante : les agents desktop (GUI, PyAutoGUI) ont besoin d'un modèle vision pour analyser les screenshots. Les agents browser (Playwright) peuvent utiliser des modèles texte uniquement.

Modèles disponibles

Nom API	Provider	Vision	Usage
`groq/llama-4-scout`	Groq	✅	Desktop (recommandé)
`groq/qwen3-32b`	Groq	❌	Browser / Texte
`groq/qwen3.6-27b`	Groq	❌	Browser / Texte
`groq/llama-3.3-70b-versatile`	Groq	❌	Browser / Texte
`gemini-2.0-flash`	Gemini	✅	Desktop (rapide)
`gemini-2.5-flash`	Gemini	✅	Desktop (équilibré)
`gemini-2.5-pro`	Gemini	✅	Desktop (capable)

Alias équivalents : agent-groq-llama-4-scout = groq/llama-4-scout, agent-gemini-2.0-flash = gemini-2.0-flash, etc.

Lancer une tâche

Aller sur http://localhost:3000 (page "Nouvelle tâche")
Décrire la tâche en langage naturel
Choisir le nombre d'agents (1 à 12)
Pour chaque agent, choisir :
- Le type : Navigateur (web) ou Desktop (applications locales)
- Le modèle IA (vision pour desktop, texte accepté pour browser)
Vérifier l'estimation RAM affichée (vert = OK, rouge = risque)
Optionnel : définir un budget max en dollars
Cliquer Lancer

Exemple multi-agents

POST /tasks
{
  "description": "Cherche le prix de l'action NVIDIA sur Google, puis ouvre LibreOffice Calc et crée un tableau",
  "agents": [
    {"executor_type": "browser", "model_name": "groq/llama-3.3-70b-versatile"},
    {"executor_type": "desktop", "model_name": "groq/llama-4-scout"}
  ]
}

Les deux agents tournent en parallèle via asyncio.gather. Chacun reçoit une sous-tâche découpée automatiquement.

Suivre l'exécution

La page Suivi (http://localhost:3000/monitor) affiche :

Une carte par agent avec :
- Un flux vidéo en direct de son bureau virtuel (via noVNC, port 6080+)
- Deux curseurs visibles : le vrai curseur du bureau VNC + un overlay SVG React coloré par agent
- Le modèle utilisé et le coût en temps réel
- L'action en cours ("Dismiss the popup...", "Navigating to...")
- Le statut (en cours, réussi, échoué, en retry)
Couleurs des agents :
- Rouge, Bleu, Vert, Jaune, Violet, Orange
- Au-delà de 6 : Rouge-2, Bleu-2, etc.

Curseur overlay : synchronisé via Redis pub/sub → WebSocket → dashboard. Transition CSS 0.12s ease-out. Position relative (pourcentage du 1280x720).

Communication entre agents

Les agents communiquent via Redis :

Mécanisme	Usage
Pub/sub (`agent_events`)	Logs, events curseur, status changes → dashboard temps réel
Hash state (`agent:{color}:state`)	Status, action courante, position souris
Shared data (`task:{id}:shared`)	Données partagées entre agents (lecture/écriture via Blackboard)

⚠️ Limitation actuelle : les agents sont lancés en parallèle, sans chaînage des dépendances. Chaque agent travaille sur sa sous-tâche de manière indépendante. Le champ dependencies[] n'est pas encore utilisé par l'orchestrateur.

Comprendre les résultats

Après exécution, la page Résultat montre :

Le statut global : Succès / Succès partiel / Échoué
Le détail par sous-tâche (chaque agent)
Le coût total
Les fichiers produits

Statuts possibles

Statut	Signification
`success`	Toutes les sous-tâches ont réussi
`partial_success`	Certaines ont réussi, d'autres non
`failed`	Tout a échoué après les retries

Gestion des erreurs

Le système gère les erreurs automatiquement :

Timeout (agent bloqué > 5 min) → retry automatique (max 3 fois)
Erreur API (429, 404, 400) → retry avec délai croissant (2s, 4s, 8s)
Crash de l'agent → nouveau conteneur lancé
Budget dépassé → arrêt immédiat, résultats partiels conservés
Modèle incorrect → 404 de LiteLLM, retry avec le modèle suivant

Combien d'agents puis-je lancer ?

Configuration	Agents max (sur 16 Go RAM)
Tous en API cloud (Groq, Gemini...)	8-12 agents
Mix cloud + Ollama local	4-6 agents
Tout en Ollama local	2-3 agents

Le dashboard affiche une estimation en temps réel avant de lancer.

Ajouter un nouveau fournisseur IA

Via `.env` + `litellm_config.yaml`

Ajouter la clé dans .env :

GROQ_API_KEY=gsk_xxx
GOOGLE_API_KEY=AIza...

Ajouter une entrée dans litellm/litellm_config.yaml :
```
- litellm_params:
    api_key: os.environ/GROQ_API_KEY
    model: groq/meta-llama/llama-4-scout-17b-16e-instruct
  model_name: groq/llama-4-scout
```
Attention au format : le model doit inclure le préfixe exact attendu par l'API du provider. Ex: Groq nécessite groq/qwen/qwen3-32b (le modèle réel est qwen/qwen3-32b), pas groq/qwen3-32b.
Redémarrer LiteLLM : docker compose restart litellm-proxy
Vérifier les modèles : curl http://localhost:4000/models

Providers supportés (21)

Provider	Préfixe LiteLLM	Inscription
Ollama (local)	`ollama/`	ollama.ai
Anthropic	`anthropic/`	console.anthropic.com
OpenAI	`openai/`	platform.openai.com
Google Gemini	`gemini/`	aistudio.google.com
Amazon Bedrock	`bedrock/`	aws.amazon.com
Microsoft Azure	`azure/`	portal.azure.com
Mistral AI	`mistral/`	console.mistral.ai
Groq	`groq/`	console.groq.com
Together AI	`together_ai/`	api.together.xyz
DeepSeek	`deepseek/`	platform.deepseek.com
NVIDIA NIM	`nvidia_nim/`	build.nvidia.com
Fireworks AI	`fireworks_ai/`	fireworks.ai
Perplexity	`perplexity/`	perplexity.ai
Cohere	`cohere/`	dashboard.cohere.com
OpenRouter	`openrouter/`	openrouter.ai
Cerebras	`cerebras/`	cloud.cerebras.ai
SambaNova	`sambanova/`	cloud.sambanova.ai
AI21 Labs	`ai21/`	studio.ai21.com
Replicate	`replicate/`	replicate.com
Anyscale	`anyscale/`	anyscale.com
Hugging Face	`huggingface/`	huggingface.co

Commandes utiles

# Démarrer le système
docker compose up -d

# Arrêter le système
docker compose down

# Voir les logs en direct
docker compose logs -f

# Logs d'un service spécifique
docker compose logs -f orchestrator

# Redémarrer un service
docker compose restart litellm-proxy

# Tout reconstruire (après mise à jour)
docker compose up --build -d

# Vérifier l'état
docker compose ps

# Nettoyer les images inutilisées
docker system prune

# Voir les modèles LiteLLM disponibles
curl http://localhost:4000/models | jq

Structure des fichiers produits

volumes/
├── output/
│   ├── result_848e6939.json
│   └── ...
└── db/
    └── agentswarm.sqlite      # Historique des tâches

Nettoyage

Après plusieurs tâches, des conteneurs d'agents arrêtés et des volumes de sortie peuvent s'accumuler.

Nettoyage automatique

bash cleanup.sh

Supprime :

Tous les conteneurs agents arrêtés (agent-*)
Les volumes de sortie orphelins (agentswarm-output-*)
Les conteneurs non-agent arrêtés depuis >24h
Les fichiers dans volumes/output/

Manuellement

# Lister les conteneurs agents
docker ps -a --filter name=agent-

# Supprimer un agent spécifique
docker rm -f agent-rouge-abc12345

# Supprimer tous les agents arrêtés
docker container prune -f --filter "until=1h"

# Lister les volumes
docker volume ls --filter name=agentswarm-output

# Supprimer un volume
docker volume rm agentswarm-output-rouge

Architecture

Vous (navigateur)
    │
    ▼
Dashboard (localhost:3000) ─── React + Vite
    │  └─ WebSocket (events temps réel)
    ▼
Orchestrateur (localhost:8000) ─── FastAPI (cerveau)
    │  ├─ TaskSplitter → découpe la tâche
    │  ├─ DockerManager → lance/monitore les conteneurs
    │  ├─ RetryHandler → gère les échecs
    │  └─ Blackboard → Redis pub/sub + state
    │
    ▼
LiteLLM Proxy (localhost:4000) ─── traducteur IA
    │  └─ Route vers Groq, Gemini, OpenAI, etc.
    │
    ▼
Redis ─── communication inter-agents + pub/sub events
    │
    ├──▶ Agent Rouge (browser: Playwright + Chromium)
    ├──▶ Agent Bleu  (desktop: PyAutoGUI + mss + xdotool)
    └──▶ Agent Vert  (browser ou desktop)
          │
          └─ Chaque agent : Xvfb + fluxbox + x11vnc + noVNC

Stack technique

Service	Technologie	Rôle
Dashboard	React + Vite + Tailwind	Interface utilisateur
Orchestrateur	FastAPI (Python)	API REST, coordination
Proxy IA	LiteLLM → 21 providers	Proxy unifié vers Groq, Gemini, OpenAI, etc.
Cache / Comms	Redis 7	Pub/sub, state, shared data
Agent Browser	Playwright + browser_use + LangChain	Navigation web automatisée
Agent Desktop	PyAutoGUI + python-mss + xdotool	GUI automation Linux
Bureau virtuel	Xvfb + x11vnc + noVNC	Streaming VNC dans le navigateur
Conteneurisation	Docker	Isolation des agents

Dépannage

Le dashboard ne se charge pas

docker compose ps   # Vérifier que tous les conteneurs sont "Up"

"Aucun fournisseur configuré"

Ajoutez une clé API dans .env et redémarrez LiteLLM.

Une tâche échoue immédiatement

docker compose logs orchestrator
docker compose logs litellm-proxy | grep -E "error|NotFound|429"

Vérifiez que le model_name est correct dans la requête.

L'agent desktop échoue avec 400 Bad Request

Le modèle utilisé ne supporte pas la vision. Utilisez groq/llama-4-scout ou gemini-2.0-flash.

Les agents sont très lents

Utilisez une API cloud (Groq, Gemini) au lieu d'Ollama local
Vérifiez le rate limiting (429) dans les logs LiteLLM

Port déjà utilisé

lsof -i :3000   # Dashboard
lsof -i :8000   # Orchestrateur
lsof -i :6379   # Redis
lsof -i :6080   # Agent VNC (incrémente)

Sécurité

Tout est local : rien n'est exposé sur internet
Clés API : stockées dans .env (jamais commitées)
Agents isolés : conteneurs Docker avec utilisateur non-root
Ports VNC : bindés sur 127.0.0.1 uniquement
Budget : configurable pour éviter les surprises sur les APIs payantes
Réseau : réseau Docker interne isolé entre services

FAQ

Q : Est-ce que ça coûte de l'argent ? R : Infrastructure 100% gratuite (Docker). Seuls les appels APIs cloud payants coûtent (quelques centimes/tâche). Groq et Gemini offrent des niveaux gratuits.

Q : Puis-je utiliser plusieurs providers en même temps ? R : Oui. Chaque agent peut avoir son propre modèle : Agent Rouge sur Gemini, Agent Bleu sur Groq, etc.

Q : Mes données sont-elles envoyées quelque part ? R : Uniquement aux APIs que vous configurez. Rien n'est envoyé à un tiers.

Q : Puis-je voir ce que font les agents en temps réel ? R : Oui, flux vidéo VNC + overlay curseur React + logs en direct.

Q : Que se passe-t-il si un agent plante ? R : Retry automatique jusqu'à 3 fois. Résultats partiels conservés.

Q : Les données persistent entre les redémarrages ? R : Oui, dans les volumes Docker persistants.

Q : Puis-je chaîner les résultats d'un agent vers un autre ? R : Pas encore — les agents tournent en parallèle. Le champ dependencies[] est présent dans le splitter mais pas implémenté dans l'orchestrateur.

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
agents		agents
dashboard		dashboard
litellm		litellm
orchestrator		orchestrator
volumes		volumes
.env.example		.env.example
.gitignore		.gitignore
COLLAB.md		COLLAB.md
README.md		README.md
cleanup.sh		cleanup.sh
docker-compose.yml		docker-compose.yml

Folders and files

Latest commit

History

Repository files navigation

AgentSwarm — Guide Utilisateur Complet

Qu'est-ce qu'AgentSwarm ?

Prérequis

Installation (2 minutes, 4 commandes)

Étape 1 — Cloner le projet

Étape 2 — Créer le fichier d'environnement

Étape 3 — Lancer (télécharge + build + démarre automatiquement)

Étape 4 — Ouvrir le dashboard

Usage quotidien

Premier lancement — Configurer un fournisseur IA

Modèles disponibles

Lancer une tâche

Exemple multi-agents

Suivre l'exécution

Communication entre agents

Comprendre les résultats

Statuts possibles

Gestion des erreurs

Combien d'agents puis-je lancer ?

Ajouter un nouveau fournisseur IA

Via .env + litellm_config.yaml

Providers supportés (21)

Commandes utiles

Structure des fichiers produits

Nettoyage

Nettoyage automatique

Manuellement

Architecture

Stack technique

Dépannage

Le dashboard ne se charge pas

"Aucun fournisseur configuré"

Une tâche échoue immédiatement

L'agent desktop échoue avec 400 Bad Request

Les agents sont très lents

Port déjà utilisé

Sécurité

FAQ

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Via `.env` + `litellm_config.yaml`

Packages