GeminiClaw: O Orquestrador Multi-Agente Local-First que Construímos para Operar no Mundo Real

A maioria dos "agentes de IA" que você vê por aí são, na prática, chatbots glorificados: recebem uma mensagem, chamam uma LLM, devolvem texto. O GeminiClaw foi construído para fazer o oposto — executar operações reais, com rastreabilidade, segurança e autonomia configurável. É o projeto que nasceu dentro da Autenticare e que agora tem seu próprio endereço: geminiclaw.dev.

---

Por que construir mais um framework de agentes?

A pergunta é legítima. Existem dezenas de frameworks disponíveis — LangChain, LlamaIndex, CrewAI, AutoGen. A resposta curta é: nenhum deles era bom o suficiente para operar em produção sem supervisão constante.

Os problemas recorrentes que identificamos em projetos reais:

• Ausência de Loop Guard: agentes entravam em loops infinitos ou sequências longas sem ponto de parada controlado.
• Permissões em excesso: um agente de "consulta" acabava tendo ferramentas de escrita por herança de configuração.
• Memória sem fronteiras: contextos de diferentes sessões se misturavam, gerando respostas incoerentes ou com vazamento de dados.
• Nenhuma superfície de auditoria: quando algo dava errado, não havia como reconstruir o que o agente fez e por quê.

O GeminiClaw foi construído sobre o livro Building Applications with AI Agents (Michael Albada, O'Reilly) — uma das fontes técnicas mais sólidas sobre engenharia de agentes — e depois adaptado para as necessidades operacionais reais que encontramos em campo.

---

A arquitetura em termos que importam para operações

O modelo conceitual do GeminiClaw tem uma distinção que raramente aparece em outros frameworks:

Essa separação de conceitos não é acadêmica — ela determina como você expande o sistema sem criar acoplamento acidental. Um canal não é um agente. Uma skill não é uma ferramenta. Um MCP não é um agente. Essas confusões geram sistemas frágeis.

---

O que o GeminiClaw faz de diferente na prática

1. Orquestração multi-agente com ownership claro

O GeminiClaw opera com um agente orquestrador principal + agentes subordinados especializados. A regra de Request Ownership é explícita no runtime: toda tarefa permanece com o agente para quem o usuário a endereçou. Handoffs funcionam para delegação com escopo — não para reassignação silenciosa. Isso evita a confusão clássica de "quem está respondendo agora?".

Cada agente tem: intent-aware tool subsets (quick_answer, read_only, execute, plan_first), isolamento por agentId + chatId, e memória semântica de longo prazo via gemini-embedding-2-preview — o mesmo modelo multimodal que indexa texto, imagens, áudio e documentos num espaço vetorial unificado.

2. Execução autônoma com portas de segurança

Este é o ponto onde a maioria dos frameworks para. O GeminiClaw tem um sistema de controle de autonomia em múltiplas camadas:

• Planning Gate (present_code_plan): nenhuma mutação de código ocorre sem um plano aprovado.
• Risk Gate: ferramentas de alto impacto exigem aprovação explícita antes de execução.
• Loop Guard: operações longas têm contagem de autonomia ajustável para evitar loops infinitos.
• Checkpoint/Replay: recovery durável de execuções — se algo falha no meio, o runtime pode retomar a partir do último checkpoint.

"O agente não é autônomo porque não tem limites. É autônomo porque os limites estão bem definidos — e ele opera com confiança dentro deles."

3. Operações reais de Google Ads B2B

Um dos verticais mais concretos: automação completa de Google Ads via API. Não é "gerar texto para anúncios". É operação real:

• Diagnóstico e mutação de campanhas via Google Ads API
• Workflows de otimização em batch (optimize_campaign_batch)
• Dayparting, budgets, otimização de RSA, negativos, geo targeting
• Automação de guardrail demográfico (apply_demographic_guard)
• Gerenciamento de conversões offline + pipeline de qualidade de leads

4. GeminiClaw Studio — o painel que faltava

Todo o runtime é operado via GeminiClaw Studio, um dashboard web com design orientado ao operador (não ao desenvolvedor).

O Pixel Arena: cada agente aparece como personagem no mapa, com estado e contexto de trabalho visíveis em tempo real. Estado "STABLE" + Guided Paths no painel lateral.

As superfícies principais:

• Board: Kanban operacional para gestão de tarefas e monitoramento de agentes em tempo real.
• Timeline Unificada: auditoria de nível de tarefa, histórico de tool calls e traces de mensagens.
• Memory Governance: inspeção, expiração, redação e purge de memórias estruturadas e semânticas — com trilha de auditoria explícita.
• Session Contexts: criação, ativação e inspeção de contextos de sessão que mudam as fronteiras de memória do agente para modo trabalho.
• Scheduler Center: monitoramento e controle de rotinas agendadas.
• Governance Inbox: recomendações de governança de memória agrupadas por urgência, com ações diretas — sem precisar navegar em tabelas técnicas brutas.

O Board do GeminiClaw Master: 42 tarefas distribuídas entre New, In Progress, Awaiting Approval, Blocked e Done — com timestamps e rastreabilidade completa.

5. Controle de contexto via Telegram

O GeminiClaw tem um conjunto de comandos Telegram nativos para operação em campo — sem precisar abrir o Studio:

• /session — exibe o contexto de trabalho ativo
• /session_set <sessionId> — ativa uma sessão específica
• /session_complete — marca sessão como concluída e gera recap durável
• /session_suggest <mensagem> — sugere qual sessão melhor corresponde à intenção atual

---

Riscos reais e onde o GeminiClaw ainda tem fricções

Sem absolutismos: todo sistema de agentes em produção tem limitações. O GeminiClaw não é exceção.

• Curva de configuração: o runtime local exige Node 20+, Telegram bot token, Gemini API key e variáveis de ambiente bem configuradas. Não é plug-and-play para usuários não-técnicos.
• Custo de tokens em operações longas: loops autônomos consomem contexto rapidamente. O Loop Guard ajuda, mas o custo ainda exige monitoramento.
• Integração MCP: o protocolo Model Context Protocol é suportado como camada de integração, mas A2A (Agent-to-Agent interoperability) ainda é trabalho futuro — atualmente o GeminiClaw usa messaging interno próprio.
• Licença proprietária: o repositório atual é proprietary/internal. O acesso público está no roadmap de maturidade.

---

Como o GeminiClaw conecta com a metodologia A-MAD da Autenticare

O GeminiClaw não é um projeto paralelo — é a implementação prática da metodologia A-MAD (AI-Managed Agile Development) que a Autenticare usa em projetos de clientes.

Quando falamos em "agentes que orquestram a estrutura pesada enquanto engenheiros focam nos 20% de diferencial competitivo", o GeminiClaw é o runtime que viabiliza isso. O Planning Gate garante que a IA não mute código sem aprovação. O Loop Guard garante que operações longas não fujam do controle. A trilha de auditoria garante que o time saiba exatamente o que aconteceu.

Em projetos reais, usamos o GeminiClaw para:

• Automação de operações de Google Ads para clientes B2B com orçamentos significativos
• Gestão de contexto de trabalho em sessões longas de desenvolvimento assistido por IA
• Pipelines de lead-to-conversion com feedback de qualidade automatizado

---

Começando com o GeminiClaw

O projeto está em maturidade de produção interna. O site oficial com documentação completa está em geminiclaw.dev.

Para quem quer explorar o stack técnico, os pré-requisitos são simples:

• Node.js 20+
• Token de bot Telegram
• Chave da API Gemini

E o comando de inicialização é único: npm run watchdog — o watchdog supervisiona o runtime Telegram e gerencia o ciclo de vida do processo com segurança.

Se você está construindo sistemas de agentes para produção e quer ver como governança, observabilidade e execução real se parecem quando estão juntos desde o design — comece pelo GeminiClaw. Ou fale com a gente: a Autenticare implementa stacks de agentes com esse nível de maturidade operacional.