MagiClaw pour débuter : l’équipe d’agents de recherche IA dans Feishu, pour une collaboration qui se fait naturellement

15 minutes pour la configuration｜Expérience native Feishu｜Orchestration d’agents de recherche｜Extension instantanée sur base EvoMaster

---

Présentation du projet

MagiClaw est une plateforme d’agents IA qui s’exécute dans Feishu. Son idée centrale est la suivante : au lieu de créer un nouvel outil indépendant que vous devez ouvrir spécifiquement, elle intègre directement les agents IA dans Feishu — l’outil que vous utilisez déjà au quotidien. Dans les discussions de groupe ou en messages privés, il suffit de décrire le besoin : l’équipe d’agents se met alors en marche.

Derrière MagiClaw, on trouve le framework EvoMaster : une infrastructure légère de base pour les agents. Elle gère l’appel d’outils, les Skills (compétences), la gestion de la mémoire et le routage des conversations. Cela signifie que vous pouvez vous concentrer sur « ce que l’agent doit faire », plutôt que de refaire sans cesse la construction de couche ingénierie. Le projet est open source, sous licence Apache 2.0. Le volume de code est réduit, ce qui facilite un développement itératif (et une reprise en main) en second temps.

---

Public cible

Cet article s’adresse aux développeurs suivants :

• Vous avez des bases en Python, vous connaissez Feishu ou des outils de collaboration type Lark, et vous souhaitez intégrer directement des capacités d’IA dans les communications quotidiennes de votre équipe
• Vous vous intéressez aux scénarios « IA pour la science » et cherchez un cadre d’agents de recherche extensible
• Vous utilisez déjà EvoMaster ou un framework d’agents similaire, et vous voulez étendre Feishu comme couche d’interaction côté front-end

Si vous cherchez un « kit complet » d’agents de recherche autonome, MagiClaw n’est pas la réponse — c’est l’intégration de l’écosystème EvoMaster dans Feishu, pour que les workflows de recherche se mettent naturellement à tourner dans l’outil de communication de votre équipe.

---

Dépendances clés et environnement

---

Arborescence complète du projet

MagiClaw/
├── evomaster/                    # Bibliothèque du framework principal
│   ├── agent/                   # Classe de base Agent et runtime
│   ├── core/                    # Appels d’outils principaux, ordonnancement des tâches
│   ├── interface/
│   │   └── feishu/             # Implémentation de l’interface Feishu (connexions longues, Webhook)
│   ├── memory/                  # Stockage de mémoire persistante
│   ├── skills/                  # Packs de compétences réutilisables
│   └── scheduler/               # Planificateur de multi-tâches
├── playground/
│   ├── magiclaw/               # Agent de conversation Feishu par défaut
│   ├── agent_builder/           # Méta-agent : conception / génération de nouveaux agents
│   ├── coding_agent/            # Agent spécialisé : écriture de code
│   ├── report_writer_agent/     # Agent spécialisé : rédaction de rapports
│   └── web_search_agent/        # Agent spécialisé : recherche web
├── configs/
│   ├── feishu/                  # Identifiants de connexion du Bot Feishu
│   │   └── config.yaml
│   ├── magiclaw/               # Configuration LLM, outils, MCP, mémoire
│   │   └── config.yaml
│   └── agent_builder/           # Configuration pour deux agents : planification + construction
├── run.py                       # Point d’entrée CLI pour démarrage rapide
├── requirements.txt
└── pyproject.toml

---

Étapes d’installation, pas à pas

Étape 1 : cloner le code

git clone https://github.com/sjtu-sai-agents/MagiClaw.git
cd MagiClaw

Étape 2 : installer les dépendances

pip install -r requirements.txt

Ou avec uv (plus rapide) :

uv pip install -r requirements.txt

Étape 3 : créer une application Feishu

1. Ouvrez Feishu Open Platform et connectez-vous avec le compte de votre équipe
2. Cliquez sur Créer une application d’entreprise (self-built) et renseignez le nom ainsi que la description
3. Une fois dans l’application, dans le menu à gauche, choisissez Ajouter des capacités d’application, puis cochez Robot

Étape 4 : configurer les identifiants de l’application

Copiez le modèle de variables d’environnement :

cp .env.template .env

Dans .env, renseignez les identifiants fournis par Feishu Open Platform :

FEISHU_APP_ID=cli_xxxxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Étape 5 : importer le périmètre des permissions

Dans Feishu Open Platform, allez dans Gestion des permissions → Importation/exportation en lot des permissions, puis collez le JSON suivant :

{
  "scopes": {
    "tenant": [
      "im:resource",
      "docx:document",
      "docx:document:readonly",
      "drive:drive",
      "im:chat:readonly",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.group_msg",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:recall",
      "im:message:send_as_bot",
      "wiki:wiki:readonly"
    ],
    "user": [
      "drive:drive",
      "drive:drive.metadata:readonly",
      "drive:drive.search:readonly",
      "drive:drive:readonly",
      "drive:drive.version",
      "drive:drive.version:readonly"
    ]
  }
}

Étape 6 : configurer l’abonnement aux événements

Dans Événements et callbacks → Configuration des événements, choisissez Utiliser la connexion longue pour recevoir les événements, puis ajoutez les événements suivants :

Dans Configuration des callbacks, choisissez également la connexion longue et abonnez-vous à :

Étape 7 : configurer le LLM

Modifiez configs/magiclaw/config.yaml et renseignez vos identifiants LLM :

llm:
  provider: openai              # ou anthropic / custom
  model: gpt-4o
  api_key: sk-...               # depuis .env ou directement dans le fichier de configuration
  base_url: https://api.openai.com/v1  # optionnel : URL d’endpoint personnalisée

Étape 8 : publier l’application et démarrer

Dans Feishu Open Platform Gestion des versions et publication, créez une version puis publiez-la afin d’activer le Bot.

Ensuite, démarrez le robot :

python -m evomaster.interface.feishu --config configs/feishu/config.yaml

Une fois le démarrage réussi, envoyez un message au Bot dans Feishu : il répondra. Par défaut, il s’agit d’un agent de conversation général, avec capacité de contexte multi-tours et mémoire.

---

Architecture à double cœur d’Agent

La véritable puissance de MagiClaw vient de la collaboration entre deux Playground intégrés : magiclaw pour gérer les conversations du quotidien, et agent_builder pour vous aider à créer de nouveaux agents spécialisés.

magiclaw : orchestrateur de conversations Feishu

magiclaw est l’agent de conversation Feishu activé par défaut. Sa force principale est l’orchestration et la délégation.

Lorsque vous envoyez une requête complexe, magiclaw n’essaie pas de tout faire seul. Il identifie plutôt les capacités spécialisées nécessaires, puis délègue le travail en appelant les autres Playground déjà enregistrés :

Dans Feishu, vous demandez : « Aidez-moi à étudier les progrès récents de l’architecture RAG dans le secteur financier et rédigez un rapport »

→ magiclaw reçoit la demande
→ Détermine : étude de la littérature (web_search_agent) + rédaction du rapport (report_writer_agent)
→ Appelle séparément ces deux agents
→ Agrège les résultats et renvoie un message Feishu

Ce mécanisme de délégation permet à magiclaw de rester léger : il n’a pas besoin de savoir tout faire, il suffit de savoir quand appeler qui. Les capacités des agents spécialisés sont étendues via les Skills et les interfaces d’outils.

agent_builder : méta-agent

agent_builder est la partie la plus intéressante de MagiClaw : c’est lui-même un Agent, mais sa mission est de** concevoir et générer de nouveaux Agents**.

Vous lui décrivez le type de tâche que vous voulez faire, et il :

1. Analyse la demande et extrait les capacités fondamentales dont l’Agent a besoin
2. Génère le fichier de compétences de l’Agent (YAML frontmatter + description en Markdown)
3. Écrit dans le répertoire playground/ pour l’enregistrer dans MagiClaw
4. Le nouvel Agent est immédiatement disponible, et magiclaw peut ensuite le déléguer

Dans Feishu, vous demandez : « J’ai besoin d’un Agent spécialisé pour gérer la revue de code »

→ agent_builder analyse la demande
→ Génère `code_reviewer_agent.py` + le fichier de configuration associé
→ Enregistre dans le système
→ Répond : « code_reviewer créé ; magiclaw peut maintenant lui déléguer des tâches de revue de code »

Grâce à cette capacité d’amorçage (self-bootstrapping), l’équipe peut étendre en continu la bibliothèque d’agents selon ses axes de recherche, au lieu de définir tous les scénarios une seule fois.

---

Configuration des outils et mécanismes Skills / mémoire

Configuration de la couche outils

Dans configs/magiclaw/config.yaml, vous pouvez configurer plusieurs types d’outils :

tools:
  mcp:
    # Outils de protocole MCP (système de fichiers, Git, bases de données, etc.)
    enabled: true
    servers:
      - name: filesystem
        command: npx @modelcontextprotocol/server-filesystem ./workspace

  web_search:
    enabled: true
    provider: duckduckgo         # optionnel : bing / google / serpapi

  feishu:
    read_document: true           # Lire les documents Feishu
    send_file: true               # Envoyer des fichiers

La configuration des outils détermine ce que l’Agent peut « faire », tandis que Skills détermine ce que l’Agent fait « vraiment bien ».

Système de compétences Skills

Skills sont des prompts structurés emballés, permettant à l’Agent d’être plus performant sur des tâches spécifiques. Le répertoire Skills d’EvoMaster se trouve dans evomaster/skills/. Chaque Skill est un fichier Markdown :

---
name: research-paper-summary
trigger: literature survey, paper review, paper analysis
agent: research
---

# Skill : Résumé d’article de recherche

Lorsque l’utilisateur demande de résumer ou d’analyser un article, exécute les étapes suivantes :

1. Extraire le titre de l’article, les auteurs et le venue de publication
2. Extraire les contributions clés (contribution)
3. Extraire les points importants de la méthodologie
4. Extraire les limites (limitations)
5. Produire un résumé structuré (pas plus de 300 mots)

Si l’utilisateur fournit un lien ArXiv, récupérer d’abord le contenu de la page, puis procéder à l’analyse.

Les Skills sont chargées à la demande : lors du traitement de certains types de tâches, l’Agent associe automatiquement la Skill correspondante, sans besoin de la déclencher manuellement.

Mémoire persistante

La mémoire de MagiClaw est gérée par le module evomaster/memory/, avec plusieurs backends de stockage :

memory:
  backend: sqlite               # optionnel : sqlite / redis / file
  session_ttl: 86400            # durée de conservation de la mémoire de session (en secondes)
  long_term:
    enabled: true
    store: file                 # persistant sur disque
    path: ./memory_store/

À la fin de chaque conversation, l’Agent enregistre automatiquement les contextes clés dans la mémoire. Au début de la conversation suivante, l’Agent lit la mémoire historique et conserve la cohérence entre les sessions.

---

Démonstration complète du workflow

Scénario : construire un Agent « Lecture rapide d’articles » pour l’équipe

Objectif : envoyer à un Bot un lien ArXiv dans Feishu ; il renvoie automatiquement un résumé structuré.

Étape 1 : créer l’Agent avec agent_builder

Dans Feishu, envoyez un message à MagiClaw :

Aide-moi à créer un Agent de lecture rapide d’articles, avec le nom paper_reader

agent_builder génère le répertoire playground/paper_reader/, contenant :

playground/paper_reader/
├── __init__.py
├── agent.py                   # Logique principale de l’Agent
└── config.yaml                 # Configuration au niveau de l’Agent

Étape 2 : enregistrer dans magiclaw

Après la création du nouvel Agent, éditez configs/magiclaw/config.yaml pour l’enregistrer sous playgrounds :

playgrounds:
  - name: paper_reader
    path: playground/paper_reader
    enabled: true

Après le redémarrage du robot, magiclaw saura reconnaître et déléguer à paper_reader.

Étape 3 : tester

Dans Feishu :

@Bot paper_reader https://arxiv.org/abs/2401.01234

paper_reader exécute automatiquement :

1. Récupérer la page ArXiv
2. Extraire le titre, les auteurs et le résumé
3. Générer un résumé structuré (contribution + méthode + limites)
4. Renvoyer le message dans Feishu

---

Dépannage des problèmes fréquents

Q1 : Après avoir démarré le robot, Feishu ne répond pas

Cause : l’abonnement aux événements ou la configuration de connexion longue n’est pas correcte.

Étapes de vérification :

# 1. Confirmer que le robot est publié (Feishu Open Platform → Gestion des versions et publication)
# Un bot non publié ne pourra pas envoyer/recevoir de messages dans l’environnement de production

# 2. Confirmer que la connexion longue est correctement configurée
# Feishu Open Platform → Événements et callbacks → Configuration des événements → sélectionner « Connexion longue »

# 3. Vérifier les logs de démarrage pour d’éventuelles erreurs
python -m evomaster.interface.feishu --config configs/feishu/config.yaml

---

Q2 : Le Bot reçoit les messages mais répond « opération non prise en charge »

Cause : le périmètre des permissions est insuffisant, ou l’application n’est pas publiée sur le périmètre correspondant.

Étapes de vérification :

Dans Feishu Open Platform → Gestion des permissions, vérifiez que les permissions minimales suivantes sont bien activées :

"im:message",
"im:message:send_as_bot",
"im:chat:readonly"

Si le Bot doit rejoindre des conversations de groupe, il faut aussi im:message.group_at_msg:readonly.

---

Q3 : Après que agent_builder a créé un Agent, magiclaw ne le reconnaît pas

Cause : le nouvel Agent n’a pas été enregistré dans configs/magiclaw/config.yaml.

Solution :

Vérifiez que dans configs/magiclaw/config.yaml, la liste playgrounds inclut le nouvel Agent et que enabled: true est bien défini. Après modification de la configuration, il faut redémarrer le robot.

---

Q4 : La mémoire n’est pas conservée d’une session à l’autre : l’Agent « oublie » à chaque conversation

Cause : le backend de stockage de la mémoire n’est pas configuré correctement, ou le chemin de stockage n’a pas les droits en écriture.

Étapes de vérification :

# 1. Vérifier la configuration memory dans config.yaml
memory:
  long_term:
    enabled: true
    store: file
    path: ./memory_store/

# 2. S’assurer que le répertoire memory_store existe et est accessible en écriture
mkdir -p memory_store
chmod 755 memory_store

# 3. Redémarrer le robot, envoyer un message pour déclencher l’écriture mémoire

---

Q5 : L’outil Web Search renvoie un résultat vide ou dépasse le délai (timeout)

Cause : le réseau ne peut pas accéder au service de recherche, ou les identifiants de l’API Search ne sont pas configurés.

Solution :

Si vous utilisez DuckDuckGo (gratuit, sans clé API), confirmez que votre environnement Python peut accéder à Internet :

# Test réseau
python -c "import requests; print(requests.get('https://api.duckduckgo.com/?q=test&format=json').status_code)"

Si le retour est 200 mais que le Bot time-out quand même, vérifiez que la configuration tools.web_search.provider dans configs/magiclaw/config.yaml est correcte.

---

Q6 : L’outil MCP ne démarre pas, erreur « command not found »

Cause : le npx de MCP Server ou le chemin de Node.js n’a pas été ajouté au PATH système.

Solution :

# Vérifier que npx est disponible
npx --version

# Si npx introuvable, indiquer le chemin manuellement
# Éditer configs/magiclaw/config.yaml :
tools:
  mcp:
    servers:
      - name: filesystem
        command: /usr/local/bin/npx @modelcontextprotocol/server-filesystem ./workspace

---

Lectures complémentaires et directions avancées

1. Se connecter à l’écosystème SciMaster

MagiClaw est l’entrée côté Feishu de l’écosystème EvoMaster, tandis que la série complète SciMaster (ML-Master, X-Master, Browse-Master, etc.) se trouve dans le dépôt en amont EvoMaster. Si votre axe de recherche nécessite une analyse multi-modale en science des matériaux ou une coordination entre plusieurs expériences, vous pouvez synchroniser ces agents spécialisés depuis EvoMaster et les intégrer à la couche d’orchestration de MagiClaw.

2. Outils MCP personnalisés

L’interface des outils MCP de MagiClaw permet d’intégrer n’importe quel MCP Server. Vous pouvez écrire un MCP Server en Python pour envelopper une API interne, des outils d’accès à une base de données de recherche ou un script de soumission pour un cluster HPC, puis l’enregistrer dans MagiClaw : l’Agent pourra alors appeler directement ces fonctionnalités depuis Feishu.

3. Architecture de collaboration multi-Bot

Si votre équipe dispose de plusieurs Bots ayant des responsabilités différentes (par exemple un Bot pour gérer le calendrier, un Bot pour gérer le code, un Bot pour gérer la bibliographie), vous pouvez les faire coopérer via les conversations de groupe Feishu : intégrez plusieurs Bots dans un même groupe, chacun gérant son rôle, puis basculez avec @.

4. Déploiement de modèles privés en entreprise

EvoMaster prend en charge le Provider custom, ce qui permet de brancher des LLM déployés en interne (Llama, Mistral, Qwen, etc.). Si les données de recherche ne doivent pas sortir du réseau, vous pouvez déployer les modèles localement ou sur un cloud privé. Avec l’interface Feishu de MagiClaw, les données ne quittent jamais l’intranet.

5. Ajustement du comportement des Agents

Le comportement des Agents de chaque Playground est principalement contrôlé par prompt et skills dans config.yaml. Si vous constatez que l’Agent est moins performant dans certains scénarios, vous pouvez modifier le fichier Skill correspondant, ajuster les étapes de raisonnement et le format de sortie, sans avoir à toucher au code.