Zeobra: um agente WhatsApp para gerir obras

A maior parte do trabalho de um arquiteto durante uma obra não é projeto. É logística. Foto de nota fiscal, áudio do empreiteiro explicando o que pagou, planilha de cronograma, contrato com o fornecedor, diário do canteiro. Tudo isso chega no WhatsApp dos clientes e fica espalhado entre conversas, álbuns e pastas no celular.

O Zeobra resolve isso transformando o próprio WhatsApp na ferramenta de gestão. Nada de baixar um app novo. Você manda foto, áudio ou texto pro Zé, e ele organiza tudo nas tabelas certas: pagamentos, contratos, diário de obra, documentos. Quando você quer ver o quadro completo, abre o app web.

Este post é sobre como funciona por dentro: as decisões de arquitetura, o stack, e o que aprendemos colocando isso em produção.

Por que WhatsApp, não um app novo

Arquitetos e proprietários de obra já vivem no WhatsApp. Pedir pra eles instalarem um app dedicado, criarem conta, lembrarem senha - é onde 90% das ferramentas de gestão de obra morrem. A taxa de adoção colapsa.

A inversão: o "app" novo é o agente do outro lado da conversa. O onboarding é mandar uma mensagem. Não há nada para aprender. A coisa que o usuário mais faz no celular - mandar foto/áudio em conversa - é a interação principal.

Tradeoff: a interface é texto + mídia, não grids e filtros. Para isso temos um painel web complementar. Mas a entrada e a operação no dia-a-dia ficam onde o usuário já está.

Arquitetura geral

WhatsApp (mensagem do usuário)
  ↓
WhatsApp Business API (webhook)
  ↓
Agente Zé Obra (orquestrador)
  ├─ Visão (OCR + classificação de imagem)
  ├─ Áudio (transcrição + intent)
  ├─ Texto (LLM com tools)
  └─ Loop de confirmação humana
  ↓
Banco de dados (projetos, pagamentos, contratos, diário, docs)
  ↓
Resposta no WhatsApp + painel web atualizado

O agente recebe a mensagem, decide o que ela é (nota fiscal? áudio narrando pagamento? foto do canteiro? pergunta de status?), extrai os dados estruturados, confirma com o usuário antes de gravar, e responde de volta no WhatsApp.

A entrada multimodal

Cada mensagem pode ser texto, imagem ou áudio. O agente normaliza todos os três para um formato comum antes de raciocinar:

Imagens passam por um modelo de visão que extrai o conteúdo estruturado. Para uma nota fiscal: fornecedor, CNPJ, valor, data, itens (quando dá). Para foto de canteiro: descrição visual ("parede de bloco em construção, com mão-de-obra trabalhando no segundo pavimento"). Cada tipo de imagem tem um prompt e schema dedicados.

Áudios passam por transcrição automática e depois por uma camada de intent. Áudio típico do empreiteiro: "Mandei 250 reais pra Casa do Construtor agora, comprei cimento e areia." Vira: {tipo: pagamento, fornecedor: "Casa do Construtor", valor_centavos: 25000, descricao: "cimento e areia", confianca: 0.85}.

Texto vai direto pro LLM com o histórico recente da conversa como contexto.

O ponto importante: o agente nunca confia 100% em uma única extração. A confiança vai pra resposta de confirmação que ele manda de volta.

O loop de confirmação humana

O Zé nunca grava direto. Toda mudança no banco passa por uma confirmação. O fluxo padrão:

Usuário: [foto da nota]
Zé:      📎 NF guardada em "Reforma Casa".
         R$ 1.250,00 → Casa do Construtor (Materiais), pago hoje.
         Cadastro como pagamento? Responde sim ou não.
Usuário: sim
Zé:      Pronto, salvei ✅ R$ 1.250,00 marcado como pago.

A confirmação é assíncrona - o usuário pode demorar minutos ou horas pra responder. O agente mantém o contexto pendente associado ao número de telefone até a confirmação chegar (ou expirar).

Esse loop é o que torna o sistema seguro de usar em produção. Quando o modelo erra (sempre erra um pouco), o erro morre na confirmação. Sem dados ruins entrando no banco silenciosamente.

Modelagem do domínio

A construção tem um vocabulário próprio. As entidades centrais ficaram assim:

• Obra (projeto). Uma reforma, uma construção nova, uma manutenção. Tem nome, endereço, escopo, prazo.
• Pagamento. Valor, fornecedor, categoria (mão-de-obra, materiais, equipamentos, taxa), data, status (pago, agendado, atrasado), comprovante.
• Contrato. Empreiteiro/fornecedor, escopo, valor total, parcelas, datas.
• Diário de obra. Entradas datadas: o que foi feito hoje, quantas pessoas trabalharam, pendências.
• Documento. NFs, ARTs, plantas, fotos rotuladas.

O agente conhece esse modelo profundamente - ele faz parte do system prompt. Quando o usuário fala "comprei tinta no Leroy", o agente sabe que isso é Pagamento com categoria=Materiais e fornecedor=Leroy Merlin, mesmo que o usuário não estruture a frase.

Onde a IA NÃO faz nada

Algumas coisas a gente deliberadamente NÃO automatiza:

1. Aprovação de contratos. O modelo extrai os dados do contrato (PDF), preenche o cadastro, mas a aprovação é manual no app web. Risco contratual é alto demais.
2. Categorização de pagamento "duvidosa". Se a confiança da extração cai abaixo de um threshold, a gente NÃO chuta - pergunta. "Esse pagamento de R$ 800 é mão-de-obra ou materiais?" Custa uma resposta a mais, evita reclassificação depois.
3. Notificações automáticas pra fornecedores. Mexer com gente de fora é responsabilidade do humano dono da obra.

Vale a regra geral: o agente é ótimo em estruturar e encontrar, e nós o mantemos longe de decidir coisas que o erro custa caro.

Stack

• WhatsApp Business API via provedor (alternativas: WhatsApp Cloud API direto, Z-API, Twilio). Webhook recebe mensagens, send API responde.
• Modelo de linguagem: Anthropic Claude para o agente principal. Sonnet para extração estruturada complexa, Haiku para classificação simples e respostas rápidas.
• Visão: Claude com input multimodal - uma única chamada extrai texto da NF e classifica a foto.
• Áudio: Whisper (open-source via API) para transcrição. Depois passa por Haiku pra extrair intent.
• Banco: Postgres (Supabase). Schema com RLS por proprietário da obra. Funções security definer para mutations.
• Frontend: Next.js App Router + React. Painel web mostra o estado consolidado, fornece edição manual quando necessário.
• Infra: Vercel para o frontend e webhooks. Supabase para storage de mídia (fotos das NFs e do canteiro). Cron diário para lembretes e rollups.
• Observabilidade: cada extração loga o input, o output do modelo, o resultado da confirmação e quanto custou. Útil pra eval e pra entender em que casos o modelo erra mais.

O que aprendemos

Confirmação humana >>> "modo automático". Versão zero do Zeobra tentava ser autônomo: extrair e gravar direto. Os usuários começaram a desconfiar do sistema na semana 1. Botar o loop de confirmação no padrão devolveu a confiança e - surpresa - não atrapalhou o uso. As pessoas respondem "sim" em segundos.

Multimodalidade é onde o ROI está. A maior parte das ferramentas de gestão de obra ainda exige formulário. Quando o input é "manda foto + áudio + texto" e o agente faz o resto, a fricção desaparece. Esse é o salto.

Domínio antes do modelo. O system prompt do agente tem mais detalhes sobre construção (categorias, vocabulário de fornecedor, regras fiscais brasileiras) do que sobre como usar tools. Foi onde o ganho de qualidade veio.

WhatsApp como canal é viável e ainda subutilizado. No Brasil, ferramentas SaaS que ignoram o WhatsApp estão perdendo a maior parte do mercado SMB. O Zeobra mostra que dá pra construir uma experiência rica usando o canal que as pessoas já usam.

O que vem a seguir

A próxima fase é fechar o loop: relatórios consolidados por obra, integração com contadores (NFe e SPED), exportação pro ERP do cliente. O agente conversacional fica como entrada, mas as saídas estruturadas (relatório de obra fechada, prestação de contas, balanço) ganham forma.

Se sua empresa tem um problema parecido - uso pesado de WhatsApp, dados espalhados, fricção pra estruturar - vale uma conversa. Construímos esse tipo de sistema com a mesma engenharia que rodou Airbyte, dbt e BigQuery em times sênior, agora com o pedaço de agente no topo.