Variáveis customizadas
Ótimo conteúdo adicional! Vou enriquecer o artigo com essas informações, especialmente os casos de uso e os alertas importantes:
Variáveis
O que são as Variáveis?
As Variáveis são dados coletados pelo Agente durante a conversa com o usuário que ficam armazenados e podem ser reutilizados em qualquer parte da configuração do Agente. Pense nelas como "gavetas com etiquetas" — o Agente coleta uma informação, guarda com um nome específico, e você pode chamar esse dado sempre que precisar ao longo do fluxo.
Uma vez criadas, as variáveis ficam disponíveis para uso em condições de elegibilidade de estágios, coleta de dados dentro de estágios, chamadas de API e personalização de instruções e prompts.
Para que servem?
Durante uma conversa, o usuário fornece uma sequência de informações — nome, e-mail, intenção, preferências. Com as variáveis, você organiza a captura desses dados de forma estruturada, sem precisar instruir explicitamente o Agente a buscá-los em cada estágio. Após a captura, elas ainda servem como base para tomadas de decisão na seleção e acionamento de estágios conversacionais.
Alguns exemplos práticos:
Coletar o nome do usuário na introdução e usá-lo para personalizar as respostas ao longo de toda a conversa
Coletar a intenção do usuário (ex.: comprar ou vender) e usar essa variável como condição para acionar o estágio correto
Coletar o e-mail e enviá-lo como parâmetro em uma chamada de API
Armazenar a nota do atendimento ao final da conversa para análise posterior
Guardar dados como destino de viagem, cidade, tipo de imóvel ou status de assinatura para uso em condições e ações específicas
Exemplo prático: imagine um Agente de uma agência de viagens. Para dar sequência ao atendimento, é necessário capturar destino, total de dias e experiências desejadas pelo usuário. Configurando variáveis para cada um desses dados e referenciando-as nos estágios, o Agente extrai todas as informações de forma estruturada — tornando o atendimento muito mais eficiente e controlado.
Tipos de variável
Ao criar uma variável, você define o tipo de dado que ela vai armazenar:
string — texto livre (nome, e-mail, cidade, mensagem, etc.)
number — valor numérico (quantidade, nota, idade, etc.)
boolean — verdadeiro ou falso (sim/não, ativo/inativo, etc.)
Como criar uma Variável
Passo 1 — Acesse a aba Avançado
No painel do Agente, clique em "Avançado" no topo do menu lateral.
Passo 2 — Clique em "Variáveis"
No menu lateral, clique em "Variáveis" para abrir o painel de configuração.
Passo 3 — Clique em "+"
No canto superior direito do painel "Configurar variáveis", clique no botão "+" para criar uma nova variável.
Passo 4 — Defina o nome da variável
No campo "Variável", escreva o nome seguindo o padrão data.nome_da_variavel. Use nomes descritivos, sem espaços e preferencialmente em letras minúsculas.
Exemplos: data.nome, data.email, data.cidade, data.destino, data.intenção_compra
Passo 5 — Escolha o tipo de dado
No campo "Tipo", selecione o tipo de dado que a variável vai armazenar: string, number ou boolean.
Passo 6 — Configure a extração automática (opcional)
A opção "Extração automática de valor (beta)" permite que o Agente identifique e preencha a variável automaticamente com base no conteúdo da conversa, sem perguntar diretamente ao usuário. Deixe ativada para a maioria dos casos ou desative se preferir controlar o preenchimento exclusivamente via API ou coleta explícita.
Passo 7 — Escreva a descrição
No campo "Descrição", explique o que essa variável representa e como o Agente deve solicitá-la ao usuário. Esse campo é essencial: é ele que orienta o Agente sobre o que perguntar e como preencher a variável corretamente.
Escreva como se estivesse dando uma instrução direta ao Agente. Seja específico sobre o formato esperado quando necessário.
Exemplo de boa descrição:
"Explique que antes de iniciar, precisa do e-mail que o usuário utiliza na Zaia e deseja atendimento. Sempre preencha com todas as letras minúsculas."
Passo 8 — Configure a visibilidade (opcional)
O toggle "Não exibir variável" faz com que essa variável não apareça nas informações da conversa. Útil para variáveis internas ou de controle que não precisam ser visíveis no histórico de atendimento.
Passo 9 — Clique em "Salvar alterações"
Clique em "Salvar alterações" para criar a variável. Ela passará a aparecer na lista de variáveis disponíveis e estará pronta para uso em qualquer parte da configuração do Agente.
Como usar as variáveis
Após criadas, as variáveis ficam disponíveis automaticamente em todos os lugares onde podem ser referenciadas:
Nas condições de estágio — ao adicionar dados obrigatórios para elegibilidade, selecione a variável no dropdown e defina o valor esperado para que o estágio seja ativado.
Na coleta de dados dentro de estágios — ao configurar "Dados que o Agente deve coletar", selecione a variável que o Agente deve solicitar ao usuário antes de seguir as instruções.
Nas instruções e prompts — referencie variáveis digitando @data, @system ou @custom nos campos de instrução. Os valores reais das variáveis serão substituídos automaticamente no texto antes de serem enviados ao modelo de linguagem.
Em chamadas de API — envie variáveis coletadas como parâmetros em chamadas de API, permitindo buscar ou enviar dados em sistemas externos com base no que foi coletado na conversa.
Importante: ao referenciar uma variável em uma instrução ou condição, se ela ainda não existir, o texto aparecerá em vermelho na interface. Clique nele para criar ou corrigir a variável.
Casos de uso
Estágio inicial — sem variáveis na condição
No estágio inicial da conversa, é essencial que a condição não tenha nenhuma variável como dado obrigatório. Como nenhuma informação foi coletada ainda, qualquer variável exigida tornaria o estágio inelegível desde o início — e o fluxo nunca começaria.
Configure as variáveis que precisa coletar no bloco de dados do estágio. O Agente concentrará seus esforços na coleta dessas informações e, somente após concluí-la, executará as instruções e ações configuradas.
Referenciando variáveis nas instruções
Você pode usar variáveis diretamente no texto das instruções para personalizar as respostas. Por exemplo, usar @data.destino em uma instrução faz com que o Agente substitua automaticamente esse marcador pelo valor real coletado antes de gerar a resposta.
Estágio de encerramento — garantindo que todo o fluxo foi percorrido
Nos estágios finais, muitas vezes você não precisa coletar novos dados — mas quer garantir que o Agente só chegue ali depois de ter percorrido todo o fluxo. Uma estratégia eficaz é adicionar todas as variáveis já coletadas ao longo da conversa como dados obrigatórios na condição do estágio de encerramento. Isso aumenta a segurança de que o objetivo só será executado após todos os estágios anteriores terem sido completados.
Condições com variáveis para decisões críticas
Usar variáveis nas condições de elegibilidade permite criar regras de negócio precisas e seguras. Por exemplo: um estágio de recomendação de bebidas alcoólicas só será ativado se data.idade tiver sido coletada e seu valor for maior ou igual a 18. Isso garante que certas ações só aconteçam quando as condições corretas forem verdadeiras.
Atualizado