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:
Combine {{today}} e {{conversation-created-at}} para lógica temporal:
Use {{conversation-priority}} para workflows:
Use {{conversation-total-messages}} para insights:
Envie contexto completo para sistemas externos:

Diferenças entre Tipos de Variáveis

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:

Em Estágios

  1. Acesse ConfiguraçõesEstágios
  2. Configure objetivos e instruções com variáveis
  3. Exemplo no objetivo:

Em Ferramentas HTTP

1

Configurar Requisição

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

Exemplo no Body

3

Exemplo em Headers

Em Follow-ups

  1. Acesse FerramentasFollow Up
  2. Configure o objetivo com variáveis
  3. Exemplo:

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

Agendamento de Consultas

Objetivo: Coletar nome, tipo de consulta e data preferidaInstruções:

Suporte Técnico


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).