"Guia completo: construindo um agente do zero"

O passo a passo de quem monta um agente profissional no builder — para o empresário, o gestor de tráfego e o programador.

Este é o mapa completo de como um agente do ScalaCRM funciona e a ordem certa de construí-lo. Não precisa ler tudo antes de começar: o fluxo guiado (menu Agentes IA → Criar agente) faz essas perguntas por você e monta a primeira versão sozinho. Este guia serve para entender o que cada peça faz — e para levar um agente de "funciona" para "profissional".

Como o agente funciona por dentro

Toda vez que um lead manda mensagem, o agente:

Espera alguns segundos (o "buffer") para o lead terminar de digitar mensagens picadas;
Confere onde pode atuar — a caixa de entrada, a etapa do funil, o público (só anúncio, condições de UTM);
Monta o contexto: quem ele é, o que sabe do seu negócio, o histórico da conversa, o perfil que já guardou daquele lead;
Escreve a resposta — e, quando a situação pede, age: move o lead no funil, avisa alguém, agenda, registra dados;
Passa por camadas de proteção antes de enviar: regras invioláveis (bloqueio por texto) e, se ligado, o supervisor de qualidade.

Tudo que você configura no builder alimenta um desses cinco momentos. A construção abaixo segue a ordem que dá menos retrabalho.

Passo 1 — Objetivo e identidade (aba Identidade)

Defina UMA missão: qualificar, vender, agendar ou atender. Agente com duas missões faz as duas mal — para processos diferentes, crie dois agentes e conecte-os (um transfere para o outro).

Dê um nome que ele usa com o cliente (nunca o nome de uma pessoa real da equipe) e escolha o tom. As Instruções extras são as regras de comportamento que não cabem em outro lugar: "use o nome da pessoa uma única vez", "no máximo uma pergunta por mensagem", "nunca oriente procedimento — quem orienta é a advogada".

Passo 2 — Conhecimento (aba Conhecimento)

O agente só sabe o que você ensinar — ele é proibido de inventar. O conhecimento tem seis lugares, cada um com um papel:

Sobre a empresa / O que vocês vendem: o pano de fundo. Quem são, onde atendem, o que oferecem.
Catálogo de produtos: se os preços vivem no catálogo do CRM, ligue o catálogo — o agente cota a partir dele e atualiza sozinho quando você muda um preço.
Blocos oficiais: textos que saem palavra por palavra — tabela de preços, condições de pagamento, aviso legal. O agente é instruído a copiar o bloco inteiro, sem mudar um número. Use para tudo que não pode sofrer "resumo criativo".
Perguntas frequentes: pares de pergunta e resposta (até 60). Use as palavras que o CLIENTE usa na pergunta.
Critérios internos de decisão: regras que o agente USA para decidir mas nunca fala — "caso com menos de X não compensa", "na dúvida, qualifique", prazos, faixas de viabilidade. Ele lê isso como análise silenciosa: decide com base nos critérios e é proibido de revelá-los.
Diálogos de exemplo: uma conversa curta no formato Lead: / Você: vale mais que dez instruções de tom — o agente imita o ritmo dos exemplos.
Fontes de conhecimento (base de conhecimento): documentos, textos e páginas que ele consulta por busca — listas longas (municípios atendidos, convênios), manuais, políticas. ⚠️ Se as suas instruções mandam "consultar a base", a base precisa existir — o card Saúde do agente avisa quando ela está vazia.

Passo 3 — Comportamento: roteiro e playbooks (aba Comportamento)

O Roteiro de atendimento é o caminho feliz: os passos, na ordem, da saudação ao fechamento. Um passo por linha.
Os Playbooks são as situações que fogem do caminho: "lead cita desconto", "lead quer falar com humano", "lead já é cliente". Cada playbook tem um gatilho (quando usar) e passos na ordem — dizer algo, perguntar e aguardar, usar uma ferramenta, desviar se uma condição acontecer. A ferramenta é escolhida da lista (nunca escrita em texto), então não há como o agente prometer uma ação que não existe.

Regra prática: se você se pega escrevendo "quando o cliente fizer X, faça Y" nas instruções, isso é um playbook.

Ainda nesta aba: caixas de entrada onde ele atua, etapas do funil permitidas, público (só anúncio / condições), ritmo de resposta, resposta em áudio e follow-up automático.

Passo 4 — Ferramentas (aba Ferramentas)

Ferramentas são as AÇÕES do agente no CRM: mover lead no funil, notificar alguém, agendar, registrar venda, preencher campos, enviar template. Três regras de ouro:

A descrição decide o uso. O agente lê a descrição para saber QUANDO chamar — escreva no imperativo, com o critério do seu negócio: "Mova o lead para Qualificado quando ele tiver respondido as 5 perguntas e confirmado interesse".
O destino é seu, não dele. A etapa do funil, o número de WhatsApp, o usuário notificado — tudo sai da configuração; o agente só decide o momento.
Encadeie o que sempre anda junto. "Executar outra ferramenta em seguida" faz a segunda ação rodar automaticamente (mover para Qualificado → avisar a equipe). Por configuração, não tem como ele esquecer a segunda.

Para campos de escolha (ex.: "Tipo de caso" com opções fixas), o agente recebe as opções como lista fechada — ele não consegue inventar uma categoria nova.

Passo 5 — Regras invioláveis (aba Avançado → Qualidade e proteção)

Aqui mora a diferença mais importante do builder:

Instrução ("nunca prometa resultado") o agente lê — vai nas Instruções extras ou nos critérios internos.
Regra inviolável é um termo proibido conferido por código na resposta pronta ("garanto que", "carência zero", "desconto de"). Se o termo aparecer, o agente reescreve; se insistir, o envio é bloqueado e a equipe avisada.

Escrever uma instrução no campo de regra inviolável cria uma regra que nunca dispara — o editor avisa quando isso acontece e oferece mover o texto para o lugar certo. Use o testador do card: cole uma resposta de exemplo e veja qual regra dispararia.

Passo 6 — Testar antes de ativar

Playground: converse você mesmo com o agente. As ações aparecem como etiquetas ("o lead seria movido...") — nada executa de verdade.
Personas: rode uma simulação com um cliente difícil (apressado, cético, cheio de perguntas, pronto para fechar) e receba um relatório com nota.
Cada teste do fluxo guiado vira um caso de avaliação: depois de qualquer mudança no agente, rode a avaliação e compare as notas — é o seu teste de regressão.

Passo 7 — Saúde do agente e ativação

O card Saúde do agente (no topo do editor e na tela de ativação) confere a configuração e avisa o que vai quebrar: ferramenta apontando para etapa que não existe mais, texto citando uma ferramenta que não está na lista, bloco oficial citado e inexistente, base de conhecimento citada e vazia, regra inviolável escrita como instrução. Ele avisa, nunca bloqueia — mas um item "grave" significa exatamente isso: aquela parte vai falhar com um lead real.

Ativou? O agente atende nas caixas vinculadas. A partir daí, acompanhe pelos números no topo do editor (respostas, conversas, ações, handoffs) e pelo relatório Performance da IA em Relatórios.

Para o programador

Nada disso impede os caminhos técnicos: o modo avançado aceita o system prompt inteiro escrito por você (as regras invioláveis, blocos oficiais, playbooks e a base de conhecimento continuam valendo por fora do prompt), a integração n8n entrega cada mensagem num webhook seu, e a API v1 cobre contatos, cards, conversas e vendas. O builder e os caminhos técnicos não competem — o que o builder dá de graça é a infraestrutura em volta: janela de 24h, anti-loop, guardrails, medição por resposta e o pré-flight.