Multi-agent system tutorial : de zéro à la prod

Introduction

Ce multi-agent system tutorial construit une veille marché avec trois responsabilités : collecte, analyse et revue. Le but n’est pas d’empiler des personnages, mais de rendre chaque frontière testable et de limiter les droits. OpenClaw servira de Gateway self-hosted, de routeur de sessions et de scheduler ; il ne sera pas présenté comme un framework Python. Le code métier peut rester dans des tools ou services séparés. Ce montage est pertinent pour une équipe qui pilote le flux depuis Slack ou Telegram et conserve ses données. Pour une chaîne courte, déterministe et sans différence de permissions, restez sur une approche plus simple.

Résumé rapide

1. Définir trois contrats de sortie avant de créer les agents.
2. Configurer des workspaces et états distincts dans ~/.openclaw/openclaw.json.
3. Formaliser les procédures dans des fichiers SKILL.md.
4. Restreindre tools, sessions et handoffs entre agents.
5. Déclencher la veille avec openclaw automations et vérifier son historique.
6. Tester timeout, données invalides, reprise et double exécution avant la production.

Modèle du système de veille

Le flux produit un rapport hebdomadaire à partir de sources autorisées. Trois rôles suffisent :

• research collecte les sources et écrit un artefact JSON cité ;
• analyst classe les signaux selon un barème stable et explique chaque score ;
• main relit, demande une approbation et livre le rapport au canal.

Les agents ne partagent pas une mémoire Python en processus. Ils échangent des artefacts durables avec un traceId, un schéma et un statut. Cette séparation autorise le replay de l’analyse sans rescanner le Web et empêche un transcript volumineux de devenir une base de données implicite.

Dans OpenClaw, un agent représente un périmètre durable : workspace, instructions, profils d’authentification, registre de modèles et sessions. Plusieurs agents tournent dans un même Gateway, puis des bindings routent les messages entrants. Ce modèle convient à des personas d’un même propriétaire ou d’une équipe de confiance. Il ne constitue pas une isolation multi-tenant hostile.

Le code Python reste possible pour une fonction métier externe, par exemple un parseur ou un calcul de score, mais OpenClaw ne fournit pas de classe Python Agent à importer. Le Gateway et la CLI actuels sont Node/TypeScript. Si votre besoin principal est un graphe applicatif Python, consultez plutôt les architectures multi-agents et choisissez un moteur adapté.

Implémentation pas à pas avec OpenClaw

1. Installer et vérifier le Gateway

Installez OpenClaw par la voie officielle, puis lancez l’onboarding :

curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon
openclaw doctor
openclaw gateway status --require-rpc

OpenClaw recommande Node 26. Sa configuration canonique vit dans ~/.openclaw/openclaw.json. N’utilisez ni pip ni un fichier YAML fictif pour l’installer ou le configurer.

2. Créer les workspaces

mkdir -p ~/.openclaw/workspace-main
mkdir -p ~/.openclaw/workspace-research
mkdir -p ~/.openclaw/workspace-analyst
mkdir -p ~/.openclaw/workspace-research/artifacts
mkdir -p ~/.openclaw/workspace-analyst/artifacts

Chaque agent doit aussi avoir un agentDir propre. Ne copiez pas un répertoire d’état entre agents : cela mélange authentification et sessions.

3. Déclarer les agents et les frontières

La configuration suivante illustre la structure actuelle. Le schéma évolue ; contrôlez chaque champ avec la documentation ou la Control UI avant de l’appliquer :

{
  agents: {
    entries: [
      { id: "main", workspace: "~/.openclaw/workspace-main" },
      { id: "research", workspace: "~/.openclaw/workspace-research" },
      { id: "analyst", workspace: "~/.openclaw/workspace-analyst" },
    ],
  },
  tools: {
    sessions: { visibility: "agent" },
    agentToAgent: {
      enabled: true,
      allow: ["main:research", "main:analyst"],
    },
  },
}

Ici, main coordonne ; les spécialistes ne se contactent pas librement. En production, complétez avec des politiques de tools par agent et une sandbox pour toute lecture de contenu non fiable. Un workspace est un cwd, pas une barrière de sécurité.

Après édition :

openclaw doctor
openclaw gateway restart
openclaw agents list --bindings
openclaw security audit --deep

4. Écrire les contrats d’artefacts

Le collecteur produit research.json :

{
  "schemaVersion": 1,
  "traceId": "market-watch-2026-W36",
  "status": "complete",
  "sources": [
    {
      "url": "https://example.com/news",
      "title": "Annonce vérifiée",
      "publishedAt": "2026-09-04",
      "excerpt": "Fait utile au classement"
    }
  ],
  "errors": []
}

L’analyste ne modifie jamais ce fichier. Il écrit analysis.json avec les références de sources, les scores et les incertitudes. main génère report.md. Un artefact incomplet reste exploitable seulement si son champ status et ses erreurs sont visibles.

5. Transformer les procédures en skills

Créez un skill propre au workspace de recherche :

mkdir -p ~/.openclaw/workspace-research/skills/market-research

Puis ajoutez ~/.openclaw/workspace-research/skills/market-research/SKILL.md :

 ---
 name: market-research
 description: Collecte une veille marché citée dans un artefact JSON.
 ---

 # Veille marché

1. Lire la liste de domaines autorisés dans `sources.txt`.
2. Collecter titre, URL, date et extrait ; ne jamais inventer une source.
3. Écrire `artifacts/<traceId>-research.json` selon le schéma fourni.
4. Marquer `partial` si une source échoue et renseigner `errors`.
5. Ne publier ni envoyer aucun message externe.

Créez de la même manière market-analysis et report-review. Les skills enseignent une procédure ; ils n’accordent pas de tool supplémentaire. Vérifiez leur chargement :

openclaw skills list

OpenClaw charge en priorité les skills du workspace de l’agent, puis les autres racines selon sa hiérarchie documentée.

6. Tester chaque rôle isolément

Lancez un tour via le Gateway :

openclaw agent --agent research \
  --message "Utilise market-research avec traceId market-watch-test." \
  --json

Contrôlez le fichier produit avec un validateur JSON indépendant. Répétez pour analyst en lui fournissant une fixture, pas un scan réel. Le test doit échouer si schemaVersion, traceId, URL ou date manque.

Testez aussi une source inaccessible. Le résultat attendu est status: "partial", une erreur explicite et aucun contenu inventé. Cette étape sépare une défaillance de tool d’une mauvaise décision de l’agent.

7. Orchestrer sans boucle ouverte

main reçoit un message qui impose le nombre maximal de handoffs et les conditions terminales. Il appelle d’abord research, valide l’artefact, puis appelle analyst. Si une étape échoue deux fois, il arrête et demande une intervention humaine. La revue finale n’envoie rien avant approbation.

Pour une exécution planifiée, utilisez le scheduler intégré au Gateway :

openclaw automations add \
  --name "Veille marché hebdomadaire" \
  --cron "0 8 * * 1" \
  --tz "Europe/Paris" \
  --session isolated \
  --message "Lance la veille market-watch, valide chaque artefact et prépare un brouillon sans publication."

Les automations persistent avec leur historique dans l’état SQLite. Le Gateway doit tourner pour que le schedule se déclenche. openclaw cron existe encore comme alias, mais openclaw automations est la surface actuelle.

8. Valider le passage en production

Exécutez cette checklist :

• chaque agent possède son workspace et son état ;
• les schemas d’artefact sont validés hors du modèle ;
• les tools sont réduits au minimum et les sandboxes testées ;
• seuls les handoffs nécessaires sont autorisés ;
• retries, timeout et nombre de délégations sont bornés ;
• une approbation protège toute livraison externe ;
• l’automation apparaît dans la liste et son historique est consultable ;
• sauvegarde et restauration de ~/.openclaw ont été exercées.

Contrôles finaux :

openclaw gateway status --require-rpc
openclaw health --json
openclaw channels status --probe
openclaw automations list
openclaw security audit --deep

Pour approfondir l’exploitation, lisez OpenClaw en production.

Exemple concret

Le lundi à 8 h, l’automation crée une tâche isolée avec traceId=market-watch-2026-W36. main demande à research d’appliquer le skill. Trois sources répondent, une expire ; l’artefact contient trois entrées et une erreur, avec status: "partial".

Le validateur accepte le schéma mais signale l’incomplétude. La politique autorise l’analyse si au moins trois sources distinctes restent disponibles. analyst reçoit le chemin de l’artefact et le barème, puis écrit cinq signaux avec source, score et justification. Il n’a pas accès au canal Slack.

main synthétise le rapport et le poste dans une session de revue, sans livraison externe. Un humain approuve ; la réponse finale est alors envoyée au canal prévu. L’opérateur vérifie l’exécution :

openclaw automations runs --id <job-id>
openclaw logs --follow

Pour tester l’idempotence, il relance la même semaine. Les skills détectent les artefacts portant le même traceId et ne créent pas un second rapport. Pour tester la reprise, il fournit un analysis.json invalide : main refuse la livraison et demande une correction. L’acceptation dépend ainsi d’artefacts observables, pas d’une impression de qualité.

Bonnes pratiques

Gardez les effets externes dans la dernière étape. La collecte et l’analyse peuvent être rejouées ; un email ou une publication ne le peut pas toujours. Utilisez des clés d’idempotence et archivez la preuve de livraison.

Ne transmettez pas tout le transcript d’un agent au suivant. Passez un artefact court, sa version et les sources. La réduction de contexte améliore coûts, confidentialité et reproductibilité.

Distinguez clairement agent, skill et tool. L’agent porte l’identité et l’état ; le skill décrit une procédure ; le tool réalise une action. Ajouter une nouvelle procédure ne justifie pas forcément un nouvel agent.

Surveillez par étape : taux de schémas valides, latence, retries, coût modèle et taux d’approbation humaine. Un taux global masque le maillon faible. Enfin, considérez un Gateway comme une seule frontière de confiance. Pour des clients adversariaux, déployez des Gateway séparés.

Questions fréquentes

Comment créer un système multi-agents avec OpenClaw ?

Déclarez plusieurs agents avec des workspaces et états distincts, routez les canaux avec des bindings, formalisez les procédures en SKILL.md, puis limitez sessions, tools et handoffs. Testez chaque agent avec openclaw agent --agent <id> --message ... avant de créer une automation récurrente.

Peut-on installer OpenClaw avec pip ?

Non. OpenClaw est un produit Node/TypeScript installé par son script officiel ou par npm, puis piloté avec la CLI openclaw. Il ne fournit pas de package Python contenant Agent, VectorMemory ou invoke_agent. Python peut servir à vos tools métier externes, sans être le runtime OpenClaw.

Quelle différence entre un skill et un agent OpenClaw ?

Un agent possède workspace, état, authentification et sessions. Un skill est un dossier contenant un SKILL.md qui explique quand et comment utiliser des tools. Le skill n’accorde pas de permission et ne crée pas un processus autonome. Il est chargé selon le workspace et les règles de priorité.

Comment déboguer une orchestration multi-agent ?

Attribuez un traceId commun, conservez chaque artefact, validez les schémas hors modèle et consultez les logs ainsi que l’historique d’automation. Rejouez une seule étape avec une fixture. Vérifiez d’abord le Gateway, puis le handoff, le tool, le contrat de sortie et enfin la livraison.

Quand rester sur un seul agent ?

Restez mono-agent si les étapes partagent les mêmes outils, données et droits, ou si le flux est court et déterministe. Des skills et fonctions validées suffisent souvent. Ajoutez un agent lorsque l’isolation, la propriété d’une décision ou la validation indépendante apporte un bénéfice mesurable.

Articles liés

Un système multi-agents fiable se construit autour de contrats et de permissions, pas autour de classes inventées. OpenClaw fournit le Gateway, les agents isolés, les skills, les sessions et les automations ; gardez le code métier et les transactions dans les outils adaptés. Commencez avec deux rôles, mesurez les échecs, puis ajoutez une frontière seulement si elle réduit le risque.

• Architectures multi-agents : patterns et design
• Comprendre un système multi-agents
• Structurer des workflows agentiques
• Guide complet OpenClaw
• Mettre OpenClaw en production
• Choisir ses outils pour agents IA