Arquitetura de um bom projeto

​

Uma peça para cada pergunta

​

Como as peças conversam

Lead manda "oi"
  └─ entra na coluna de entrada + departamento padrão (rodízio escolhe o responsável)
Agente responde (a cada mensagem, recebe nome, tags, etapa e propriedades marcadas)
  ├─ grava propriedades         → @properties_update_<slug>
  ├─ põe tags                   → @tag_add_<tag>
  └─ move no funil              → @kanban_move_<coluna>
        ├─ coluna com Transbordo → IA desligada + aviso ao responsável
        ├─ conversão da coluna   → evento ao Meta Ads (se o lead veio de anúncio)
        └─ fluxos "Movido no Kanban" e webhooks de Kanban
Resposta enviada = interação concluída
  └─ agenda follow-ups, transbordo por inatividade e webhooks por inatividade
     que batem nos filtros de coluna e tag
Lead fica em silêncio
  ├─ reengajamento: texto livre antes de a janela de 24h fechar (conexão oficial)
  ├─ follow-up: template depois do atraso
  └─ transbordo por inatividade: mensagem + move para a coluna de humano
Humano responde pelo chat
  └─ IA pausada pelos minutos da pausa humana

• A chave “Disparar automações” da coluna só vale quando uma pessoa move o lead pelo CRM. Quando o agente, a API ou um fluxo move, as automações não são reagendadas por ela. Veja Quando as automações disparam.
• Os filtros das automações são conferidos de novo na hora do envio. Um follow-up filtrado pela coluna “Triagem” não sai se o lead já mudou de coluna. É isso que torna a coluna o melhor filtro de automação.
• O agente vê as propriedades só com “enviar para a IA” ligado. A opção vem ligada por padrão e só se muda pelo template. Veja O que a Zatten injeta no contexto.

​

Padrões

​

O funil é o processo do cliente

• De 4 a 8 colunas. Cada coluna é uma etapa em que algo diferente acontece: outra automação, outro responsável, outra conversão. Etapa sem consequência não precisa de coluna.
• Uma coluna de transbordo com a chave Transbordo, para onde o agente, o transbordo por inatividade e a falha do modelo mandam o lead. Veja Resiliência.
• Saber quem move cada coluna. O agente move nas etapas que ele conclui (qualificou, agendou). A equipe move nas que acontecem fora do WhatsApp (compareceu, assinou, pagou). Nas colunas que a equipe move, ligue Disparar automações se houver follow-up daquela etapa.
• Decidir o fim do ciclo. Uma coluna final com Desativar IA deixa a IA muda para aquele lead até alguém religar. Se o lead pode voltar meses depois (novo agendamento, nova compra), deixe a IA ligada na coluna final e diga no prompt o que fazer em cada etapa, ou encerre o atendimento, que devolve o lead à entrada com a IA ligada.

​

Tags e propriedades com papel claro

• Tag é sim ou não; propriedade guarda um valor. “Convênio: Unimed” é propriedade. “Urgente” é tag.
• Vínculo certo. Contato para o que vale para sempre (cliente, ex-aluno, VIP). Conversa para o que vale neste atendimento (urgente, aguardando documento). Ao encerrar, o que é de conversa some.
• Tag de marco. A coluna mostra onde o lead está agora; ela não lembra por onde ele passou. Para contar depois quem chegou a uma etapa (“já agendou alguma vez”), use uma tag de vínculo contato posta junto com a mudança de coluna.
• Lista sempre que as respostas são conhecidas, com poucos valores e um “Outro”. O agente recebe as opções e não inventa variações.
• Escreva os valores aceitos no “Quando usar” da ação de propriedade. O modelo acerta de primeira. Veja Ações da Zatten.

​

Poucas tools, bem descritas

• Cada coluna, tag e propriedade que o agente mexe é uma tool a mais. Seis colunas, cinco tags e quatro propriedades viram quinze tools. Dê ao agente só as ações que ele precisa fazer.
• Até umas dez tools o modelo escolhe bem. Acima disso, ligue Filtrar tools. Veja Tools: visão geral.
• A regra de quando usar fica na tool, no “Quando usar no seu atendimento” ou na descrição. O prompt diz a ordem das etapas.

​

O prompt conduz, não armazena

• O prompt tem o fluxo, o tom e as proibições. Tabelas, políticas e FAQ vão para skills. Agenda, preço do dia e status de pedido vêm de tools.
• Não escreva dado de lead, data ou hora no prompt: chegam pelo contexto injetado. Veja Escrever um bom prompt.

​

O humano sempre tem por onde entrar

• Departamento padrão com membros recebendo leads, para todo lead ter responsável.
• Direcionar para departamento antes de Transferir para humano, quando há mais de uma equipe: o responsável escolhido é quem recebe o aviso.
• Pausa humana com valor gravado, do tamanho de uma intervenção da equipe.

​

Antipadrões

​

Checklist de arquitetura

• Cada coluna tem uma consequência (automação, transbordo, conversão ou responsável) e se sabe quem move o lead para ela.
• Existe uma coluna com Transbordo e um departamento padrão com membros recebendo leads.
• A coluna de entrada não tem Desativar IA.
• Tags com o vínculo certo; nenhuma tag faz o papel de etapa.
• Propriedades com respostas conhecidas estão em lista; as que o agente usa, com enviar para a IA.
• Até umas dez tools, cada uma com “quando usar” e “quando não usar”.
• Cada @ do prompt aponta para uma tool que existe.
• Follow-ups com template aprovado e filtro de coluna; transbordo por inatividade com colunas de origem.
• Buffer e pausa humana gravados com valor explícito.
• Retry, fallback e falha do agente configurados. Veja Resiliência.

​

Pelo MCP

​

Armadilhas

• Desenhar o funil pelo que a equipe gostaria de ver, não pelo que muda. Coluna que nada aciona só dá trabalho de mover.
• Renomear sem slug. Pelo template, um nome novo sem o slug cria outro item e o antigo fica de fora sem ser apagado.
• Excluir coluna ou tag que uma tool usa. A tool sai do agente junto. Revise o prompt.
• Mover em massa no CRM. Não aplica nenhuma chave da coluna nem conversões.

​

Para saber mais

• Funil (Kanban), Tags, Propriedades
• Quando as automações disparam
• Ações da Zatten
• Escrever um bom prompt
• Como usar os playbooks
• Anthropic, “Writing tools for agents”: https://www.anthropic.com/engineering/writing-tools-for-agents
• Anthropic, “Effective context engineering for AI agents”: https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
• Termos para buscar: “CRM pipeline design”, “lead stage vs tag”, “tool description best practices”, “context engineering”.