Estágios
O que são os Estágios?
Os Estágios são a estrutura central de configuração do comportamento do seu Agente IA. É através deles que você ensina ao Agente como executar processos, tarefas e fluxos de atendimento de forma controlada e previsível — definindo exatamente o que deve acontecer, em que momento, e em que ordem.
Dominar os estágios é o que permite criar agentes altamente personalizados, com total controle sobre cada etapa da conversa com o usuário.
Dois tipos de estágio
Comportamento Geral
O Comportamento do Agente (configurado na aba Básico > Cargo) funciona como um estágio global: tudo que você definir ali será levado em consideração em todas as interações, independentemente do estágio específico que estiver ativo. Pense nele como as diretrizes gerais de conduta do seu funcionário virtual.
Para agentes simples — que apenas tiram dúvidas, compartilham links ou consultam o Cérebro — o comportamento geral pode ser suficiente para configurar tudo o que você precisa.
Estágios Específicos
São etapas ou tarefas que o Agente vai executar em um momento específico da conversa, seguindo um roteiro definido por você. Cada estágio tem sua própria condição de ativação, suas próprias ações e suas próprias instruções de resposta.
Atenção: Evite criar conflitos entre o que está escrito no comportamento geral e as instruções dos estágios específicos. Contradições podem gerar respostas inconsistentes.
Como os Estágios funcionam
A interface de configuração de um estágio segue uma ordem lógica que é exatamente a mesma ordem em que as coisas acontecem quando o Agente gera uma resposta. Entender essa sequência é fundamental.
Bloco 1 — Condições
As condições dizem ao Agente quando ele deve selecionar aquele estágio. Você define o contexto da conversa que deve estar presente para que esse estágio seja ativado.
Exemplos de condições:
"Se for o início da conversa"
"Se o usuário deseja agendar uma reunião"
"Se o usuário informou que quer vender um imóvel"
Dentro das condições, você também pode usar dados obrigatórios — variáveis que precisam estar preenchidas para que o estágio possa ser escolhido. Ao clicar em "Adicionar dado", você seleciona uma variável, um operador (igual a, contém, etc.) e o valor esperado.
Atenção crítica: Nunca coloque como dado obrigatório de uma condição uma variável que só será coletada dentro daquele mesmo estágio. O Agente precisaria escolher o estágio para coletar a variável, mas não pode escolhê-lo sem a variável. Isso cria um impasse e o estágio nunca será selecionado.
Importante: Condição é condição, não instrução. Não escreva coisas como "Se for início da conversa, faça tal coisa" no campo de condição — o Agente não vai considerar essa instrução ali.
Bloco 2 — Ações
As ações são executadas após o estágio ser selecionado e antes das instruções finais. A seção de Ações é dividida em duas partes:
Parte 1 — Dados que o Agente deve coletar
Aqui você define quais variáveis o Agente deve perguntar ao usuário antes de avançar. Selecione a variável desejada no dropdown e clique em "Adicionar". Você pode adicionar quantas variáveis precisar, e elas serão coletadas na ordem em que aparecem.
Exemplo: em um agente de vendas de imóveis, você pode configurar para coletar data.tipo_imovel e data.cidade antes de qualquer outra ação.
Parte 2 — Ação que o Agente deve efetuar (aparece após salvar o estágio pela primeira vez)
Após coletar os dados, o Agente pode executar uma ação automatizada. As opções disponíveis são:
Chamar uma API — integra com sistemas externos, podendo usar as variáveis já coletadas na chamada
Enviar arquivos (beta)
Conectar calendário — para agendamentos
Passar para um humano — transfere o atendimento
Importante: O bloco de ações só aparece completo depois que o estágio for salvo pela primeira vez. Ao criar um novo estágio, preencha o nome, a condição e uma instrução básica, clique em "Treinar Agente IA" e, depois, volte ao estágio — todas as opções estarão disponíveis.
Atenção: Não tente usar em uma chamada de API uma variável que ainda não foi coletada neste mesmo estágio. Colete primeiro, acione a API depois.
Bloco 3 — Instruções finais para responder o usuário
Este é o bloco onde você define o que o Agente deve dizer ao usuário após concluir todas as etapas anteriores. As instruções finais acontecem somente após os passos 1 e 2 serem concluídos.
Você pode referenciar variáveis coletadas diretamente na instrução usando @data, @system ou @custom.
Exemplo de instrução final:
"Apresente ao usuário as opções de @data.tipo_imovel disponíveis na cidade de @data.cidade e pergunte qual melhor se encaixa no seu perfil."
Importante: Instruções finais não servem para acionar ações como "chame uma API" ou "passe para um humano" — essas funções ficam no bloco de Ações, não aqui.
Bloco 4 — Timeout do estágio (opcional)
Permite desativar o estágio temporariamente após ele ser executado, evitando repetições de comportamento ou controlando a experiência do usuário.
Como criar um novo Estágio
Passo 1 — Acesse a aba Avançado
No painel do Agente, clique em "Avançado" no topo do menu lateral.
Passo 2 — Clique em "Adicionar estágio específico"
No menu lateral, na seção Estágios, clique em "Adicionar estágio específico +".
Passo 3 — Preencha os campos mínimos e salve
Para que todas as opções de configuração fiquem disponíveis, você precisa preencher ao menos:
Nome do estágio — apenas para identificação interna
Condição geral — descreva quando esse estágio deve ser ativado
Instrução final — escreva uma instrução básica de resposta
Em seguida, clique em "Treinar Agente IA". Após salvar, o bloco completo de Ações ficará visível e disponível para configuração.
Passo 4 — Configure as Ações e finalize
Com o estágio salvo, volte a ele e configure os dados a coletar, as ações a executar e refine a instrução final conforme o seu fluxo de atendimento.
Boas práticas
Menos é mais. Quanto mais direto e específico você for nas condições e instruções, menor a chance do Agente se confundir. Instruções ambíguas ou condições parecidas demais podem fazer o Agente escolher o estágio errado.
A ordem importa. O Agente sempre segue a sequência: condição → coleta de dados → ação → instrução final. Nunca pule etapas nem coloque informações no bloco errado.
Use variáveis para criar condições precisas. Você pode combinar condição textual com dados obrigatórios para tornar a elegibilidade de um estágio muito mais específica. Por exemplo: "Se for início da conversa" + data.intenção igual a vender.
Use o Alfred para diagnosticar problemas. No chat de teste ou no histórico de conversas, clique na varinha mágica para pedir ao Alfred uma explicação sobre por que determinado estágio foi ou não foi escolhido. Ele fará um diagnóstico completo e apontará o que pode ser ajustado.
Sempre presuma que o problema está na configuração. Se o Agente não está seguindo o fluxo esperado, revise primeiro as condições e instruções dos estágios antes de buscar qualquer outra causa.
FAQ — Problemas comuns com Estágios
Seu Agente não está seguindo o processo configurado? Reinicia o fluxo do nada? Não respeita as regras? As respostas abaixo cobrem os problemas mais frequentes na configuração de estágios.
Como fazer para um estágio ser acionado?
O estágio é acionado quando a condição que você definiu nele ocorre durante a conversa. Por exemplo, se a condição for "Se é a primeira mensagem da conversa", aquele estágio será selecionado exatamente nesse momento.
Um ponto muito importante: tenha sempre pelo menos um estágio sem nenhuma variável nos dados obrigatórios da condição. Se todos os seus estágios exigirem variáveis para serem elegíveis, nenhum deles poderá ser selecionado no início da conversa — afinal, nenhuma variável foi coletada ainda. O resultado é que o Agente não encontrará nenhum estágio válido e o fluxo não iniciará corretamente.
O que acontece após o estágio ser selecionado?
Existem três níveis de comportamento que você pode configurar em um estágio:
Básico — o estágio é acionado e o Agente segue diretamente as instruções finais.
Intermediário — o estágio é acionado, o Agente coleta os dados configurados no bloco de variáveis e, só depois, segue as instruções finais.
Avançado — o estágio é acionado, o Agente coleta os dados, executa uma ação (como chamar uma API ou conectar um calendário) e, por fim, segue as instruções finais.
Por que meu Agente escolhe o estágio errado?
Provavelmente você configurou duas condições que se sobrepõem ou conflitam, fazendo com que a IA fique em dúvida sobre qual estágio selecionar.
Exemplo clássico de conflito:
Estágio A: "Se é o início da conversa"
Estágio B: "Se o usuário disse bom dia"
Se a primeira mensagem do usuário for "Oi, bom dia", as duas condições são verdadeiras ao mesmo tempo. A IA vai selecionar um dos estágios, mas não necessariamente o que você gostaria.
Como evitar: seja o mais específico possível em cada condição e evite sobreposições. Qualquer detalhe importa. Use o Alfred (varinha mágica no chat de teste) para inspecionar por que determinado estágio foi escolhido e o que pode ser ajustado.
Por que meu Agente não respeita as regras que defini?
As causas mais comuns são:
Conflito com o comportamento geral. Se uma instrução no campo de Comportamento do Agente (Básico > Cargo) contradiz uma instrução dentro de um estágio, o Agente pode ficar confuso sobre qual seguir. Revise os dois e garanta que sejam complementares, não contraditórios.
Instrução no lugar errado. Lembre-se: condições só definem quando o estágio é ativado, não o que fazer. Ações como chamar APIs ou transferir para humano pertencem ao bloco de Ações, não às instruções finais. Se você colocou uma instrução no bloco errado, ela será ignorada.
Instrução ambígua ou genérica demais. O Agente é muito obediente, mas justamente por isso se perde com facilidade quando as instruções não são claras. Seja direto, específico e evite deixar margem para interpretação.
Por que meu Agente reinicia o fluxo do nada?
Isso geralmente acontece quando o estágio de início da conversa não tem uma condição suficientemente específica para distingui-lo de outros estágios, ou quando não há um estágio configurado para lidar com os momentos intermediários da conversa. O Agente, sem encontrar um estágio elegível para o contexto atual, pode acabar voltando ao único que reconhece como válido.
Revise se você tem estágios cobrindo todos os momentos relevantes do fluxo e se as condições de cada um são distintas o suficiente para não se sobrepor.
Posso usar uma variável na condição de um estágio se ela ainda vai ser coletada nesse mesmo estágio?
Não. A condição é avaliada antes de o estágio ser selecionado. Se a variável só existe após o estágio ser acionado, ela nunca estará disponível no momento da avaliação — criando um impasse onde o estágio nunca pode ser escolhido.
A regra é: só coloque uma variável como dado obrigatório na condição se ela já foi coletada em um estágio anterior.
O bloco de Ações não está aparecendo na configuração do estágio. Por quê?
Esse bloco completo só fica visível depois que o estágio é salvo pela primeira vez. Ao criar um novo estágio, preencha o nome, a condição e uma instrução básica qualquer, clique em "Treinar Agente IA" e volte ao estágio. A partir daí, todas as opções de configuração — incluindo coleta de variáveis, chamada de API, calendário e transferência para humano — estarão disponíveis.
Atualizado