Tutorial: Construindo Agentes de IA Auto-Evolutivos com OpenSpace, MCP e Reuso de Baixo Custo

Por que agentes auto-evolutivos importam agora

Em julho de 2026, construir agentes de IA que aprendem com a própria experiência deixou de ser uma ideia de pesquisa para se tornar uma realidade prática. O OpenSpace, um framework open-source desenvolvido pelo laboratório HKUDS, implementa um ciclo completo de evolução de agentes: execução de tarefas, captura de habilidades, versionamento com linhagem e reuso de baixo custo. Neste tutorial, você vai do zero a um agente auto-evolutivo funcional no Google Colab, com skills personalizados, servidor MCP e inspeção completa do banco de evolução.

✅ O que você ganha

• Agentes que melhoram com o uso: cada tarefa concluída gera skills reutilizáveis
• Custo decrescente: skills capturados (FIX, DERIVED, CAPTURED) reduzem tokens em tarefas subsequentes
• Linhagem completa: SQLite rastreia a origem e evolução de cada capacidade
• Integração nativa com MCP (Model Context Protocol) via HTTP streamable
• Compatível com Claude, GPT e qualquer modelo via API compatível com OpenAI

⚠️ O que você NÃO ganha

• Não substitui orchestration engines como LangGraph ou CrewAI — é uma camada de memória procedural
• Requer Python 3.12+ (não funciona em ambientes legados)
• Skills evoluídos têm qualidade variável — revisão humana ainda é recomendada para tarefas críticas

1. Configuração do ambiente

Comece clonando o repositório com sparse checkout para evitar baixar assets pesados desnecessários:

import os, sys, subprocess

# Verificar Python 3.12+
assert sys.version_info >= (3, 12), "OpenSpace requer Python 3.12+"

# Clone com sparse checkout (economiza ~500 MB)
REPO_DIR = "/content/OpenSpace"
subprocess.run([
    "git", "clone", "--filter=blob:none", "--sparse",
    "https://github.com/HKUDS/OpenSpace.git", REPO_DIR
], check=True)
subprocess.run([
    "git", "sparse-checkout", "set", "--no-cone", "/*", "!/assets/"
], cwd=REPO_DIR, check=True)

# Instalar em modo editável
subprocess.run([sys.executable, "-m", "pip", "install", "-q", "-e", REPO_DIR], check=True)
subprocess.run([sys.executable, "-m", "pip", "install", "-q", "nest_asyncio"], check=True)

O --filter=blob:none --sparse faz o Git baixar apenas metadados inicialmente, e o sparse-checkout exclui a pasta assets/ que contém imagens e capturas de tela do showcase. A instalação em modo editável (-e) permite modificar o código-fonte e ver as mudanças refletidas imediatamente. O nest_asyncio é necessário porque o Colab já tem um event loop rodando; ele permite aninhar loops asyncio.

2. Configuração de credenciais e workspace

import pathlib

# Definir credenciais
ANTHROPIC_API_KEY = "sk-ant-..."  # sua chave
OPENSPACE_MODEL = "anthropic/claude-sonnet-4-5"
WORKSPACE = "/content/openspace_workspace"
SKILLS_DIR = "/content/my_agent_skills"

os.makedirs(WORKSPACE, exist_ok=True)
os.makedirs(SKILLS_DIR, exist_ok=True)

# Escrever .env
env_path = pathlib.Path(REPO_DIR) / "openspace" / ".env"
env_path.write_text(f"""\
OPENSPACE_MODEL={OPENSPACE_MODEL}
OPENSPACE_WORKSPACE={WORKSPACE}
OPENSPACE_HOST_SKILL_DIRS={SKILLS_DIR}
ANTHROPIC_API_KEY={ANTHROPIC_API_KEY}
""")

O OpenSpace lê a configuração de um arquivo .env dentro da pasta openspace/ — isso mantém as credenciais fora do código e segue o princípio de 12-factor apps. A variável OPENSPACE_HOST_SKILL_DIRS aponta para a pasta onde você colocará skills personalizados que o agente pode descobrir em tempo de execução.

3. Primeira execução: tarefa de payroll

import asyncio, nest_asyncio
nest_asyncio.apply()

from openspace import OpenSpace

async def executar_tarefa(descricao: str):
    async with OpenSpace() as agente:
        resultado = await agente.execute(descricao)
        print("── RESPOSTA ──")
        print(resultado["response"][:2000])
        for skill in resultado.get("evolved_skills", []):
            print(f"  ⚡ Skill evoluído: {skill['name']} (origem={skill['origin']})")
        return resultado

# Primeira tarefa
resultado = asyncio.run(executar_tarefa(
    "Escreva uma função Python que parseia um CSV de horas trabalhadas e "
    "calcula folha de pagamento semanal com hora extra (1.5x além de 40h). "
    "Teste com um exemplo sintético."
))

O async with OpenSpace() cria um contexto de agente isolado. O método execute() é a interface principal — ele recebe uma descrição em linguagem natural, executa a tarefa e retorna a resposta junto com metadados de skills evoluídos. O parâmetro origin indica como o skill foi gerado: FIX (correção de erro), DERIVED (variação de skill existente) ou CAPTURED (novo comportamento observado).

4. Reuso de skills em tarefa relacionada

Agora a parte mais importante: executar uma segunda tarefa que se beneficia do skill gerado na primeira:

resultado2 = asyncio.run(executar_tarefa(
    "Estenda a lógica de folha de pagamento: adicione um segundo CSV com "
    "taxas de imposto retido por funcionário e produza o pagamento líquido. "
    "Reutilize qualquer skill de payroll anterior."
))

Quando o OpenSpace detecta que a nova tarefa é semanticamente relacionada a uma anterior, ele ativa automaticamente os skills relevantes. O efeito prático é que a segunda execução consome 30-60% menos tokens — o agente não precisa redescobrir padrões que já aprendeu.

5. Criando um SKILL.md personalizado

custom_skill = pathlib.Path(SKILLS_DIR) / "colab-csv-report"
custom_skill.mkdir(parents=True, exist_ok=True)

(custom_skill / "SKILL.md").write_text("""\
---
name: colab-csv-report
description: Transforma qualquer CSV em relatório markdown com estatísticas,
  contagem de nulos, dtypes e 3 observações-chave.
---

# colab-csv-report

1. Carregue o CSV com pandas (`on_bad_lines="skip"` como fallback).
2. Emita: shape, tabela de dtypes, describe(), contagem de nulos.
3. Escreva 3 observações em markdown.
4. Se o parse falhar, retente com `sep=None, engine="python"`.
""")

Skills seguem o formato SKILL.md com frontmatter YAML e corpo em markdown. O OpenSpace descobre automaticamente skills na pasta OPENSPACE_HOST_SKILL_DIRS. Você pode criar dezenas de skills especializados — o agente seleciona os relevantes por similaridade semântica com a tarefa atual.

6. Servidor MCP via HTTP streamable

# Iniciar servidor MCP
mcp_proc = subprocess.Popen([
    "openspace-mcp", "--transport", "streamable-http",
    "--host", "127.0.0.1", "--port", "8081"
], stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True)

# Configuração para Claude Desktop ou outros hosts MCP:
{
  "mcpServers": {
    "openspace": {
      "command": "openspace-mcp",
      "toolTimeout": 600,
      "env": {
        "OPENSPACE_HOST_SKILL_DIRS": "/content/my_agent_skills",
        "OPENSPACE_WORKSPACE": "/content/openspace_workspace"
      }
    }
  }
}

O servidor MCP expõe o workspace do OpenSpace para qualquer cliente compatível com MCP (Claude Desktop, Codex, Continue.dev). Isso permite que skills evoluídos em uma sessão sejam acessados por outros agentes e ferramentas.

7. Inspecionando o banco de evolução

O coração do OpenSpace é o banco SQLite que armazena cada skill com metadados de versão e linhagem:

import sqlite3

db_path = os.path.join(WORKSPACE, ".openspace", "openspace.db")
con = sqlite3.connect(db_path)
cur = con.cursor()

# Agregar skills por origem
for origin, count in cur.execute("""
    SELECT origin, COUNT(*) FROM skills
    GROUP BY origin ORDER BY 2 DESC
"""):
    print(f"  {origin:>10}: {count} skills")
# Output típico:
#   CAPTURED: 35 skills
#   DERIVED: 18 skills
#       FIX: 7 skills

Cada registro de skill inclui: nome, descrição, origem, versão, ID do skill pai (para DERIVED), hash do conteúdo, timestamp de criação e métricas de qualidade. A linhagem permite rastrear exatamente como uma capacidade evoluiu — de um FIX inicial, passando por DERIVED, até versões refinadas.

Casos de uso reais

• Processamento de documentos legais: um skill que aprende a extrair cláusulas específicas de contratos e melhora a cada lote processado
• Análise de dados financeiros: skills que evoluem para detectar anomalias em séries temporais com padrões específicos do seu negócio
• Suporte técnico automatizado: o agente captura soluções para tickets recorrentes como skills reutilizáveis, reduzindo o tempo de resolução
• Geração de código boilerplate: skills que aprendem seus padrões de projeto e geram scaffolds cada vez mais precisos
• Moderação de conteúdo: skills que evoluem para identificar novos padrões de toxicidade sem re-treinamento do modelo

Troubleshooting

• ❌ assert sys.version_info >= (3, 12) falha no Colab: O runtime padrão do Colab usa Python 3.11. Solução: vá em Runtime → Change runtime type e selecione um ambiente com Python 3.12+, ou crie um venv com Python 3.12.
• ❌ ModuleNotFoundError: No module named 'openspace': A instalação com pip install -e não foi concluída. Verifique se o diretório do repositório está correto e reinstale: pip install -e /content/OpenSpace.
• ❌ API key não reconhecida: O OpenSpace procura o .env dentro da pasta openspace/ do repositório, não na raiz. Confirme que o arquivo está em /content/OpenSpace/openspace/.env.
• ❌ Skills não são reutilizados na segunda tarefa: O OpenSpace decide quais skills ativar por similaridade semântica. Se a segunda tarefa for muito diferente, os skills não serão ativados. Tente usar linguagem mais próxima da tarefa original.
• ❌ Servidor MCP não inicia (porta ocupada): Altere a porta com --port 8082 ou mate processos anteriores com kill $(lsof -t -i:8081).

FAQ

• OpenSpace substitui LangChain ou CrewAI? Não. OpenSpace é uma camada de memória procedural — ele complementa frameworks de orquestração, adicionando capacidade de aprendizado e evolução.
• Posso usar com GPT em vez de Claude? Sim. Defina OPENSPACE_MODEL=openai/gpt-5 ou qualquer modelo compatível com a API OpenAI.
• Os skills são compartilháveis entre projetos? Skills são armazenados em SQLite por workspace. Você pode copiar o banco ou usar o openspace-upload-skill / openspace-download-skill com uma conta cloud.
• Quanto custa rodar o OpenSpace? O overhead é mínimo — o framework em si é gratuito e open-source. O custo principal são as chamadas de API do LLM, que diminuem conforme os skills evoluem.
• Funciona sem internet? Parcialmente. O motor de skills e o banco SQLite funcionam offline, mas a execução de tarefas requer acesso à API do LLM. O servidor MCP pode rodar em rede local.

Tendência: o futuro dos agentes auto-evolutivos

O OpenSpace representa uma mudança de paradigma: em vez de agentes estáticos com prompts fixos, entramos na era de agentes que acumulam conhecimento procedural como engenheiros humanos. Em 2027, a expectativa é que frameworks como OpenSpace se integrem nativamente a IDEs (VS Code, Cursor) e plataformas de deploy, permitindo que agentes evoluam continuamente em produção — aprendendo com erros, capturando soluções e reduzindo custos de inferência a cada iteração.