Agente Janaina Ortiga — Documentação Operacional¶

Tudo que foi implementado, decidido e como operar o ecossistema de agentes da Janaina Ortiga.

Produção desde: 18/04/2026 Responsável operacional: Taynara Negrão (Tay)

Arquitetura¶

WhatsApp Janaina (1 número, Uazapi)
           │
           ▼
/webhook/whatsapp/janaina-router
           │
           ├── janaina-suporte   → lead menciona que é aluna
           ├── janaina-conversao → lead veio do checkout, dúvida de pagamento
           └── janaina-captacao  → qualquer outro opener (default)

Agente	Persona	Papel
`janaina-router`	—	Fantoche, só classifica e delega. Não chama Gemini.
`janaina-captacao`	Isis (time da Jana)	Qualifica interesse, convida pro evento/lançamento
`janaina-conversao`	Isis (time da Jana)	Destrava pagamento, envia link correto, fecha venda
`janaina-suporte`	Isis (time da Jana)	Redireciona aluna para link de suporte da Ana

Produto¶

Formação Lojista de Sucesso (LS) - Público: lojistas de moda feminina, 33-52 anos, faturamento até R$50k/mês - Formato: 12+ módulos gravados + ao vivo mensais + mentorias + planilhas - Acesso: 1 ano | Garantia: 7 dias incondicional | Plataforma: Hotmart

Variáveis dinâmicas (editáveis via admin)¶

Todas as variáveis ficam em ai_agents.variables (JSONB). Nunca sobrescrever o JSON inteiro — sempre GET → merge → PATCH. Ver docs/editar-variaveis-agente.md.

janaina-conversao (principal)¶

Chave	Descrição
`condicao_especial_titulo`	Título da condição vigente (ex: "12x no cartão, à vista, boleto ou 2 cartões")
`valor_vista`	Preço à vista (ex: "R$ 2.897 à vista")
`parcelamento_cartao`	Condição parcelada cartão (ex: "12x de R$ 299,62")
`parcelamento_boleto`	Descrição boleto (ex: "Até 6x no boleto pela TMB Educação")
`bonus_extras`	Bônus da oferta vigente
`validade_oferta`	Prazo/contexto da oferta
`link_checkout_cartao`	Link Hotmart cartão padrão
`link_checkout_parcelamento_inteligente`	Link Hotmart parcelamento inteligente
`link_checkout_2cartoes`	Link Hotmart 2 cartões
`link_boleto_3x`	Link TMB 3x
`link_boleto_4x`	Link TMB 4x
`link_boleto_6x`	Link TMB 6x
`link_pagina_vendas`	Página de vendas (quando lead quer conhecer antes)
`link_suporte_alunas`	Link suporte da Ana (redireciona alunas)

janaina-captacao¶

Chave	Descrição
`modo_captacao`	`lancamento_ativo` ou `perpetuo` — altera comportamento do prompt
`nome_evento`	Nome do evento/desafio em lançamento
`data_inicio_evento` / `data_fim_evento`	Datas do evento
`link_grupo_evento`	Link do grupo WhatsApp do evento
`link_inscricao_evento`	Link de inscrição (quando pago/cadastro)
`link_checkout_cartao`	Checkout da Formação
`valor_formacao`	Preço atual
`valor_parcelado_cartao`	Condição parcelada

Boleto: apenas até 6x¶

Decisão de 19/04/2026: boleto parcelado liberado somente em 3x, 4x e 6x. Opções de 10x e 12x foram removidas do prompt e não devem ser reofertadas.

Follow-up automático (janaina-conversao)¶

Follow-up ativado com 3 estágios. A Isis lê o histórico da conversa e adapta a mensagem ao contexto real (não presume onde o lead parou).

Estágio	Intervalo	Comportamento
1	2 horas	Retoma exatamente onde parou. Trata objeção aberta ou pergunta se concluiu.
2	1 dia	Reforça valor conectado à dor mencionada. Menciona condição atual de forma natural.
3	3 dias	Encerramento gentil. Deixa porta aberta. Sem pressão. Sem pergunta final.

Como funciona internamente: - Loop a cada 60s verifica leads com follow_up_stage < total_intervalos - Gemini recebe histórico da conversa + instrução do estágio - Referência de tempo: follow_up_last_at (se já fez follow) ou updated_at (última interação)

Quando para: - Lead responde → follow_up_stage reseta para 0 (orchestrator.ts linha 177) - Lead confirma compra → follow_up_stage = -1, status = converted (tool registrar_compra) - Lead completa todos os 3 estágios → não há mais estágios, loop ignora

Lock distribuído: só 1 instância processa follow-up por vez (Redis SET NX EX 55s).

Tool: registrar_compra¶

Quando a lojista confirmar que comprou, a Isis chama registrar_compra. Isso: - Seta follow_up_stage = -1 → lead sai do loop de follow-up - Seta status = converted - Loga lead.converted em agent_logs

A Isis pergunta após enviar o link: "Conseguiu finalizar a inscrição?" Se confirmar → registrar_compra → "Que ótimo! Bem-vinda à Formação ✨"

Pausa manual (label pausar-ia no Chatwoot)¶

A Tay pode pausar a IA em qualquer conversa adicionando a label pausar-ia no Chatwoot.

Como pausar: 1. Abrir a conversa em https://atendimento.gita.work/app/accounts/3/inbox/23 2. Adicionar label pausar-ia na conversa 3. IA para de responder imediatamente (próxima mensagem recebida é ignorada)

Como retomar: 1. Remover a label pausar-ia 2. IA volta a responder na próxima mensagem

Como funciona internamente: antes de processar qualquer mensagem, o engine consulta o Chatwoot pelo número do contato e verifica se alguma conversa tem essa label. Se tiver, bloqueia silenciosamente (sem log de erro, sem resposta enviada).

Config Chatwoot nos agentes:

{
  "api_url": "https://atendimento.gita.work",
  "account_id": "3",
  "block_label": "pausar-ia"
}

Confirmação de compra (sem pedir dados antes do link)¶

Decisão de 19/04/2026: a Isis não pede mais nome completo e e-mail antes de enviar o link. A etapa de coleta de dados foi removida pois dificultava a venda.

Fluxo atual: 1. Entende como a lojista quer pagar 2. Envia o link direto 3. Pergunta: "Conseguiu finalizar a inscrição?"

Troubleshooting comum¶

IA não responde¶

Verificar se agente está ativo (is_active = true) no admin
Verificar se existe label pausar-ia no Chatwoot
Verificar logs em agent_logs — filtrar por remote_jid do número
Verificar se é horário comercial (se business_hours_enabled = true)

Variável aparece literal (`{{chave}}`) na conversa¶

Significa que a chave não existe em variables do agente
Log prompt.missing_variable (nível warn) em agent_logs
Solução: adicionar a chave via admin (GET → merge → PATCH)

Follow-up não dispara¶

Verificar follow_up_enabled = true no agente
Verificar follow_up_stage do lead (se for -1, está desabilitado)
Verificar follow_up_last_at e updated_at do lead — intervalo pode não ter passado ainda
Lock Redis: se engine travou, lock pode estar preso. TTL é 55s — aguardar e tentar novamente

Follow-up dispara para quem já comprou¶

Significa que registrar_compra não foi chamada
Verificar logs da conversa se a tool foi executada
Pode setar manualmente no Supabase: follow_up_stage = -1, status = converted

Lead respondeu mas follow-up continua¶

Verificar se updated_at foi atualizado no leads (trigger de banco)
Verificar se a mensagem passou pelo orchestrator (pode ter sido bloqueada por filtro)

Operação do dia a dia (Tay faz sozinha via admin)¶

Tarefa	Como fazer
Trocar links de checkout	Admin → agente → variables → editar `link_checkout_*`
Mudar condição especial	Admin → variables → `condicao_especial_titulo`, `valor_vista`, `parcelamento_cartao`, `validade_oferta`
Abrir/fechar lançamento	Admin → janaina-captacao → variables → `modo_captacao`: `lancamento_ativo` ou `perpetuo`
Pausar IA de um lead	Chatwoot → conversa → label `pausar-ia`
Ver leads e status	Admin → leads → filtrar por agente
Ver logs de uma conversa	Admin → logs → filtrar por `remote_jid`
Desativar agente inteiro	Admin → agente → toggle `is_active`

Chama dev quando: - Bug no pipeline (mensagens não chegando, erros nos logs) - Mudança estrutural de prompt (além de variáveis) - Nova forma de pagamento ou novo fluxo - Problema técnico com Uazapi ou Chatwoot

Histórico de decisões¶

Data	Decisão
18/04/2026	Go-live em produção com 4 agentes
19/04/2026	Distributed lock no follow-up (Redis) — evita duplicatas em múltiplas instâncias
19/04/2026	Follow-up ativado no janaina-conversao: 3 estágios (2h, 1d, 3d), modo AI
19/04/2026	Tool `registrar_compra` — encerra follow-up quando lojista confirma compra + aplica label `pausar-ia` no Chatwoot
19/04/2026	Removida obrigatoriedade de pedir nome/e-mail antes de enviar link
19/04/2026	Boleto limitado a no máximo 6x (removidas opções 10x e 12x)
19/04/2026	Filtro `pausar-ia` ativado via Chatwoot nos 4 agentes
20/04/2026	Fix: busca do contato no Chatwoot agora tenta JID completo + número (contatos sem `phone_number` cadastrado)
20/04/2026	TTL do cache CRM reduzido para 30s (antes 5min) — pausa reflete rápido
20/04/2026	Follow-up passou a verificar label `pausar-ia` antes de disparar
20/04/2026	Histórico compartilhado por tenant: agentes do mesmo cluster veem mensagens uns dos outros (texto apenas, não function calls)
20/04/2026	Reclassificação: match explícito em outro agente troca o sticky (antes: uma vez no agente, preso até reset)
20/04/2026	Sticky passou a ordenar por `updated_at` e toca timestamp em toda interação
20/04/2026	`reportar` integrado com ClickUp Chat (canal #Comercial) + link direto pra conversa no Chatwoot
20/04/2026	Regex de captação ampliada: cobre "evento gratuito", "próxima aula", "como funciona a formação"
20/04/2026	Webhook secundário configurado na Uazapi: Chatwoot e IA convivem na mesma instância
20/04/2026	Modo `dry_run` no engine para testes automatizados — requer secret + prefixo `test_` no JID