Pular para conteúdo

Runbook — Pausar / Reativar cliente

Três cenários diferentes com soluções diferentes:

  1. Pausar um lead específico (atendente humano assumiu a conversa) → label Chatwoot pausar-ia
  2. Pausar um agente inteiro (ex: fim de lançamento, modo perpétuo, bug crítico) → is_active=false + status em CLIENTES.md
  3. Pausar um cliente inteiro (todos os agentes desse cliente) → idem, em loop nos agentes

Cenário 1 — Pausar um lead específico (humano assumiu)

Quando usar: Tay/Junior viu a conversa no Chatwoot e quer responder manualmente. A IA precisa parar de responder pra não atropelar.

Via Chatwoot (recomendado — operador)

  1. Abrir a conversa em https://atendimento.gita.work/app/accounts/1/conversations/<id>
  2. Adicionar label pausar-ia na conversa (painel lateral direito)
  3. Responder manualmente — a IA respeita o bloqueio automaticamente

Via Redis (emergência — dev)

Se o label não estiver funcionando (checar crm_config.block_label do agente), dá pra setar direto:

# Engine faz isso automaticamente quando detecta mensagem "fromMe" via Uazapi,
# mas pode ser forçado via script ou re-check manual.

Como funciona por baixo

  • filters.ts checa redis.get(block:<agentId>:<remoteJid>) no início do pipeline
  • Quando TTL expira (padrão 6h, configurável via block_ia_ttl_minutes), IA volta automaticamente
  • Follow-up também respeita o block (follow-up.ts checa a mesma key antes de disparar)
  • O label pausar-ia no Chatwoot só serve pra operador humano sinalizar — quem bloqueia de fato é o Redis

Voltar a IA antes do TTL expirar

  • Remover o label pausar-ia no Chatwoot E esperar até a próxima mensagem do lead (Redis limpa ao próximo ciclo válido)
  • Ou deletar a key direto no Redis (requer acesso)

Cenário 2 — Pausar um agente inteiro

Quando usar: - Fim de lançamento (captação dormindo até próxima janela) - Bug crítico no prompt (evitar que a IA atenda mal enquanto corrige) - Troca de estratégia (agente vai ser refatorado)

Passos

  1. Desativar no banco (via admin ou SQL):
UPDATE ai_agents
SET is_active = false
WHERE slug = '<agente-slug>';
  1. Atualizar status em CLIENTES.md: mover linha do cliente pra seção "Histórico (pausado)" com nota:
| Cliente | 🔴 pausado | <data> | <agentes> | <canal> | <operador> | Pausado em <data> — motivo: <motivo> |

  1. Se for um router (ex: janaina-router), pausar também os agentes-alvo ou deixar eles "silenciosos" (sem webhook apontando). Opção: remover webhook da Uazapi temporariamente.

  2. Registrar em MEMORY.md do repo da Gita:

- [YYYY-MM-DD] Agente <slug> pausado — motivo: <motivo>. Voltar quando: <condição>.
  1. Atualizar CHANGELOG.md do cliente em ~/gita/agents/<cliente>/CHANGELOG.md.

O que acontece quando is_active=false

  • Webhooks chegam mas getAgentConfig(slug) retorna null (ver orchestrator.ts:87)
  • Log webhook.agent_not_found é registrado
  • Mensagem do lead não é respondida nem salva em messages
  • ⚠️ Cuidado: se for o router principal, o cliente inteiro fica sem resposta. Confirmar com operador antes.

Cenário 3 — Pausar um cliente inteiro

Raro mas acontece (pendência financeira, fim de contrato, crise interna). É o cenário 2 aplicado em todos os agentes daquele client_name.

UPDATE ai_agents
SET is_active = false
WHERE client_name = '<Nome do Cliente>';

Checklist completo:

  • is_active=false em todos os agentes do cliente
  • CLIENTES.md atualizado pra 🔴 pausado
  • MEMORY.md registra data e motivo
  • AGENT.md do cliente atualizado com status
  • CHANGELOG.md do cliente registra o evento
  • Webhook da Uazapi removido temporariamente (opcional — se quiser evitar logs de webhook.agent_not_found)
  • Ads ativos (Meta) pausados se estavam apontando pro WhatsApp desse cliente
  • Comunicação ao operador humano (Tay, Junior, cliente direto)

Cenário 4 — Reativar cliente pausado

Reverso do Cenário 3.

UPDATE ai_agents
SET is_active = true
WHERE client_name = '<Nome do Cliente>';

Antes de reativar, checar:

  • Prompt revisado (pode ter desatualizado)
  • Variáveis (modo_captacao, horários, links) atualizadas
  • Credenciais ainda válidas (provider_config.gemini_api_key, token Uazapi, Chatwoot)
  • Webhook Uazapi reapontado (se foi removido)
  • Rodar bateria de testes dry-run antes de liberar tráfego real
  • CLIENTES.md atualizado pra 🟢 produção ou 🟡 validação
  • MEMORY.md registra reativação
  • Comunicação ao operador humano

Cache do agente (atenção)

getAgentConfig tem TTL de 60 segundos (ver services/agent-config.ts). Após mudar is_active no banco, aguardar até 60s pra a mudança refletir em produção.

Pra forçar invalidação imediata: restart do engine no Easypanel (redeploy).

Comunicação ao operador humano

Sempre avisar a Tay (ou responsável do cliente) quando agente for pausado/reativado:

[pausado]
"Tay, acabei de pausar o agente <X> do cliente <Y>. Motivo: <motivo>. Estimativa pra voltar: <quando>. 
Enquanto isso, quem responder lá vai precisar responder manualmente — o label `pausar-ia` do Chatwoot não é necessário porque o agente já está off."

[reativado]
"Tay, reativei o agente <X> do cliente <Y>. Testei 3 cenários em dry-run antes, tudo passou. 
Pode voltar a operar normal — se quiser responder manualmente em algum lead, aplica o label `pausar-ia` nele."