Pular para conteúdo

Ecossistema de agentes WhatsApp da Gita — estado atual + roadmap

Documento consolidado sobre o que o sistema de agentes IA da Gita faz hoje, como ele é construído, onde estão os limites conhecidos e o que vem pela frente. Atualizado em 2026-04-21 após a bateria v15 (13 cenários end-to-end, 13/13 ✅).

1. Visão geral

Três clientes em produção/validação, todos no mesmo engine multi-tenant (~/projetos/gita-agents/):

Cliente (client_name) Status Agentes Canal Produto principal
Gita Agentes 🟢 produção + 🟡 validação 9 (router + 8 agentes) Uazapi "Lojista Assistant" (556191502969) Implementação de IA · Tráfego pago · Empresa no Digital · Vagas
Janaina Ortiga 🟢 produção desde 2026-04-18 4 (router + 3 agentes) Uazapi número próprio Formação LS (modo perpétuo)
Denise Ramos 🟡 validação 1 (fluxo único) Uazapi Protocolo 8/28 · Detox 7d · Consulta individual

Diagrama lógico (cluster Gita Agentes):

gita-router
  ├─ regex "tráfego|anúncios|meta ads..."       → gita-trafego-captacao ──(fit=trafego_qualificado)──→ gita-trafego-proposta
  ├─ regex "criar infoproduto|estruturar..."    → gita-end-captacao     ──(fit=end_qualificado)────→ gita-end-proposta
  ├─ regex "quero trabalhar|vaga|currículo"     → gita-vagas (terminal)
  └─ default                                    → gita-captacao         ──(fit=gita_agents)───────→ gita-conversao
                                                                        └(fit=empresa_digital)────→ gita-downsell

Transições cross-produto são bloqueadas pela função productOf() no router — exceto pra gita-vagas, que tem prioridade absoluta (isVagasPriority). Isso protege lead de END que menciona "Meta Ads" de ser reclassificado pra tráfego, mas permite candidato no meio de qualquer fluxo ser redirecionado pra vagas.

Cluster Janaina (análogo, simplificado):

janaina-router
  ├─ regex "sou aluna|acesso..."         → janaina-suporte
  ├─ regex "checkout|inscrição|pagar..." → janaina-conversao
  └─ default                             → janaina-captacao (modo perpétuo)

2. Catálogo de agentes (13 agentes)

Slug Tenant Papel Modelo Prompt local Notas
gita-router Gita Agentes Roteador (sem IA) — — 5 regex + sticky + FIT_ROUTING + cross-product blocking
gita-captacao Gita Agentes Captação IA Gemini 2.5 Flash ~/gita/agents/gita-agentes/whatsapp/captacao.prompt.md SPIN 4 perguntas, decide fit=gita_agents ou empresa_digital
gita-conversao Gita Agentes Conversão IA qualificada Gemini conversao.prompt.md Agenda reunião com Tay · consultar_disponibilidade + agendar_reuniao
gita-downsell Gita Agentes Downsell END Gemini downsell.prompt.md Apresenta Empresa no Digital · oferecer_empresa_no_digital
gita-trafego-captacao Gita Agentes Captação tráfego Gemini ~/gita/agents/gita-trafego/whatsapp/captacao.prompt.md Few-shots baseados em 6 conversas reais da base Janaina
gita-trafego-proposta Gita Agentes Proposta tráfego Gemini proposta.prompt.md Agenda call com Tay, sem valores no chat
gita-end-captacao Gita Agentes Captação END Gemini ~/gita/agents/gita-end/whatsapp/captacao.prompt.md 3 segmentos (varejo / infoproduto / servico_profissional), pergunta adaptada por segmento
gita-end-proposta Gita Agentes Proposta END Gemini proposta.prompt.md Método Segunda Sede adaptado · 3 níveis (Formação/Acompanhamento/Execução) sem preço no chat
gita-vagas Gita Agentes Terminal — candidatos Gemini ~/gita/agents/gita-vagas/whatsapp/vagas.prompt.md Entrega URL vagas.grupogita.com.br, escala desvio comercial via reportar
janaina-router Janaina Ortiga Roteador — — 3-way (captacao/conversao/suporte)
janaina-captacao Janaina Ortiga Captação LS Gemini ~/gita/agents/janaina-ortiga/whatsapp/ Modo perpétuo (modo_captacao=perpetuo), troca pra lancamento_ativo em janelas
janaina-conversao Janaina Ortiga Destravar pagamento Gemini (idem) Recupera checkout, envia link · registrar_compra
janaina-suporte Janaina Ortiga Aluna da formação Gemini (idem) Redireciona pra /suporte-alunas-ls
denise-vendas Denise Ramos Vendas + agendamento Gemini ~/gita/agents/denise/whatsapp/ Agente único, sem router. 3 produtos em catálogo

9 + 4 = 13 agentes ativos no engine. Mais a Denise fecha 13 de fato (1 agente + 0 router pro cluster dela).

3. Tools disponíveis (8 handlers)

Todas em packages/engine/src/services/tools.ts. Gemini chama via function calling; ativadas por agente na tabela tools.

Tool Propósito Usada por Side-effects
qualificar_lead Salva progressivamente qualified_data (nicho, faturamento, fit, segmento…) com merge GET→PATCH Todas as captações e conversões leads.qualified_data + leads.name + leads.status='qualified' quando tem fit
consultar_disponibilidade Lista eventos no Google Calendar em um range (data_inicio/data_fim) gita-conversao, gita-end-proposta, gita-trafego-proposta GET Calendar via OAuth2
agendar Cria evento Google Calendar simples (título, data, descrição) Legado / agentes simples POST Calendar + gera Meet
agendar_reuniao Cria evento com contexto de qualificação estruturado + link Meet + convite pro lead gita-conversao, gita-end-proposta, gita-trafego-proposta POST Calendar + envia convite + loga agendamento.created
oferecer_empresa_no_digital Retorna descrição adaptada do END pelo segmento (varejo/infoproduto/serviço) gita-downsell, gita-end-captacao Apenas leitura de dados de produto
registrar_compra Marca lead como converted, pausa follow-up em todos agentes do tenant, adiciona label pausar-ia no Chatwoot janaina-conversao, denise-vendas 3 writes: leads, follow_up_stage=-1 cross-agent, Chatwoot label
reportar Posta notificação formatada no ClickUp Chat #Comercial com link Chatwoot Todos os agentes POST ClickUp 8cgqa6x-12233 + log reportar.sent
handleHttpTool Handler genérico pra tools HTTP custom por agente (config JSON em tools.handler_config) Futuro — nenhum agente usa hoje HTTP arbitrário (whitelist)

Motivos de reportar já padronizados: solicitou_humano, nome_conhecido, horario_indisponivel, negociacao_especial, segmento_fora_do_escopo, candidato_quer_servicos, insistencia_curriculo, indicacao_interna, material_pre_call, avaliacao_perfil.

4. Features de infra reutilizáveis (12 capabilities)

Todas documentadas em detalhe em features-reutilizaveis.md. Resumo:

# Feature Status Ativação
1 Pausa por atendente humano (block_ia Redis TTL 6h) ✅ em uso block_ia_enabled: true no agente
2 Pausa via label pausar-ia no Chatwoot ✅ em uso crm_config com block_label
3 Follow-up multi-estágio com IA (gera msg lendo histórico) ✅ Janaina (2h/1d/3d) follow_up_enabled + intervals + prompts
4 Tool registrar_compra (cross-agent pause + label) ✅ Janaina, Denise INSERT em tools + instrução no prompt
5 Tool reportar → ClickUp #Comercial ✅ todos os clusters notification_clickup_channel_id
6 Router regex + sticky + FIT_ROUTING + cross-product blocking + isVagasPriority ✅ Gita + Janaina Automático
7 Histórico compartilhado por tenant (agent switching preserva contexto) ✅ todos clusters Automático
8 Múltiplos webhooks Uazapi (Chatwoot + IA coexistindo) ✅ Janaina, Gita action: add no Uazapi
9 Dry-run testing (X-Gita-Dry-Run: 1 + X-Test-Secret + JID test_*) ✅ validado na v15 Env GITA_TEST_SECRET
10 Distributed lock no follow-up (Redis SET NX EX 55) ✅ automático Nenhuma
11 Endpoint seed-lead (automação externa dispara msg inicial + histórico salvo) ⚠️ existe, não documentado em produção POST /webhook/seed-lead/:slug
12 Endpoint chatwoot/inbound-message (captura mensagens durante pausa) ⚠️ endpoint existe, Automation Chatwoot não configurada Automation no Chatwoot + webhook

Bônus não catalogado: cache de agente (TTL 60s) em agent-config.ts — edição no admin reflete em até 1 min.

5. Integrações externas

Sistema Para quê Em uso por Arquivo
Uazapi Envio + recepção WhatsApp + download mídia 3 tenants (3 instâncias separadas) integrations/whatsapp/uazapi.ts
Evolution API Canal WhatsApp alternativo Nenhum cliente ativo (suporte legado) integrations/whatsapp/evolution.ts
Instagram Graph API Canal Instagram (envio) ⚠️ sender existe, webhook não integrado pipeline/sender.ts
Unipile Canal LinkedIn ⚠️ sender existe, não em produção pipeline/sender.ts
Chatwoot CRM — leitura de label pausar-ia, registrar_compra escreve label 3 tenants (account 1 = atendimento.gita.work) integrations/crm/chatwoot.ts
Kommo CRM alternativo Nenhum cliente ativo integrations/crm/kommo.ts
ClickUp Notificação de escalação via reportar Cluster Gita (channel 8cgqa6x-12233) integrations/clickup/chat.ts
Google Calendar Agendamento com Tay (OAuth2) gita-conversao, gita-end-proposta, gita-trafego-proposta integrations/google/calendar.ts
Gemini 2.5 (Flash/Pro) LLM principal — function calling, geração 13 agentes integrations/gemini/client.ts
OpenAI Whisper Transcrição de áudio (whisper-1, pt) Todos agentes (fallback Gemini se falhar) integrations/openai/transcribe.ts
Hotmart Webhooks de compra / histórico Janaina (em migração — ver backlog) server/automations/hotmart-*
Redis Debounce + cache CRM + block_ia + distributed lock Automático integrations/redis.ts
Supabase Banco (ai_agents, messages, leads, tools, agent_logs) Único banco de dados integrations/supabase/client.ts

6. Gaps e limitações conhecidas

Reconhecidos em docs/código (não são "bugs" abertos — são trade-offs ou pendências).

  1. client_name string-based: tenants são identificados por string livre. Typo ("Janaina" vs "Janaina Ortiga") criaria tenant fantasma. Não tem RLS no Supabase. Doc: arquitetura.md:183.
  2. Admin sem view por cliente: lista flat de agentes. Difícil navegar em 13+ agentes. Doc: arquitetura.md:186.
  3. Chatwoot inbound-message inativo em produção: endpoint existe (POST /webhook/chatwoot/inbound-message) e salva histórico durante pausa, mas Automation no Chatwoot ainda não configurada nos 3 clientes. Doc: features-reutilizaveis.md:373-403.
  4. Duplicação de balão pós-tool: Gemini às vezes gera texto + tool call + texto de novo após o tool result. Sender envia ambos → lead vê 2 balões iguais. Prompts mitigam ("string vazia após tool result"), mas bug estrutural permanece. Visto em B2/C1 da bateria v15.
  5. Function calls filtradas no histórico cross-agent: pra evitar erro "tool não declarada" no Gemini, só text vira contexto. Trade-off: agente novo não sabe que o anterior executou registrar_compra — só vê o que foi falado. Doc: features-reutilizaveis.md:213.
  6. updateLeadQualification vulnerável a concurrent writes: GET→merge→PATCH sem lock otimista. Em rajada de mensagens (2+ chegando no mesmo debounce), última sobrescreve. Mitigado pelo debounce de 5-8s, mas não resolvido.
  7. Hotmart scope impreciso: documentação não confirma quais clientes usam. Backfill de 24m em andamento (memory: hotmart_webhooks_supabase), scheduled-reports ainda usando conta antiga.
  8. Tools duplicadas: agendar (simples) vs agendar_reuniao (com contexto) coexistem. Só Gita usa a segunda. Vale unificar.
  9. Sem dashboard de métricas: leads/dia por agente, taxa de conversão por estágio, distribuição de fit, tools executadas — tudo vive em agent_logs. Admin mostra listagem, não aggregates.
  10. Whitelist + horário comercial pode travar: se business_hours for reativado, números fora da whitelist são silenciosamente filtrados. Pode confundir atendimento.
  11. Nome não capturado em alguns fluxos (visto na v15): o prompt pede nome mas Gemini ocasionalmente pula. O agente já tem regras de tolerância ("se após 2 tentativas segue sem"), mas falta validação estrutural.
  12. Engine cache de 60s: edição rápida de prompt demora até 1 min pra valer. Pra desenvolvimento é ruim — não tem flag "force reload".
  13. Deploy manual do engine: auto-deploy do Easypanel falhou durante a v15 (30+ min sem subir após push). Sem feedback de erro claro.

7. Roadmap de melhorias priorizadas

🟢 Quick wins (baixo esforço · alto impacto)

# O que Impacto Esforço Por que
QW-1 Ativar Automation no Chatwoot pra disparar chatwoot/inbound-message nos 3 tenants Alto ⏱️ 30min Elimina "IA cega" depois de pausa — problema recorrente em atendimento híbrido
QW-2 Documentar endpoint seed-lead no runbook-novo-cliente.md + 1 exemplo curl Médio ⏱️ 20min Feature subutilizada; destravaria migrações com lista de leads
QW-3 Admin: agrupamento visual por client_name na listagem de agentes Alto ⏱️ 1-2h Melhora navegação com 13 agentes; já existem dados, é só UI
QW-4 Unificar tools agendar e agendar_reuniao (deprecate a simples) Baixo ⏱️ 30min Limpeza — evita confusão de prompt writer
QW-5 Flag force_reload no admin pra pular cache de 60s de agente Médio ⏱️ 1h Velocidade de iteração em prompt
QW-6 Dashboard mínimo no admin: últimas 24h — leads novos por agente, reportar executados, conversões Alto ⏱️ 2-3h Visibilidade operacional diária
QW-7 Script NPM npm run test:v15 que reroda os 13 cenários + valida asserts Alto ⏱️ 1h Virar CI/regression test — pega bug antes de deploy

Ordem sugerida: QW-1 (antes que perca mais contexto em pausa real) → QW-7 (proteger regressões) → QW-3 → QW-6 → QW-2, QW-4, QW-5.

🟡 Robustez estrutural (médio esforço)

# O que Impacto Esforço Por que
RS-1 Tabela clients com FK, migrar client_name → client_id Alto ⏱️ 1-2 dias Resolve tenants fantasma · abre caminho pra RLS · onboarding de cliente vira INSERT estruturado
RS-2 Coalescer no sender.ts — se 2 balões com texto quase idêntico no mesmo turno, envia só 1 Alto ⏱️ 4h Bug #4 resolvido sem depender de prompt
RS-3 RLS no Supabase com JWT por tenant Alto ⏱️ 2 dias Defesa em profundidade — bug de código não vaza dados
RS-4 Lock otimista em updateLeadQualification (usar If-Match com updated_at) Médio ⏱️ 3h Bug #6 resolvido em concorrência
RS-5 Alerta no ClickUp se auto-deploy do Easypanel não subir em 5min após push Médio ⏱️ 1h Bug #13 — visibilidade
RS-6 Testes automáticos no CI (subset dry-run em cada PR) Alto ⏱️ 4h Regressão de prompts detectada antes de main
RS-7 Retry com backoff em agendar_reuniao e postChannelMessage Médio ⏱️ 2h Falhas transientes de Calendar/ClickUp hoje viram erro duro
RS-8 Incluir function calls (de forma segura) no histórico cross-agent Baixo ⏱️ 4h Trade-off #5 — agente novo sabe que houve compra

🔴 Novas capacidades (alto esforço · alto valor)

# O que Impacto Esforço Por que
NC-1 Captação via Instagram DM (receiver + sender já existem parcial) Alto ⏱️ 3-5 dias Expande canal — hoje lead só via WhatsApp. Gita tem audiência IG relevante
NC-2 Agente pós-venda / nurture que reativa lead silencioso de 15-30d Alto ⏱️ 2-3 dias Recupera 5-15% de leads perdidos (benchmarks); pipeline reaproveita follow-up
NC-3 Dashboard de conversão por estágio de funil (captação→qualificado→agendado→comprou) Alto ⏱️ 3-4 dias Fecha o loop analítico; permite A/B de prompt com dado de outcome
NC-4 A/B testing de prompts (50/50 split, 2 variantes do mesmo agente) Alto ⏱️ 3 dias Ciência em vez de achismo na iteração de prompt
NC-5 Checkout Hotmart embutido (tool gerar_checkout que cria link personalizado) Alto ⏱️ 2-3 dias Fecha venda dentro da conversa · reduz fricção do agente de conversão
NC-6 Voz do agente via TTS (opcional por agente — envia áudio em vez de texto) Médio ⏱️ 3-4 dias Diferencial competitivo · mais humano em cenários específicos
NC-7 Multi-idioma (detecção automática + prompt-per-idioma) Baixo ⏱️ 1-2 dias Casos pontuais (lead gringo) — baixa prioridade no momento
NC-8 LinkedIn via Unipile pra B2B outbound Médio ⏱️ 3-5 dias Captação ativa B2B · abre novo canal comercial
NC-9 Agente de Recuperação de Carrinho (integrado ao Hotmart checkout abandonado) Alto ⏱️ 2 dias Janaina + futuros produtos digitais da Gita
NC-10 Integrar outras agendas (Outlook, Calendly) além do Google Calendar Baixo ⏱️ 2 dias Flexibilidade pra novos clientes

8. Próximos passos sequenciados (proposta de sprint)

Semana 1 — Operação estável e visível

  1. QW-1 Ativar Automation Chatwoot inbound-message (30min)
  2. QW-7 Script npm run test:v15 como regressão (1h)
  3. RS-5 Alerta de deploy travado (1h)
  4. QW-3 Admin agrupado por cliente (2h)
  5. QW-6 Dashboard diário mínimo (3h)

Total estimado: 7-8h. Resultado: operação visível e protegida contra regressões.

Semana 2 — Robustez e escala

  1. RS-2 Coalescer duplicação no sender (4h) — fix estrutural do bug mais visível
  2. RS-6 Testes no CI (4h)
  3. RS-4 Lock otimista em qualificar_lead (3h)
  4. NC-2 Agente nurture / pós-venda (2-3 dias) — começa o dev

Total: 2-3 dias efetivos. Resultado: engine mais seguro + recuperação de leads perdidos.

Semana 3-4 — Nova capacidade (escolher 1)

Opções (decidir com Junior + Tay):

  • NC-1 Instagram DM — expande canal primário
  • NC-3 Dashboard de conversão — fecha loop analítico
  • NC-5 Checkout embutido + NC-9 recuperação carrinho — fecha loop de venda

Cada uma: 3-5 dias. Recomendo NC-3 primeiro: sem dado de outcome, qualquer outra iteração é cega.

Médio prazo (mês 2-3)

  • RS-1 Tabela clients (destrava RLS e templates de cliente novo)
  • RS-3 RLS Supabase
  • NC-4 A/B testing
  • NC-5 + NC-9 (checkout + carrinho)

Longo prazo (mês 4+)

  • NC-6 TTS
  • NC-8 LinkedIn B2B
  • NC-7 Multi-idioma
  • NC-10 Outlook/Calendly

Apêndice — validação recente

Bateria v15 (2026-04-21) validou 13 cenários end-to-end no cluster Gita Agentes:

  • 7 happy paths (IA qualificado, IA downsell, tráfego, END varejo/infoproduto/serviço, vagas)
  • 5 bordas/cross-agent (captação → vagas via isVagasPriority, Meta Ads não reclassifica END, vagas → reportar desvio, horário fora janela, opt-out cordial)
  • 1 mega-lead (end-captação → vagas → reportar em 5 turnos)

Resultado: 13/13 ✅ após 4 rodadas de fixes (router regex, placeholder guard, anti-loop, REGRA DURA pra fit, anti-duplicação). Commits:

  • 25a4d42 (gita-agents): regex do router aceita "criar meu/minha infoproduto/curso/mentoria"
  • 0689971 (grupo-gita): 5 prompts (gita-captacao, gita-end-captacao, gita-end-proposta, gita-trafego-captacao, gita-vagas)

Script de regressão: scripts/test-chat.ts com JIDs test_v15_*. Ver runbook-testes-dry-run.md pra padrão.