Skip to main content

Sistema de Variáveis no Super Agentes

O sistema de variáveis permite armazenar e utilizar informações dinâmicas durante as conversas, funcionando como “memória” do agente para personalizar respostas e manter contexto.

Antes de começar

Para usar variáveis, você precisa:
Variáveis são específicas de cada conversa e são automaticamente removidas após 30 dias de inatividade. Não armazene informações sensíveis ou críticas apenas em variáveis.

Pré-requisitos

Antes de configurar variáveis, certifique-se de que:
  1. Seu agente está ativo
  2. Você tem permissões de edição
  3. Compreende a sintaxe: {{nome_da_variavel}}
  4. Você criou variáveis em ferramentas de variáveis.

Configurando Variáveis

Acessando o Módulo

  1. Acesse a barra lateral do Super Agentes
  2. Clique na aba Agentes
  3. Selecione o agente desejado
  4. Vá para ConfiguraçõesFerramentas
  5. Clique em Variáveis

Criando Variáveis Personalizadas

1

Adicionar Ferramenta de Variáveis

  • Clique em + Adicionar Ferramenta
  • Selecione Variáveis na lista
  • Clique em Conectar variáveis
2

Configurar Variáveis

  • Nome da variável: Identificador único (ex: nome_cliente)
  • Descrição: Explique quando e como será utilizada
    • Seja específico sobre o contexto de uso
    • Inclua exemplos de valores esperados
3

Templates Disponíveis

  • nome - Nome completo do usuário
  • email - Endereço de email do usuário
  • Use o botão Preencher com template para aplicar
  • Clique em + Adicionar variável
  • Defina nome e descrição personalizados
  • Repita para cada variável necessária

Tipos de Variáveis

Variáveis Customizadas

  • Criadas por você
  • Específicas do seu negócio
  • Exemplos: {{produto_interesse}}, {{data_agendamento}}

Variáveis Globais

  • Capturadas automaticamente
  • Baseadas no canal de comunicação
  • Exemplos: {{user-name}}, {{user-email}}

Variáveis de Runtime

  • Geradas pelo sistema
  • Atualizadas dinamicamente
  • Exemplos: {{today}}, {{conversation-id}}

Variáveis Globais por Canal

Dashboard

  • {{user-name}} - Nome do usuário logado
  • {{user-email}} - E-mail do usuário logado, caso tenha conta no Super Agentes
  • Capturadas automaticamente da sessão

WhatsApp

  • {{user-name}} - Nome do contato
  • {{user-phone-number}} - Número de telefone
  • Extraídas do perfil do WhatsApp

Variáveis de Sistema

  • {{today}} - Data/hora atual
  • {{conversation-id}} - ID da conversa
  • {{conversation-status}} - Status da conversa
  • {{conversation-channel}} - Canal de comunicação

Variáveis de Runtime (Sistema)

As variáveis de runtime são geradas automaticamente pelo sistema durante a execução das conversas. Elas fornecem informações contextuais em tempo real e não precisam ser configuradas manualmente.

Lista Completa de Variáveis de Runtime

Data e Tempo

{{today}}
  • Data e hora atual no formato ISO
  • Formato: YYYY-mm-ddTHH:MM:SS
  • Atualizada a cada execução
  • Exemplo: 2024-01-15T14:30:25

Identificação da Conversa

{{conversation-id}}
  • ID único da conversa
  • Gerado automaticamente pelo sistema
  • Útil para integrações e logs
  • Exemplo: clr8x9y2k0001abc123def456

Status da Conversa

{{conversation-status}}
  • Status atual da conversa
  • Valores possíveis: OPEN, RESOLVED, PENDING
  • Atualizado conforme ações do usuário
  • Útil para workflows condicionais

Prioridade

{{conversation-priority}}
  • Nível de prioridade da conversa
  • Valores: LOW, MEDIUM, HIGH, URGENT
  • Pode ser definida manualmente ou por regras
  • Influencia ordem de atendimento

Canal de Comunicação

{{conversation-channel}}
  • Canal onde a conversa está acontecendo
  • Valores: whatsapp, dashboard, website, api
  • Útil para personalizar respostas por canal
  • Permite lógica condicional

Métricas da Conversa

{{conversation-total-messages}}
  • Contagem total de mensagens na conversa
  • Inclui mensagens do usuário e do agente
  • Útil para análise de engajamento
  • Exemplo: 15

Data de Criação

{{conversation-created-at}}
  • Data e hora de início da conversa
  • Formato ISO: YYYY-mm-ddTHH:MM:SS
  • Não muda durante a conversa
  • Exemplo: 2024-01-15T09:15:30

Casos de Uso das Variáveis de Runtime

Use {{conversation-channel}} para adaptar o comportamento:
{% if conversation-channel == "whatsapp" %}
Olá! Vi que você está entrando em contato pelo WhatsApp 📱
{% elif conversation-channel == "dashboard" %}
Bem-vindo ao nosso portal de atendimento!
{% endif %}
Combine {{today}} e {{conversation-created-at}} para lógica temporal:
Prompt do sistema:
"Esta conversa foi iniciada em {{conversation-created-at}}.
Agora são {{today}}. Se a conversa tem mais de 24 horas,
pergunte se o usuário ainda precisa de ajuda."
Use {{conversation-priority}} para workflows:
Ferramentas HTTP - Headers:
"X-Priority": "{{conversation-priority}}"
"X-Conversation-ID": "{{conversation-id}}"

Lógica no sistema externo:
- HIGH/URGENT: Notificar supervisor
- MEDIUM: Fila padrão
- LOW: Resposta automatizada
Use {{conversation-total-messages}} para insights:
Follow-up personalizado:
"Olá! Notei que já trocamos {{conversation-total-messages}} mensagens.
{% if conversation-total-messages > 10 %}
Que tal agendar uma conversa por telefone para resolver mais rapidamente?
{% endif %}"
Envie contexto completo para sistemas externos:
{
  "conversation_metadata": {
    "id": "{{conversation-id}}",
    "channel": "{{conversation-channel}}",
    "status": "{{conversation-status}}",
    "priority": "{{conversation-priority}}",
    "created_at": "{{conversation-created-at}}",
    "message_count": "{{conversation-total-messages}}",
    "last_activity": "{{today}}"
  }
}

Diferenças entre Tipos de Variáveis

TipoConfiguraçãoPersistênciaAtualizaçãoExemplos
RuntimeAutomáticaPor conversaDinâmica{{today}}, {{conversation-id}}
GlobalAutomáticaPor conversaNo início{{user-name}}, {{user-email}}
CustomizadaManualPor conversaQuando coletada{{nome_cliente}}, {{produto_interesse}}

Limitações das Variáveis de Runtime

  • Não são editáveis: Valores são gerados automaticamente pelo sistema
  • Específicas por conversa: Cada conversa tem seus próprios valores
  • Dependem do contexto: Algumas podem estar vazias dependendo do canal
  • Formato fixo: Datas seguem sempre o padrão ISO

Monitoramento de Runtime Variables

Para visualizar os valores atuais das variáveis de runtime:
  1. Logs da Conversa: Acesse uma conversa específica nos logs
  2. Debug do Agente: Use o preview para ver valores em tempo real
  3. Ferramentas HTTP: Configure endpoints de teste para capturar os valores
  4. Perfil da Conversa: Visualize metadados na interface de logs

Boas Práticas com Runtime Variables

Recomendado:
  • Use {{conversation-id}} para rastreamento em integrações
  • Combine {{today}} com lógica temporal nos prompts
  • Utilize {{conversation-channel}} para personalizar experiência
  • Aproveite {{conversation-status}} para workflows condicionais
Evite:
  • Tentar modificar valores de runtime variables
  • Assumir que todas estarão sempre preenchidas
  • Usar em cálculos complexos de data (use sistema externo)
  • Depender exclusivamente delas para lógica crítica

Usando Variáveis

Em Prompts do Sistema

  1. Acesse ConfiguraçõesPrompt
  2. Use a sintaxe {{variavel}} no texto
  3. Exemplo:
Você é um assistente de vendas da empresa XYZ. 
Sempre se dirija ao cliente pelo nome: {{user-name}}.
Se o cliente demonstrar interesse em {{produto_interesse}}, 
forneça informações detalhadas sobre este produto.

Em Estágios

  1. Acesse ConfiguraçõesEstágios
  2. Configure objetivos e instruções com variáveis
  3. Exemplo no objetivo:
Coletar o nome completo do cliente e armazenar em {{nome_cliente}} 
para personalização das próximas interações.

Em Ferramentas HTTP

1

Configurar Requisição

  • Acesse FerramentasHTTP
  • Use variáveis no Body, Headers ou Parameters
2

Exemplo no Body

{
  "customer_name": "{{nome_cliente}}",
  "customer_email": "{{user-email}}",
  "product_interest": "{{produto_interesse}}",
  "conversation_id": "{{conversation-id}}"
}
3

Exemplo em Headers

Authorization: Bearer {{api_token}}
X-Customer-Phone: {{user-phone-number}}

Em Follow-ups

  1. Acesse FerramentasFollow Up
  2. Configure o objetivo com variáveis
  3. Exemplo:
Verificar se {{nome_cliente}} efetuou o pagamento da parcela 
referente ao produto {{produto_interesse}} adquirido em {{data_compra}}.

Monitoramento e Status

Visualizando Variáveis Ativas

Em Conversa

Acesse uma conversa específica para ver as variáveis coletadas

Logs do Agente

Visualize o histórico de uso das variáveis nos logs

Debug Mode

Use o preview do agente para testar as substituições

Perfil do Usuário

Veja as variáveis globais capturadas por conversa

Exemplos Práticos

E-commerce

- {{nome_cliente}} - Nome do cliente
- {{produto_carrinho}} - Produto no carrinho  
- {{valor_total}} - Valor total da compra
Você é um assistente de vendas. Sempre use o nome {{nome_cliente}} 
para se dirigir ao cliente. Se ele perguntar sobre o carrinho, 
informe que tem {{produto_carrinho}} no valor de {{valor_total}}.
Olá {{nome_cliente}}! Notamos que você deixou {{produto_carrinho}} 
no seu carrinho. Que tal finalizar sua compra? O valor continua 
sendo {{valor_total}}.

Agendamento de Consultas

- {{nome_paciente}} - Nome do paciente
- {{tipo_consulta}} - Tipo de consulta desejada
- {{data_preferencia}} - Data preferida pelo paciente
Objetivo: Coletar nome, tipo de consulta e data preferidaInstruções:
1. Pergunte: 'Qual seu nome completo?' → armazene em {{nome_paciente}}
2. Pergunte: 'Que tipo de consulta precisa?' → armazene em {{tipo_consulta}}
3. Pergunte: 'Qual data prefere?' → armazene em {{data_preferencia}}
{
  "patient_name": "{{nome_paciente}}",
  "consultation_type": "{{tipo_consulta}}",
  "preferred_date": "{{data_preferencia}}",
  "phone": "{{user-phone-number}}"
}

Suporte Técnico

- {{problema_relatado}} - Descrição do problema
- {{numero_protocolo}} - Número do protocolo gerado
- {{tecnico_responsavel}} - Técnico designado
Você é um assistente de suporte técnico. Sempre se apresente como:
'Olá {{user-name}}, sou seu assistente de suporte.'
Quando um problema for relatado, armazene em {{problema_relatado}} 
e gere um protocolo em {{numero_protocolo}}.
Olá {{user-name}}, este é um follow-up do protocolo {{numero_protocolo}}. 
O problema '{{problema_relatado}}' foi resolvido? O técnico {{tecnico_responsavel}} 
está disponível para mais esclarecimentos.

Boas Práticas

1. Nomenclatura

  • Use nomes descritivos: {{nome_cliente}} ao invés de {{n}}
  • Use snake_case: {{data_nascimento}} ao invés de {{dataNascimento}}
  • Evite caracteres especiais e espaços
  • Mantenha consistência entre variáveis relacionadas

2. Descrições e Documentação

  • Sempre forneça descrições detalhadas das variáveis
  • Explique quando e como a variável será utilizada
  • Inclua exemplos de valores esperados
  • Mantenha documentação interna atualizada

3. Segurança e Privacidade

  • Não armazene informações sensíveis em variáveis
  • Cuidado com dados pessoais (LGPD/GDPR)
  • Use variáveis apenas para informações necessárias
  • Monitore o acesso e uso das variáveis

4. Performance e Organização

  • Evite criar muitas variáveis desnecessárias
  • Reutilize variáveis globais quando possível
  • Agrupe variáveis relacionadas com prefixos
  • Teste sempre antes de colocar em produção

Solução de Problemas

  1. Verifique a sintaxe: {{nome_variavel}}
  2. Confirme se a variável foi configurada na ferramenta
  3. Verifique se o agente está coletando o valor corretamente
  4. Teste com uma conversa nova no preview
  1. Confirme se o valor foi armazenado durante a conversa
  2. Verifique se a variável global está disponível no canal
  3. Teste com uma conversa nova
  4. Verifique os logs da conversa para debug
  1. Verifique se as variáveis estão sendo substituídas antes da requisição
  2. Confirme se os valores são válidos para o endpoint
  3. Teste a requisição manualmente com valores fixos
  4. Valide o formato JSON se aplicável
  1. Salve a configuração da ferramenta de variáveis
  2. Recarregue a página de configurações
  3. Verifique se a ferramenta está ativa
  4. Confirme se você tem permissões adequadas

Perguntas Frequentes

Não há limite específico, mas recomendamos até 20 variáveis por agente para manter a performance otimizada.
Não. Cada conversa tem seu próprio conjunto de variáveis. Variáveis globais são recapturadas automaticamente.
Acesse os logs da conversa ou use o preview do agente para ver as substituições em tempo real.
Atualmente não há funcionalidade de import/export. Configure manualmente ou use templates disponíveis.
Sim, mas variáveis globais específicas dependem do canal (ex: user-phone-number só no WhatsApp).
I