Introducción a MagiClaw: equipo de agentes de investigación con IA en Feishu para que la colaboración ocurra de forma natural

Configuración en 15 minutos｜Experiencia nativa de Feishu｜Orquestación de agentes de investigación｜Expansión en un clic sobre la base EvoMaster

---

Introducción del proyecto

MagiClaw es una plataforma de agentes de IA que se ejecuta en Feishu. La idea central es esta: en lugar de crear otra herramienta independiente que tengas que abrir específicamente, inserta directamente los agentes de IA en Feishu, el que usas todos los días. En un chat de grupo o en un mensaje privado, describes lo que necesitas y el equipo de agentes empieza a funcionar.

Detrás de MagiClaw está el framework EvoMaster: una infraestructura ligera para agentes, encargada de la invocación de herramientas, las Skills, la gestión de memoria y el “cableado” de la conversación. Esto significa que puedes concentrarte en «definir qué debe hacer el agente», en lugar de volver a montar desde cero la capa de ingeniería. El proyecto es de código abierto, con licencia Apache 2.0, tiene poco código y es fácil de desarrollar en segunda iteración.

---

Perfil de lectores objetivo

Este artículo está dirigido a los siguientes desarrolladores:

• Tienes base en Python, conoces Feishu o herramientas de colaboración como Lark y quieres incorporar capacidades de IA directamente en la comunicación diaria del equipo
• Te interesa el escenario de IA para la ciencia (AI for Science) y buscas un marco de agentes de investigación escalable
• Ya estás usando EvoMaster o un framework de agentes similar, y quieres ampliar Feishu como una capa de interacción frontal

Si estás buscando un “kit familiar” completo de un agente de investigación independiente, MagiClaw no es esa respuesta: conecta el ecosistema de EvoMaster con Feishu, para que los flujos de trabajo de investigación se integren y corran de forma natural dentro de las herramientas de comunicación de tu equipo.

---

Dependencias principales y entorno

---

Estructura completa del árbol del proyecto

MagiClaw/
├── evomaster/                    # Biblioteca del framework principal
│   ├── agent/                   # Clase base de Agent y runtime
│   ├── core/                    # Llamadas a herramientas y planificación de tareas
│   ├── interface/
│   │   └── feishu/             # Implementación de Feishu (conexión persistente, Webhook)
│   ├── memory/                  # Almacenamiento de memoria persistente
│   ├── skills/                  # Paquetes de Skills reutilizables
│   └── scheduler/               # Planificador de múltiples tareas
├── playground/
│   ├── magiclaw/               # Agente de conversación predeterminado para Feishu
│   ├── agent_builder/           # Meta-agent: diseña / genera nuevos Agents
│   ├── coding_agent/            # Agent especializado para escritura de código
│   ├── report_writer_agent/     # Agent especializado para redacción de informes
│   └── web_search_agent/        # Agent especializado para búsqueda web
├── configs/
│   ├── feishu/                  # Credenciales de conexión del Bot de Feishu
│   │   └── config.yaml
│   ├── magiclaw/               # Configuración de LLM, herramientas, MCP y memoria
│   │   └── config.yaml
│   └── agent_builder/           # Configuración de dos Agents: planificación + construcción
├── run.py                       # Entrada rápida por CLI
├── requirements.txt
└── pyproject.toml

---

Pasos de instalación guiados

Paso 1: clonar el código

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

Paso 2: instalar dependencias

pip install -r requirements.txt

O con uv (más rápido):

uv pip install -r requirements.txt

Paso 3: crear una aplicación en Feishu

1. Abre Feishu Open Platform e inicia sesión con la cuenta de tu equipo
2. Haz clic en Crear una aplicación empresarial autogestionada y completa el nombre y la descripción
3. Una vez dentro de la aplicación, en el menú de la izquierda selecciona Agregar capacidades de la aplicación y marca Bot

Paso 4: configurar credenciales de la aplicación

Copia la plantilla de variables de entorno:

cp .env.template .env

En .env, completa las credenciales proporcionadas por la plataforma:

FEISHU_APP_ID=cli_xxxxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Paso 5: importar rangos de permisos

En la plataforma de Feishu, entra en Gestión de permisos → Importar/exportar permisos en lote y pega el siguiente JSON:

{
  "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"
    ]
  }
}

Paso 6: configurar la suscripción de eventos

En Eventos y devoluciones (callbacks) → Configuración de eventos, selecciona Usar conexión persistente para recibir eventos y agrega los siguientes eventos:

En Configuración de callbacks, selecciona también la conexión persistente y suscríbete a:

Paso 7: configurar LLM

Edita configs/magiclaw/config.yaml e introduce tus credenciales de LLM:

llm:
  provider: openai              # o anthropic / custom
  model: gpt-4o
  api_key: sk-...               # desde .env o escrito directamente en el archivo de configuración
  base_url: https://api.openai.com/v1  # opcional: endpoint personalizado

Paso 8: publicar la aplicación y arrancar

En la plataforma de Feishu Gestión de versiones y publicación, crea una versión y publícala para que el Bot entre en funcionamiento.

Luego inicia el bot:

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

Si el inicio tiene éxito, envíale un mensaje al Bot en Feishu y este responderá. En el estado inicial, es un agente conversacional general que cuenta con contexto de múltiples turnos y capacidades de memoria.

---

Arquitectura de doble Agent central

Las capacidades reales de MagiClaw provienen de la combinación de dos Playground integrados: magiclaw gestiona las conversaciones diarias y agent_builder te ayuda a crear nuevos agentes especializados.

magiclaw: orquestador de conversaciones en Feishu

magiclaw es el agente de conversación de Feishu activado por defecto. Su capacidad central es la orquestación y la delegación.

Cuando envías una solicitud compleja, magiclaw no intenta resolverlo todo por sí solo. En su lugar, identifica qué capacidades especializadas necesita la tarea y delega el trabajo a otros Playground ya registrados mediante llamadas a herramientas:

En Feishu: «Ayúdame a investigar los avances más recientes de la arquitectura RAG en el sector financiero y escribe un informe»

→ magiclaw recibe la solicitud
→ determina que se necesita: investigación de literatura (web_search_agent) + redacción del informe (report_writer_agent)
→ llama a esos dos Agents por separado
→ resume los resultados y devuelve el mensaje en Feishu

Este mecanismo de delegación mantiene a magiclaw ligero: no necesita saber de todo; solo debe saber cuándo llamar a quién. Las capacidades de todos los Agents especializados se amplían mediante Skills y la interfaz de herramientas.

agent_builder: meta-agent

agent_builder es la parte más interesante de MagiClaw. Él mismo también es un Agent, pero su responsabilidad es diseñar y generar nuevos Agents.

Le indicas qué tipo de tareas quieres realizar y él:

1. Analiza el requerimiento y extrae las capacidades clave que necesita el Agent
2. Genera el archivo de Skills del Agent (frontmatter YAML + descripción en Markdown)
3. Escribe en el directorio playground/ y registra en MagiClaw
4. El nuevo Agent queda disponible al instante, y magiclaw puede delegarle tareas

En Feishu: «Necesito un Agent especializado para hacer revisión de código»

→ agent_builder analiza el requerimiento
→ genera `code_reviewer_agent.py` + el archivo de configuración correspondiente
→ registra en el sistema
→ responde: «Se creó code_reviewer; ahora magiclaw puede delegar tareas de revisión de código»

Esta capacidad de “autoboostrap” permite que el equipo amplíe continuamente el catálogo de Agents según sus líneas de investigación, en lugar de definir todos los escenarios de una sola vez.

---

Configuración de herramientas y mecanismos de Skills / memoria

Configuración de la capa de herramientas

En configs/magiclaw/config.yaml puedes configurar varios tipos de herramientas:

tools:
  mcp:
    # Herramientas del protocolo MCP (como sistema de archivos, Git, base de datos, etc.)
    enabled: true
    servers:
      - name: filesystem
        command: npx @modelcontextprotocol/server-filesystem ./workspace

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

  feishu:
    read_document: true           # leer documentos de Feishu
    send_file: true               # enviar archivos

La configuración de herramientas determina qué puede “hacer” el Agent; mientras que Skills determina “qué tan bien” lo hace.

Sistema de Skills

Skills son prompts estructurados encapsulados que permiten que el Agent tenga mejor desempeño en tareas específicas. El directorio de Skills de EvoMaster está en evomaster/skills/. Cada Skill es un archivo Markdown:

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

# Research Paper Summary Skill

Cuando el usuario solicite resumir o analizar un artículo, ejecuta los siguientes pasos:

1. Extraer el título del paper, autores y venue
2. Extraer las contribuciones principales (contribution)
3. Extraer los puntos clave de la metodología
4. Extraer las limitaciones (limitations)
5. Generar un resumen estructurado (no más de 300 palabras)

Si el usuario proporciona un enlace de ArXiv, primero extrae el contenido de la página y luego realiza el análisis.

Las Skills se cargan según sea necesario. Cuando el Agent procesa un tipo de tarea específico, coincide automáticamente con la Skill correspondiente, sin necesidad de activarla manualmente.

Memoria persistente

La memoria de MagiClaw se gestiona mediante el módulo evomaster/memory/, con soporte para diversos backends de almacenamiento:

memory:
  backend: sqlite               # opcional: sqlite / redis / file
  session_ttl: 86400            # tiempo de retención de memoria de sesión (segundos)
  long_term:
    enabled: true
    store: file                 # persistir en disco
    path: ./memory_store/

Al finalizar cada conversación, el Agent escribe automáticamente el contexto clave en la memoria. Cuando comienza la siguiente sesión, el Agent lee la memoria histórica y mantiene la coherencia entre conversaciones.

---

Demostración del flujo de trabajo completo

Escenario: construir un Agent de «lectura rápida de artículos» para el equipo

Objetivo: en Feishu, enviarle a Bot un enlace de ArXiv; este devuelve automáticamente un resumen estructurado.

Paso 1: crear el Agent con agent_builder

En Feishu, envía un mensaje a MagiClaw:

Ayúdame a crear un Agent de lectura rápida de artículos, y llámalo paper_reader

agent_builder generará el directorio playground/paper_reader/, que contiene:

playground/paper_reader/
├── __init__.py
├── agent.py                   # lógica principal del Agent
└── config.yaml                 # configuración a nivel de Agent

Paso 2: registrarlo en magiclaw

Después de crear el nuevo Agent, edita configs/magiclaw/config.yaml para registrar en playgrounds:

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

Tras reiniciar el bot, magiclaw podrá reconocer y delegar en paper_reader.

Paso 3: prueba

En Feishu:

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

paper_reader ejecuta automáticamente:

1. Descargar la página de ArXiv
2. Extraer título, autores y resumen
3. Generar un resumen estructurado (contribución + método + limitaciones)
4. Devolver el mensaje en Feishu

---

Solución de problemas frecuentes

Q1: Después de arrancar el bot, Feishu no responde

Causa: la suscripción de eventos o la configuración de conexión persistente es incorrecta.

Pasos de verificación:

# 1. Confirmar que el bot ya está publicado (Feishu Open Platform → Gestión de versiones y publicación)
# Los bots no publicados no pueden enviar/recibir mensajes en producción

# 2. Confirmar que la conexión persistente está configurada correctamente
# Feishu Open Platform → Eventos y callbacks → Configuración de eventos → seleccionar «Conexión persistente»

# 3. Revisar si el log de arranque muestra errores
python -m evomaster.interface.feishu --config configs/feishu/config.yaml

---

Q2: El Bot recibe el mensaje, pero responde «No se admite esta operación»

Causa: el rango de permisos es insuficiente o la aplicación no se ha publicado para el ámbito correspondiente.

Pasos de verificación:

En Feishu Open Platform → Gestión de permisos, confirma que se haya habilitado el siguiente conjunto mínimo de permisos:

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

Si el Bot necesita unirse a un grupo, también se requiere im:message.group_at_msg:readonly.

---

Q3: Después de que agent_builder cree un Agent, magiclaw no puede reconocerlo

Causa: el nuevo Agent no se ha registrado en configs/magiclaw/config.yaml.

Solución:

Confirma que en configs/magiclaw/config.yaml, dentro de la lista playgrounds, se haya agregado el nuevo Agent y que se haya configurado enabled: true. Después de modificar la configuración, es necesario reiniciar el bot.

---

Q4: La memoria no se conserva entre sesiones y en cada conversación el Agent parece haber “olvidado”

Causa: el backend de almacenamiento de memoria no está configurado correctamente o la ruta de almacenamiento no tiene permisos de escritura.

Pasos de verificación:

# 1. Revisar la configuración de memory en config.yaml
memory:
  long_term:
    enabled: true
    store: file
    path: ./memory_store/

# 2. Asegurar que el directorio memory_store exista y tenga permisos de escritura
mkdir -p memory_store
chmod 755 memory_store

# 3. Reiniciar el bot y enviar un mensaje para activar la escritura de memoria

---

Q5: La herramienta Web Search devuelve resultados vacíos o expira el tiempo

Causa: no hay acceso de red al servicio de búsqueda, o no se han configurado credenciales para Search API.

Solución:

Si usas DuckDuckGo (gratis, sin necesidad de API Key), confirma que tu entorno Python pueda acceder a Internet:

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

Si devuelve 200 pero el Bot sigue excediendo el tiempo de espera, revisa si en configs/magiclaw/config.yaml la configuración de tools.web_search.provider es correcta.

---

Q6: La herramienta MCP no puede iniciarse y muestra “command not found”

Causa: la ruta de npx de MCP Server o de Node.js no se ha agregado al PATH del sistema.

Solución:

# Confirmar que npx está disponible
npx --version

# Si aparece que no se encuentra npx, especifica la ruta manualmente
# Editar configs/magiclaw/config.yaml:
tools:
  mcp:
    servers:
      - name: filesystem
        command: /usr/local/bin/npx @modelcontextprotocol/server-filesystem ./workspace

---

Lecturas adicionales y direcciones de nivel avanzado

1. Conectar el ecosistema SciMaster

MagiClaw es la puerta de entrada de Feishu al ecosistema de EvoMaster. La serie completa de SciMaster (ML-Master, X-Master, Browse-Master, etc.) se encuentra en el repositorio aguas arriba EvoMaster. Si tu línea de investigación requiere análisis de ciencia de materiales multimodal o coordinación de múltiples experimentos, puedes sincronizar estos Agents especializados desde EvoMaster, y conectar la capa de orquestación de MagiClaw.

2. Crear herramientas MCP personalizadas

La interfaz de herramientas MCP de MagiClaw soporta conectar cualquier MCP Server. Puedes usar Python para escribir un MCP Server que encapsule una API interna, herramientas para consultar bases de datos de investigación o scripts para enviar trabajos a un clúster HPC. Luego, regístralo en MagiClaw para que el Agent llame directamente a esas capacidades desde Feishu.

3. Arquitectura de colaboración con múltiples Bots

Si el equipo cuenta con varios Bots con diferentes funciones (por ejemplo, uno para gestionar calendario, otro para gestionar código y otro para gestionar bibliografía), puedes hacer que colaboren mediante chats de grupo en Feishu: integra varios Bots en un mismo grupo, y cada uno se encarga de su función; cambia entre ellos usando @.

4. Despliegue de modelos privados para el equipo

EvoMaster soporta el Provider custom, con lo que puedes conectar LLM desplegados internamente en la empresa (Llama, Mistral, Qwen, etc.). Si los datos de investigación no pueden salir, puedes desplegar el modelo en local o en una nube privada. Luego, mediante la interfaz de Feishu de MagiClaw, los datos no abandonan la red interna en ningún momento.

5. Ajuste fino del comportamiento del Agent

El comportamiento de los Agents en cada Playground está controlado principalmente por el prompt y las skills del config.yaml. Si descubres que el Agent no rinde bien en ciertos escenarios, puedes modificar el archivo de Skills correspondiente, ajustando los pasos de razonamiento y el formato de salida del Agent; no es necesario tocar el código.