> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superagentes.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Sistema de Variáveis

> Aprenda a usar variáveis para personalizar conversas e armazenar informações dinâmicas em seus agentes.

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

<Card title="Antes de começar" icon="circle-info">
  Para usar variáveis, você precisa:

  * [Ter um agente criado](/agentes/criar-agente)
  * [Configurar ferramentas básicas](/agentes/ferramentas)
  * Acesso às configurações do agente
</Card>

<Warning>
  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.
</Warning>

***

## Pré-requisitos

Antes de configurar variáveis, certifique-se de que:

1. [Seu agente está ativo](/agentes/ativar-agente)
2. [Você tem permissões de edição](/workspaces/permissoes)
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ções** → **Ferramentas**
5. Clique em **Variáveis**

### Criando Variáveis Personalizadas

<Steps>
  <Step title="Adicionar Ferramenta de Variáveis">
    * Clique em **+ Adicionar Ferramenta**
    * Selecione **Variáveis** na lista
    * Clique em **Conectar variáveis**
  </Step>

  <Step title="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
  </Step>

  <Step title="Templates Disponíveis">
    <AccordionGroup>
      <Accordion title="Template Padrão">
        * `nome` - Nome completo do usuário
        * `email` - Endereço de email do usuário
        * Use o botão **Preencher com template** para aplicar
      </Accordion>

      <Accordion title="Configuração Manual">
        * Clique em **+ Adicionar variável**
        * Defina nome e descrição personalizados
        * Repita para cada variável necessária
      </Accordion>
    </AccordionGroup>
  </Step>
</Steps>

***

## Tipos de Variáveis

<CardGroup cols={3}>
  <Card title="Variáveis Customizadas" icon="gear">
    * Criadas por você
    * Específicas do seu negócio
    * Exemplos: `{{produto_interesse}}`, `{{data_agendamento}}`
  </Card>

  <Card title="Variáveis Globais" icon="globe">
    * Capturadas automaticamente
    * Baseadas no canal de comunicação
    * Exemplos: `{{user-name}}`, `{{user-email}}`
  </Card>

  <Card title="Variáveis de Runtime" icon="clock">
    * Geradas pelo sistema
    * Atualizadas dinamicamente
    * Exemplos: `{{today}}`, `{{conversation-id}}`
  </Card>
</CardGroup>

### Variáveis Globais por Canal

<CardGroup cols={2}>
  <Card title="Dashboard" icon="desktop">
    * `{{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
  </Card>

  <Card title="WhatsApp" icon="phone">
    * `{{user-name}}` - Nome do contato
    * `{{user-phone-number}}` - Número de telefone
    * Extraídas do perfil do WhatsApp
  </Card>

  <Card title="Variáveis de Sistema" icon="robot">
    * `{{today}}` - Data/hora atual
    * `{{conversation-id}}` - ID da conversa
    * `{{conversation-status}}` - Status da conversa
    * `{{conversation-channel}}` - Canal de comunicação
  </Card>
</CardGroup>

***

## 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

<CardGroup cols={2}>
  <Card title="Data e Tempo" icon="clock">
    **`{{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`
  </Card>

  <Card title="Identificação da Conversa" icon="id-card">
    **`{{conversation-id}}`**

    * ID único da conversa
    * Gerado automaticamente pelo sistema
    * Útil para integrações e logs
    * Exemplo: `clr8x9y2k0001abc123def456`
  </Card>

  <Card title="Status da Conversa" icon="flag">
    **`{{conversation-status}}`**

    * Status atual da conversa
    * Valores possíveis: `OPEN`, `RESOLVED`, `PENDING`
    * Atualizado conforme ações do usuário
    * Útil para workflows condicionais
  </Card>

  <Card title="Prioridade" icon="exclamation-triangle">
    **`{{conversation-priority}}`**

    * Nível de prioridade da conversa
    * Valores: `LOW`, `MEDIUM`, `HIGH`, `URGENT`
    * Pode ser definida manualmente ou por regras
    * Influencia ordem de atendimento
  </Card>

  <Card title="Canal de Comunicação" icon="channels">
    **`{{conversation-channel}}`**

    * Canal onde a conversa está acontecendo
    * Valores: `whatsapp`, `dashboard`, `website`, `api`
    * Útil para personalizar respostas por canal
    * Permite lógica condicional
  </Card>

  <Card title="Métricas da Conversa" icon="chart-bar">
    **`{{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`
  </Card>

  <Card title="Data de Criação" icon="calendar">
    **`{{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`
  </Card>
</CardGroup>

### Casos de Uso das Variáveis de Runtime

<AccordionGroup>
  <Accordion title="Personalização por Canal">
    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 %}
    ```
  </Accordion>

  <Accordion title="Controle de Tempo">
    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."
    ```
  </Accordion>

  <Accordion title="Escalação por Prioridade">
    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
    ```
  </Accordion>

  <Accordion title="Análise de Engajamento">
    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 %}"
    ```
  </Accordion>

  <Accordion title="Integrações com CRM">
    Envie contexto completo para sistemas externos:

    ```json theme={null}
    {
      "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}}"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

### Diferenças entre Tipos de Variáveis

| Tipo            | Configuração | Persistência | Atualização     | Exemplos                                    |
| --------------- | ------------ | ------------ | --------------- | ------------------------------------------- |
| **Runtime**     | Automática   | Por conversa | Dinâmica        | `{{today}}`, `{{conversation-id}}`          |
| **Global**      | Automática   | Por conversa | No início       | `{{user-name}}`, `{{user-email}}`           |
| **Customizada** | Manual       | Por conversa | Quando coletada | `{{nome_cliente}}`, `{{produto_interesse}}` |

### Limitações das Variáveis de Runtime

<Warning>
  * **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
</Warning>

### 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ções** → **Prompt**
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ções** → **Está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

<Steps>
  <Step title="Configurar Requisição">
    * Acesse **Ferramentas** → **HTTP**
    * Use variáveis no Body, Headers ou Parameters
  </Step>

  <Step title="Exemplo no Body">
    ```json theme={null}
    {
      "customer_name": "{{nome_cliente}}",
      "customer_email": "{{user-email}}",
      "product_interest": "{{produto_interesse}}",
      "conversation_id": "{{conversation-id}}"
    }
    ```
  </Step>

  <Step title="Exemplo em Headers">
    ```
    Authorization: Bearer {{api_token}}
    X-Customer-Phone: {{user-phone-number}}
    ```
  </Step>
</Steps>

### Em Follow-ups

1. Acesse **Ferramentas** → **Follow 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

<CardGroup cols={2}>
  <Card title="Em Conversa" icon="message">
    Acesse uma conversa específica para ver as variáveis coletadas
  </Card>

  <Card title="Logs do Agente" icon="file">
    Visualize o histórico de uso das variáveis nos logs
  </Card>

  <Card title="Debug Mode" icon="bug">
    Use o preview do agente para testar as substituições
  </Card>

  <Card title="Perfil do Usuário" icon="user">
    Veja as variáveis globais capturadas por conversa
  </Card>
</CardGroup>

***

## Exemplos Práticos

### E-commerce

<AccordionGroup>
  <Accordion title="Configuração de Variáveis">
    ```
    - {{nome_cliente}} - Nome do cliente
    - {{produto_carrinho}} - Produto no carrinho  
    - {{valor_total}} - Valor total da compra
    ```
  </Accordion>

  <Accordion title="Prompt do Sistema">
    ```
    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}}.
    ```
  </Accordion>

  <Accordion title="Follow-up (24 horas)">
    ```
    Olá {{nome_cliente}}! Notamos que você deixou {{produto_carrinho}} 
    no seu carrinho. Que tal finalizar sua compra? O valor continua 
    sendo {{valor_total}}.
    ```
  </Accordion>
</AccordionGroup>

### Agendamento de Consultas

<AccordionGroup>
  <Accordion title="Variáveis Necessárias">
    ```
    - {{nome_paciente}} - Nome do paciente
    - {{tipo_consulta}} - Tipo de consulta desejada
    - {{data_preferencia}} - Data preferida pelo paciente
    ```
  </Accordion>

  <Accordion title="Estágio de Coleta">
    **Objetivo**: Coletar nome, tipo de consulta e data preferida

    **Instruçõ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}}
    ```
  </Accordion>

  <Accordion title="Integração HTTP">
    ```json theme={null}
    {
      "patient_name": "{{nome_paciente}}",
      "consultation_type": "{{tipo_consulta}}",
      "preferred_date": "{{data_preferencia}}",
      "phone": "{{user-phone-number}}"
    }
    ```
  </Accordion>
</AccordionGroup>

### Suporte Técnico

<AccordionGroup>
  <Accordion title="Sistema de Protocolos">
    ```
    - {{problema_relatado}} - Descrição do problema
    - {{numero_protocolo}} - Número do protocolo gerado
    - {{tecnico_responsavel}} - Técnico designado
    ```
  </Accordion>

  <Accordion title="Prompt Personalizado">
    ```
    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}}.
    ```
  </Accordion>

  <Accordion title="Follow-up Automático">
    ```
    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.
    ```
  </Accordion>
</AccordionGroup>

***

## 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

<AccordionGroup>
  <Accordion title="Variável não está sendo substituída">
    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
  </Accordion>

  <Accordion title="Variável aparece vazia">
    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
  </Accordion>

  <Accordion title="Erro em ferramentas HTTP">
    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
  </Accordion>

  <Accordion title="Variáveis não aparecem no dropdown">
    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
  </Accordion>
</AccordionGroup>

***

## Perguntas Frequentes

<AccordionGroup>
  <Accordion title="Quantas variáveis posso criar por agente?">
    Não há limite específico, mas recomendamos até 20 variáveis por agente para manter a performance otimizada.
  </Accordion>

  <Accordion title="As variáveis persistem entre diferentes conversas?">
    Não. Cada conversa tem seu próprio conjunto de variáveis. Variáveis globais são recapturadas automaticamente.
  </Accordion>

  <Accordion title="Como monitorar o uso das variáveis?">
    Acesse os logs da conversa ou use o preview do agente para ver as substituições em tempo real.
  </Accordion>

  <Accordion title="Posso importar/exportar configurações de variáveis?">
    Atualmente não há funcionalidade de import/export. Configure manualmente ou use templates disponíveis.
  </Accordion>

  <Accordion title="Variáveis funcionam em todos os canais?">
    Sim, mas variáveis globais específicas dependem do canal (ex: user-phone-number só no WhatsApp).
  </Accordion>
</AccordionGroup>