Introdução ao MagiClaw: equipe de agentes de pesquisa com IA no Feishu, para a colaboração acontecer naturalmente

Configuração em 15 minutos｜Experiência nativa do Feishu｜Orquestração de agentes de pesquisa｜Expansão instantânea da base EvoMaster

---

Visão geral do projeto

MagiClaw é uma plataforma de agentes de IA executada dentro do Feishu. A ideia central é esta: não criar mais uma ferramenta independente que você precise abrir manualmente — e sim integrar os agentes de IA diretamente no Feishu que você já usa todos os dias. Em grupos ou conversas privadas, basta descrever a necessidade e a equipe de agentes começa a funcionar.

Por trás do MagiClaw está a estrutura EvoMaster: uma infraestrutura leve para agentes, responsável por chamadas de ferramentas, habilidades (Skills), gerenciamento de memória e o “encaminhamento” das conversas. Isso significa que você pode concentrar sua energia em “o que fazer o agente fazer”, em vez de reconstruir repetidamente a camada de engenharia. O projeto é open source, com licença Apache 2.0, tem poucas linhas de código e é fácil de fazer desenvolvimento adicional.

---

Perfil de público-alvo

Este artigo é voltado a desenvolvedores que:

• Têm base em Python, conhecem ferramentas de colaboração como Feishu ou Lark, e querem levar capacidades de IA diretamente para a comunicação cotidiana do time
• Têm interesse em cenários de AI for Science e buscam um framework de agentes de pesquisa escalável
• Já usam EvoMaster ou um framework de agentes semelhante, e querem estender o Feishu como uma camada de interação (front-end)

Se você está procurando um “kit completo” independente de agentes de pesquisa, o MagiClaw não é essa resposta — ele conecta o ecossistema do EvoMaster ao Feishu, para que os fluxos de trabalho de pesquisa rodem de forma natural dentro das ferramentas de comunicação do seu time.

---

Dependências principais e ambiente

---

Estrutura completa de diretórios do projeto

MagiClaw/
├── evomaster/                    # Biblioteca principal do framework
│   ├── agent/                   # Classe base do Agent e tempo de execução
│   ├── core/                    # Chamadas de ferramentas essenciais e escalonamento de tarefas
│   ├── interface/
│   │   └── feishu/             # Implementação da interface do Feishu (conexão persistente, Webhook)
│   ├── memory/                  # Armazenamento de memórias persistentes
│   ├── skills/                  # Pacotes de Skills reutilizáveis
│   └── scheduler/               # Agendador de múltiplas tarefas
├── playground/
│   ├── magiclaw/               # Agente padrão de diálogo no Feishu
│   ├── agent_builder/           # Metaagente: design / geração de novos Agents
│   ├── coding_agent/            # Agente focado em escrita de código
│   ├── report_writer_agent/     # Agente focado em redação de relatórios
│   └── web_search_agent/        # Agente focado em busca na web
├── configs/
│   ├── feishu/                  # Credenciais de conexão do Feishu Bot
│   │   └── config.yaml
│   ├── magiclaw/               # Configurações de LLM, ferramentas, MCP e memória
│   │   └── config.yaml
│   └── agent_builder/           # Configurações de dois agentes para planejamento + construção
├── run.py                       # Entrada rápida via CLI
├── requirements.txt
└── pyproject.toml

---

Passo a passo: instalação

Etapa 1: clonar o código

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

Etapa 2: instalar dependências

pip install -r requirements.txt

Ou usando uv (mais rápido):

uv pip install -r requirements.txt

Etapa 3: criar uma aplicação no Feishu

1. Abra Feishu Open Platform, faça login na conta do seu time
2. Clique em Criar aplicação interna (enterprise self-built), preencha nome e descrição
3. Depois de entrar na aplicação, no menu à esquerda selecione Adicionar capacidades de aplicação, marque Robô

Etapa 4: configurar credenciais da aplicação

Copie o template de variáveis de ambiente:

cp .env.template .env

No .env, preencha as credenciais fornecidas pela plataforma Open do Feishu:

FEISHU_APP_ID=cli_xxxxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Etapa 5: importar o escopo de permissões

Na plataforma Open do Feishu, acesse Gestão de permissões → Importação/Exportação em lote de permissões e cole o JSON a seguir:

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

Etapa 6: configurar a assinatura de eventos

Em Eventos e callbacks → Configuração de eventos, selecione Receber eventos via conexão persistente e adicione os eventos a seguir:

Em Configuração de callbacks, da mesma forma selecione conexão persistente e subscreva:

Etapa 7: configurar o LLM

Edite configs/magiclaw/config.yaml e preencha suas credenciais de LLM:

llm:
  provider: openai              # ou anthropic / custom
  model: gpt-4o
  api_key: sk-...               # a partir do .env ou diretamente no arquivo de configuração
  base_url: https://api.openai.com/v1  # opcional, para endpoint personalizado

Etapa 8: publicar a aplicação e iniciar

Na plataforma Open do Feishu, em Gerenciamento de versões e publicação, crie uma versão e publique para ativar o Bot.

Em seguida, inicie o robô:

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

Após iniciar com sucesso, envie uma mensagem ao Bot no Feishu: ele responderá. No estado inicial, ele é um agente de conversa genérico, com capacidade de contexto em múltiplas rodadas e memória.

---

Arquitetura em dois Agents centrais

As capacidades reais do MagiClaw vêm da combinação de dois Playground internos: magiclaw lida com as conversas do dia a dia, e agent_builder ajuda você a criar novos agentes especializados.

magiclaw: orquestrador de conversas do Feishu

O magiclaw é o agente de diálogo do Feishu ativado por padrão; sua capacidade central é a orquestração e delegação.

Quando você envia uma solicitação complexa, o magiclaw não tenta resolver tudo sozinho. Em vez disso, ele identifica quais capacidades especializadas são necessárias para a tarefa e, por meio de chamadas de ferramentas, delega o trabalho a outros Playground já registrados:

No Feishu, você diz: «Ajude-me a pesquisar os avanços mais recentes da arquitetura RAG na área financeira e escreva um relatório»

→ o magiclaw recebe a solicitação
→ identifica a necessidade: pesquisa de literatura (web_search_agent) + redação de relatório (report_writer_agent)
→ chama os dois Agents separadamente
→ consolida os resultados e retorna a mensagem no Feishu

Esse mecanismo de delegação mantém o magiclaw enxuto: ele não precisa “fazer tudo”, apenas saber quando chamar quem. As capacidades de todos os Agents especializados são estendidas por Skills e por interfaces de ferramentas.

agent_builder: metaagente

O agent_builder é a parte mais interessante do MagiClaw: ele também é um Agent, mas sua função é desenhar e gerar novos Agents.

Você diz que tipo de tarefa quer fazer, e ele:

1. Analisa a necessidade e extrai as capacidades centrais que o Agent precisa
2. Gera o arquivo de Skills do Agent (YAML frontmatter + descrição em Markdown)
3. Escreve no diretório playground/ e registra no MagiClaw
4. O novo Agent fica disponível imediatamente; o magiclaw pode delegar a ele

No Feishu, você diz: «Preciso de um Agent especializado para revisão de código»

→ o agent_builder analisa a necessidade
→ gera `code_reviewer_agent.py` + o arquivo de configuração correspondente
→ registra no sistema
→ responde: «Criado code_reviewer. O magiclaw agora pode delegar tarefas de revisão de código a ele.»

Essa capacidade de “bootstrapping” permite que o time expanda continuamente a biblioteca de Agents de acordo com suas linhas de pesquisa, em vez de definir todos os cenários de uma vez.

---

Configuração de ferramentas e mecanismo de Skills / memória

Configuração da camada de ferramentas

Em configs/magiclaw/config.yaml é possível configurar diversos tipos de ferramentas:

tools:
  mcp:
    # Ferramentas do protocolo MCP (como sistema de arquivos, Git, bancos de dados 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           # ler documentos do Feishu
    send_file: true               # enviar arquivos

A configuração das ferramentas determina o que o Agent consegue “fazer”; já as Skills determinam “como ele faz bem”.

Sistema de Skills

Skills são prompts estruturados encapsulados que fazem o Agent ter melhor desempenho em tarefas específicas. O diretório de Skills do EvoMaster fica em evomaster/skills/, e cada Skill é um arquivo Markdown:

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

# Skill de resumo de artigo de pesquisa

Quando o usuário solicitar a síntese ou análise de um artigo, execute os passos a seguir:

1. Extraia título, autores e venue de publicação do artigo
2. Extraia as contribuições centrais (contribution)
3. Extraia os pontos-chave da metodologia
4. Extraia as limitações (limitations)
5. Gere um resumo estruturado (máximo de 300 palavras)

Se o usuário fornecer um link do ArXiv, primeiro extraia o conteúdo da página e depois analise.

As Skills são carregadas sob demanda. Quando o Agent lida com um tipo específico de tarefa, ele encontra automaticamente a Skill correspondente, sem necessidade de acionamento manual.

Memória persistente

A memória do MagiClaw é gerenciada pelo módulo evomaster/memory/, com suporte a diferentes backends de armazenamento:

memory:
  backend: sqlite               # opcional: sqlite / redis / file
  session_ttl: 86400            # tempo de retenção da memória da sessão (em segundos)
  long_term:
    enabled: true
    store: file                 # persistir em disco
    path: ./memory_store/

Ao final de cada conversa, o Agent salva automaticamente os contextos-chave na memória. No início da próxima sessão, o Agent lê as memórias históricas, mantendo a coerência entre conversas.

---

Demonstração completa do fluxo de trabalho

Cenário: construir um Agent de «leitura rápida de artigos» para o time

Objetivo: no Feishu, enviar ao Bot um link do ArXiv; ele retorna automaticamente um resumo estruturado do artigo.

Etapa 1: criar o Agent com agent_builder

No Feishu, envie uma mensagem ao MagiClaw:

Ajude-me a criar um Agent de leitura rápida de artigos chamado paper_reader

O agent_builder gera o diretório playground/paper_reader/, contendo:

playground/paper_reader/
├── __init__.py
├── agent.py                   # lógica principal do Agent
└── config.yaml                 # configuração do Agent

Etapa 2: registrar no magiclaw

Após criar o novo Agent, edite configs/magiclaw/config.yaml e registre em playgrounds:

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

Depois de reiniciar o robô, o magiclaw consegue reconhecer e delegar para o paper_reader.

Etapa 3: testar

No Feishu:

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

O paper_reader executa automaticamente:

1. Buscar a página do ArXiv
2. Extrair título, autores e resumo
3. Gerar um resumo estruturado (contribuição + metodologia + limitações)
4. Retornar a mensagem no Feishu

---

Resolução de problemas comuns

Q1: Após iniciar o robô, o Feishu não responde

Causa: a assinatura de eventos ou a configuração de conexão persistente está incorreta.

Passos de verificação:

# 1. Confirmar que o robô foi publicado (Feishu Open Platform → Gerenciamento de versões e publicação)
# Robôs não publicados não podem enviar/receber mensagens no ambiente de produção

# 2. Confirmar que a conexão persistente está configurada corretamente
# Feishu Open Platform → Eventos e callbacks → Configuração de eventos → selecionar «conexão persistente»

# 3. Verificar se há erros no log de inicialização
python -m evomaster.interface.feishu --config configs/feishu/config.yaml

---

Q2: O Bot recebe a mensagem, mas responde «Operação não suportada»

Causa: o escopo de permissões é insuficiente, ou a aplicação não foi publicada para o escopo correspondente.

Passos de verificação:

Na plataforma Open do Feishu → Gestão de permissões, confirme que o conjunto mínimo de permissões a seguir foi ativado:

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

Se o Bot precisar entrar em salas de grupo, também será necessário im:message.group_at_msg:readonly.

---

Q3: Após o agent_builder criar o Agent, o magiclaw não consegue reconhecê-lo

Causa: o novo Agent não foi registrado em configs/magiclaw/config.yaml.

Solução:

Verifique se, na lista playgrounds de configs/magiclaw/config.yaml, você adicionou o novo Agent e definiu enabled: true. Após alterar a configuração, é necessário reiniciar o robô.

---

Q4: A memória não é preservada entre sessões; em cada conversa o Agent parece “esquecer”

Causa: o backend de armazenamento de memória não está configurado corretamente, ou o caminho de armazenamento não tem permissão de escrita.

Passos de verificação:

# 1. Verifique a configuração de memory em config.yaml
memory:
  long_term:
    enabled: true
    store: file
    path: ./memory_store/

# 2. Garanta que o diretório memory_store exista e seja gravável
mkdir -p memory_store
chmod 755 memory_store

# 3. Reinicie o robô e envie uma mensagem para acionar a gravação da memória

---

Q5: A ferramenta de Web Search retorna resultado vazio ou dá timeout

Causa: a rede não consegue acessar o serviço de busca, ou as credenciais da Search API não foram configuradas.

Solução:

Se estiver usando DuckDuckGo (gratuito, sem necessidade de API Key), confirme que o ambiente Python consegue acessar a internet:

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

Se retornar 200, mas o Bot ainda der timeout, verifique se a configuração tools.web_search.provider em configs/magiclaw/config.yaml está correta.

---

Q6: A ferramenta MCP não consegue iniciar e aparece «command not found»

Causa: o caminho do npx do MCP Server ou do Node.js não foi adicionado ao PATH do sistema.

Solução:

# Confirmar que o npx está disponível
npx --version

# Se não encontrar npx, informe o caminho manualmente
# Edite configs/magiclaw/config.yaml:
tools:
  mcp:
    servers:
      - name: filesystem
        command: /usr/local/bin/npx @modelcontextprotocol/server-filesystem ./workspace

---

Leitura adicional e caminhos para avançar

1. Conectar ao ecossistema do SciMaster

MagiClaw é a porta de entrada do Feishu para o ecossistema EvoMaster, e a série completa do SciMaster (ML-Master, X-Master, Browse-Master etc.) fica no repositório upstream EvoMaster. Se a sua linha de pesquisa exigir análise de ciência dos materiais multimodal ou colaboração entre múltiplos experimentos, você pode sincronizar esses Agents especializados do EvoMaster e integrar a camada de orquestração do MagiClaw.

2. Criar ferramentas MCP personalizadas

A interface de ferramentas MCP do MagiClaw suporta conectar qualquer MCP Server. Você pode escrever um MCP Server em Python para encapsular APIs internas, ferramentas de consulta em bancos de dados de pesquisa ou scripts para submissão em clusters HPC; depois, registre-o no MagiClaw para que o Agent chame diretamente no Feishu.

3. Arquitetura de colaboração com múltiplos Bots

Se o time tiver vários Bots com funções diferentes (por exemplo, um para gerenciar calendário, outro para gerenciar código e outro para gerenciar literatura), é possível fazê-los colaborar via conversas em grupos do Feishu: integrar vários Bots em um grupo, cada um responsável pela sua função, alternando por @.

4. Implantação de modelos privados do time

O EvoMaster suporta o Provider custom, permitindo conectar LLMs implantados internamente na empresa (Llama, Mistral, Qwen etc.). Se os dados de pesquisa não puderem sair, você pode implantar modelos localmente ou em uma nuvem privada; ao operar pela interface do MagiClaw, os dados não saem totalmente da rede interna.

5. Ajuste fino do comportamento dos Agents

O comportamento do Agent de cada Playground é controlado principalmente pelo prompt e pelas skills em config.yaml. Se você perceber que o Agent tem desempenho ruim em certos cenários, pode editar o arquivo de Skill correspondente, ajustando os passos de raciocínio e o formato de saída do Agent, sem precisar mexer no código.