> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# Variáveis dinâmicas

As **variáveis dinâmicas** permitem inserir valores de tempo de execução nas mensagens, nos prompts de sistema e nas ferramentas do seu agente. Isso permite personalizar cada conversa com dados específicos do usuário sem criar vários agentes.

## Visão geral

As variáveis dinâmicas podem ser integradas a vários aspectos do seu agente:

* **Prompts de sistema** para personalizar o comportamento e o contexto
* **Primeiras mensagens** para personalizar cumprimentos
* **Parâmetros e cabeçalhos de ferramentas** para transmitir dados específicos do usuário

Veja alguns exemplos em que as variáveis dinâmicas são úteis:

* **Personalizar cumprimentos** com nomes de usuários
* **Incluir detalhes da conta** nas respostas
* **Transmitir dados** para chamadas de ferramentas
* **Personalizar o comportamento** com base nos níveis de assinatura
* **Acessar informações do sistema** como o ID da conversa ou a duração da chamada

As variáveis dinâmicas aceitam três tipos de valor:

#### String

Valores de texto

#### Number

Valores numéricos

#### Boolean

Valores verdadeiro/falso

## Variáveis dinâmicas do sistema

Seu agente tem acesso a variáveis integradas `system__*` em todas as conversas, sem configuração em tempo de execução. Essas variáveis têm o prefixo do namespace reservado `system__` e são atualizadas automaticamente conforme a conversa avança. Variáveis dinâmicas personalizadas não podem usar o prefixo `system__` nem substituir variáveis do sistema.

As variáveis marcadas com † mudam entre os turnos. Incluí-las no texto do prompt pode impedir o armazenamento do prompt em cache; veja [Boas práticas](#best-practices) para alternativas.

### Identidade do agente e da conversa

| Variável                   | Tipo             | Descrição                                                                                                                                             | Exemplo                                |
| -------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| `system__agent_id`         | `string`         | Identificador único do agente que iniciou a conversa. Nunca muda durante uma conversa.                                                                | `"agent_8401kp8bt0jdf14rzzcv5veq94yg"` |
| `system__current_agent_id` | `string`         | Identificador único do agente ativo no momento. É atualizado quando a conversa é transferida para outro agente.                                       | `"agent_8401kp8bt0jdf14rzzcv5veq94yg"` |
| `system__conversation_id`  | `string`         | Identificador único da conversa na ElevenLabs.                                                                                                        | `"conv_1801kp8qtb2begztn7zyf446v4jk"`  |
| `system__user_id`          | `string \| null` | ID de usuário fornecido pelo cliente para rastreamento e análises. Não deve ser considerado confiável para autenticação.                              | `"G6yhJW8MktQdhUquvXD1iKpPHql2"`       |
| `system__initiator_id`     | `string \| null` | Identificador correspondente ao método de autenticação usado para iniciar a conversa.                                                                 | `"user_1801kp8qtb2begztn7zyf446v4jk"`  |
| `system__channel`          | `string`         | Canal pelo qual a conversa foi iniciada.                                                                                                              | `"slack_integration"`                  |
| `system__is_text_only`     | `boolean`        | `true` quando a conversa está no modo somente texto (chat); `false` para chamadas de voz.                                                             | `true`                                 |
| `system__environment`      | `string`         | Ambiente em que a conversa está sendo executada, usado para resolver [variáveis de ambiente](/docs/pt/eleven-agents/integrate/environment-variables). | `"production"`                         |

### Hora e fuso horário

| Variável                | Tipo             | Descrição                                                                                                                                                    | Exemplo                              |
| ----------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------ |
| `system__timezone`      | `string \| null` | Fuso horário configurado (`conversation_config.agent.prompt.timezone`) ou fuso horário IANA fornecido pelo chamador. Usa UTC por padrão quando não definido. | `"America/New_York"`                 |
| `system__time` †        | `string`         | Data e hora atuais no fuso horário configurado (`%A, %H:%M %d %B %Y`). Reavaliada a cada turno (muda uma vez por minuto).                                    | `"Friday, 12:33 12 December 2025"`   |
| `system__time_utc` †    | `string`         | Carimbo de data e hora UTC atual no formato ISO 8601. Reavaliado a cada turno.                                                                               | `"2025-12-12T12:33:45.123456+00:00"` |
| `system__time_date`     | `string`         | Data atual no fuso horário configurado (ou UTC, se nenhum estiver definido) (`%A, %d %B %Y`). Muda uma vez por dia.                                          | `"Friday, 12 December 2025"`         |
| `system__time_hour`     | `integer`        | Hora atual (`0`–`23`) no fuso horário configurado (ou UTC, se nenhum estiver definido). Muda no máximo uma vez por hora.                                     | `12`                                 |
| `system__time_minute` † | `integer`        | Minuto atual (`0`–`59`) no fuso horário configurado (ou UTC, se nenhum estiver definido). Muda uma vez por minuto.                                           | `33`                                 |
| `system__time_second` † | `integer`        | Segundo atual (`0`–`59`) no fuso horário configurado (ou UTC, se nenhum estiver definido). Muda a cada turno.                                                | `45`                                 |

### Telefonia e mensagens

Essas variáveis são preenchidas quando aplicável nos canais de telefonia e mensagens:

| Variável                | Tipo             | Descrição                                                         | Exemplo                                  |
| ----------------------- | ---------------- | ----------------------------------------------------------------- | ---------------------------------------- |
| `system__caller_id`     | `string \| null` | Número de telefone do chamador (voz/SMS/WhatsApp/Amazon Connect). | `"+14155552671"`                         |
| `system__called_number` | `string \| null` | Número de telefone de destino chamado.                            | `"+18005551234"`                         |
| `system__call_sid`      | `string \| null` | SID de chamada do Twilio (somente chamadas do Twilio).            | `"CA3498076234a8bbf65c8f09fb8ad7ac1b"`   |
| `system__call_id`       | `string \| null` | Call-ID SIP (somente chamadas de tronco SIP).                     | `"757f72cf-e80f-44f7-87d6-a961ffbf5b3d"` |

### Estado da conversa por turno

| Variável                           | Tipo      | Descrição                                                                                                                                                                                   | Exemplo                |
| ---------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| `system__call_duration_secs` †     | `integer` | Tempo de conversa decorrido em segundos. Reavaliado a cada turno.                                                                                                                           | `142`                  |
| `system__agent_turns` †            | `integer` | Número total de turnos do agente na conversa até o momento. Aumenta a cada turno.                                                                                                           | `5`                    |
| `system__current_agent_turns` †    | `integer` | Número de turnos do agente atual; é redefinido para `0` após uma transferência de agente.                                                                                                   | `3`                    |
| `system__current_subagent_turns` † | `integer` | Número de turnos do agente no nó atual do workflow; é redefinido para `0` na transição de nó.                                                                                               | `2`                    |
| `system__conversation_history` †   | `string`  | Transcrição da conversa serializada em JSON até o turno atual (`{"entries": [{"role": "user", "message": "..."}]}`). Veja [Formato do histórico da conversa](#conversation-history-format). | `'{"entries": [...]}'` |

### Formato do histórico da conversa

A variável `system__conversation_history` contém um objeto JSON com a seguinte estrutura:

```json
{
  "x-elevenlabs-history": true,
  "entries": [
    { "role": "user", "message": "Hello" },
    { "role": "agent", "message": "Hi, how can I help?" },
    {
      "role": "agent",
      "tool_requests": [{ "tool_name": "lookup_order", "params_as_json": { "order_id": "123" } }]
    },
    {
      "role": "tool",
      "tool_results": [{ "tool_name": "lookup_order", "result_value": "{\"status\": \"shipped\"}" }]
    }
  ]
}
```

Cada entrada inclui uma `role` (`"user"`, `"agent"` ou `"tool"`) e um dos seguintes itens:

* `message`: O conteúdo de texto do turno
* `tool_requests`: Uma matriz de chamadas de ferramentas feitas pelo agente, com valores de parâmetros resolvidos
* `tool_results`: Uma matriz de respostas de ferramentas

Se o resultado ou um parâmetro de uma ferramenta contiver um histórico de conversa aninhado, ele será ocultado e substituído por um marcador (como `[conversation_history (5 turns)]`) para evitar uma expansão recursiva ilimitada.

Essa variável é útil para transmitir o contexto da conversa para ferramentas (como webhooks ou LLMs personalizados) ou para incluir o histórico da conversa nos prompts de subagentes durante transferências.

## Variáveis dinâmicas secretas

As variáveis dinâmicas secretas são preenchidas da mesma forma que as variáveis dinâmicas normais, mas indicam ao ElevenAgents que elas devem ser usadas somente nos cabeçalhos de variáveis dinâmicas e nunca enviadas a um provedor de LLM como parte do prompt de sistema ou da primeira mensagem de um agente.

Use variáveis dinâmicas secretas para tokens de autenticação ou IDs privados que não devem ser enviados a um LLM. Para criar uma variável dinâmica secreta, adicione o prefixo `secret__` à variável dinâmica.

> **Warning**
>
> Os valores secretos são armazenados ocultos, portanto a API de conversas os retorna como `<REDACTED>`.
> Os webhooks de transcrição pós-chamada entregam os valores originais, então garanta que seu endpoint de webhook
> os trate como segredos. Não use o prefixo `secret__` para valores que você precisa recuperar da
> API de conversas. Transmita-os como variáveis dinâmicas normais ou transmita um identificador não confidencial e
> procure o valor confidencial no seu próprio sistema.

## Atualizar variáveis dinâmicas por ferramentas

[Chamadas de ferramentas](/docs/pt/eleven-agents/customization/tools) podem criar ou atualizar variáveis dinâmicas se retornarem um objeto JSON válido. Para especificar o que deve ser extraído, defina os caminhos dos objetos usando notação de ponto. Se o campo ou caminho não existir, nada será atualizado.

Exemplo de um objeto de resposta e de notação de ponto:

* O status corresponde ao caminho: `response.status`
* O e-mail do primeiro usuário na matriz de usuários corresponde ao caminho: `response.users.0.email`

**`JSON`**

```JSON title="JSON"
{
  "response": {
    "status": 200,
    "message": "Successfully found 5 users",
    "users": [
      "user_1": {
        "user_name": "test_user_1",
        "email": "test_user_1@email.com"
      }
    ]
  }
}
```

Para atualizar uma variável dinâmica com o e-mail do primeiro usuário, defina a atribuição da seguinte forma.

![Parâmetros de consulta](/docs/_fern-files/_img/95ff0cae8613eafa8bc4312e7cafa39ac0eab34d2fd2b21f0894a30775366110.webp)

As atribuições são configuradas em cada ferramenta de webhook; consulte [atribuições de ferramentas](/docs/pt/eleven-agents/api-reference/tools/create#response.body.tool_config.SystemToolConfig.assignments) na referência da API.

## Guia

Pré-requisitos:

* Uma [conta da ElevenLabs](https://elevenlabs.io)
* Um agente do ElevenAgents configurado (siga o [guia de início rápido](/docs/pt/eleven-agents/quickstart) para criar um)

#### Definir variáveis dinâmicas nos prompts

Adicione variáveis usando chaves duplas `{{variable_name}}` em:

* Prompts de sistema
* Primeiras mensagens
* Parâmetros de ferramentas

![Variáveis dinâmicas em mensagens](/docs/_fern-files/_img/84a9870018a436215fe8d6563a47f42b1b45e005c56dffff3b37dbfe8a25adf3.webp)

![Variáveis dinâmicas em mensagens](/docs/_fern-files/_img/052ab733ff3ecb2512218c70d82a4337764577b0082cdc4b2fb4415d273d2cbe.webp)

#### Definir variáveis dinâmicas em ferramentas

Você também pode definir variáveis dinâmicas na configuração da ferramenta.
Para criar uma nova variável dinâmica, defina o tipo de valor como Variável dinâmica e clique no botão `+`.

![Definir marcadores](/docs/_fern-files/_img/7da35479f409f1505dc528e78d782d74e226fa51b2a5d3b6ede3929359be8ddd.webp)

![Definir marcadores](/docs/_fern-files/_img/21856929c95fe77b274dc1a849668c144554719cd468a225d110295ae94c7713.webp)

#### Definir marcadores

Configure valores padrão para testes sem transmitir variáveis em tempo de execução.

#### Atualizar pelo painel

Defina valores padrão para cada variável dinâmica no painel do agente.

![Definir marcadores](/docs/_fern-files/_img/dbea803919e315240202a3cb355ef7f62f25a5182d9aa99d0916177349c70ae4.webp)

#### Atualizar pela CLI

#### Baixar a configuração do agente

```bash
elevenlabs agents pull --agent "<agent-name>"
```

#### Editar \`agent_configs/\<agent-name>.json\`

Defina `conversation_config.agent.dynamic_variables.dynamic_variable_placeholders`. Cada chave é o nome da variável; o valor é o marcador usado durante os testes:

```json
{
  "conversation_config": {
    "agent": {
      "dynamic_variables": {
        "dynamic_variable_placeholders": {
          "user_name": "Angelo",
          "account_type": "premium"
        }
      }
    }
  }
}
```

#### Enviar suas alterações

```bash
elevenlabs agents push --agent "<agent-name>"
```

#### Atualizar pela API

```python
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs()

elevenlabs.conversational_ai.agents.update(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    conversation_config={
        "agent": {
            "dynamic_variables": {
                "dynamic_variable_placeholders": {
                    "user_name": "Angelo",
                    "account_type": "premium",
                }
            }
        },
    },
)
```

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", {
  conversationConfig: {
    agent: {
      dynamicVariables: {
        dynamicVariablePlaceholders: {
          user_name: "Angelo",
          account_type: "premium",
        },
      },
    },
  },
});
```

#### Transmitir variáveis em tempo de execução

Ao iniciar uma conversa, forneça as variáveis dinâmicas no seu código:

> **Tip**
>
> Verifique se você tem a versão mais recente do [SDK](/docs/pt/eleven-agents/libraries/python) instalada.

**`Python`**

```python title="Python" focus={10-23} maxLines=25
import os
import signal
from elevenlabs.client import ElevenLabs
from elevenlabs.conversational_ai.conversation import Conversation, ConversationInitiationData
from elevenlabs.conversational_ai.default_audio_interface import DefaultAudioInterface

agent_id = os.getenv("AGENT_ID")
api_key = os.getenv("ELEVENLABS_API_KEY")
elevenlabs = ElevenLabs(api_key=api_key)

dynamic_vars = {
    "user_name": "Angelo",
}

config = ConversationInitiationData(
    dynamic_variables=dynamic_vars
)

conversation = Conversation(
    elevenlabs,
    agent_id,
    config=config,
    # Assume auth is required when API_KEY is set.
    requires_auth=bool(api_key),
    # Use the default audio interface.
    audio_interface=DefaultAudioInterface(),
    # Callbacks that print the conversation to the console.
    callback_agent_response=lambda response: print(f"Agent: {response}"),
    callback_agent_response_correction=lambda original, corrected: print(f"Agent: {original} -> {corrected}"),
    callback_user_transcript=lambda transcript: print(f"User: {transcript}"),
    # Uncomment the below if you want to see latency measurements.
    # callback_latency_measurement=lambda latency: print(f"Latency: {latency}ms"),
)

conversation.start_session()

signal.signal(signal.SIGINT, lambda sig, frame: conversation.end_session())
```

**`JavaScript`**

```javascript title="JavaScript" focus={7-20} maxLines=25
import { Conversation } from '@elevenlabs/client';

class VoiceAgent {
  ...

  async startConversation() {
    try {
        // Request microphone access
        await navigator.mediaDevices.getUserMedia({ audio: true });

        this.conversation = await Conversation.startSession({
            agentId: 'agent_7101k5zvyjhmfg983brhmhkd98n6',

            dynamicVariables: {
                user_name: 'Angelo'
            },

            ... add some callbacks here
        });
    } catch (error) {
        console.error('Failed to start conversation:', error);
        alert('Failed to start conversation. Please ensure microphone access is granted.');
    }
  }
}
```

**`Swift`**

```swift title="Swift"
let dynamicVars: [String: DynamicVariableValue] = [
  "customer_name": .string("John Doe"),
  "account_balance": .number(5000.50),
  "user_id": .int(12345),
  "is_premium": .boolean(true)
]

// Create session config with dynamic variables
let config = SessionConfig(
    agentId: "agent_7101k5zvyjhmfg983brhmhkd98n6",
    dynamicVariables: dynamicVars
)

// Start the conversation
let conversation = try await Conversation.startSession(
    config: config
)
```

**`Widget`**

```html title="Widget"
<elevenlabs-convai
  agent-id="agent_7101k5zvyjhmfg983brhmhkd98n6"
  dynamic-variables='{"user_name": "John", "account_type": "premium"}'
></elevenlabs-convai>
```

## Integração com a página pública de conversa

A página pública de conversa aceita variáveis dinâmicas por meio de parâmetros de URL, permitindo personalizar conversas ao compartilhar links de agentes. Isso é especialmente útil para incorporar agentes personalizados em sites, e-mails ou campanhas de marketing.

### Métodos de parâmetros de URL

Há dois métodos para transmitir variáveis dinâmicas à página pública de conversa:

#### Método 1: JSON codificado em Base64

Transmita as variáveis como um objeto JSON codificado em Base64 usando o parâmetro `vars`:

```
https://elevenlabs.io/app/talk-to?agent_id=agent_7101k5zvyjhmfg983brhmhkd98n6&vars=eyJ1c2VyX25hbWUiOiJKb2huIiwiYWNjb3VudF90eXBlIjoicHJlbWl1bSJ9
```

O parâmetro `vars` contém JSON codificado em Base64:

```json
{ "user_name": "John", "account_type": "premium" }
```

#### Método 2: Parâmetros de consulta individuais

Transmita variáveis usando parâmetros de consulta com o prefixo `var_`:

```
https://elevenlabs.io/app/talk-to?agent_id=agent_7101k5zvyjhmfg983brhmhkd98n6&var_user_name=John&var_account_type=premium
```

### Precedência de parâmetros

Quando os dois métodos são usados simultaneamente, os parâmetros individuais `var_` têm precedência sobre as variáveis codificadas em Base64 para evitar conflitos:

```
https://elevenlabs.io/app/talk-to?agent_id=agent_7101k5zvyjhmfg983brhmhkd98n6&vars=eyJ1c2VyX25hbWUiOiJKYW5lIn0=&var_user_name=John
```

Neste exemplo, `user_name` será `"John"` (de `var_user_name`) em vez de `"Jane"` (do `vars` codificado em Base64).

### Exemplos de implementação

#### Geração de URL em JavaScript

```javascript
// Method 1: Base64-encoded JSON
function generateTalkToURL(agentId, variables) {
  const baseURL = 'https://elevenlabs.io/app/talk-to';
  const encodedVars = btoa(JSON.stringify(variables));
  return `${baseURL}?agent_id=${agentId}&vars=${encodedVars}`;
}

// Method 2: Individual parameters
function generateTalkToURLWithParams(agentId, variables) {
  const baseURL = 'https://elevenlabs.io/app/talk-to';
  const params = new URLSearchParams({ agent_id: agentId });

  Object.entries(variables).forEach(([key, value]) => {
    params.append(`var_${key}`, encodeURIComponent(value));
  });

  return `${baseURL}?${params.toString()}`;
}

// Usage
const variables = {
  user_name: "John Doe",
  account_type: "premium",
  session_id: "sess_123"
};

const urlMethod1 = generateTalkToURL("agent_7101k5zvyjhmfg983brhmhkd98n6", variables);
const urlMethod2 = generateTalkToURLWithParams("agent_7101k5zvyjhmfg983brhmhkd98n6", variables);
```

#### Geração de URL em Python

```python
import base64
import json
from urllib.parse import urlencode, quote

def generate_talk_to_url(agent_id, variables):
    """Generate URL with base64-encoded variables"""
    base_url = "https://elevenlabs.io/app/talk-to"
    encoded_vars = base64.b64encode(json.dumps(variables).encode()).decode()
    return f"{base_url}?agent_id={agent_id}&vars={encoded_vars}"

def generate_talk_to_url_with_params(agent_id, variables):
    """Generate URL with individual var_ parameters"""
    base_url = "https://elevenlabs.io/app/talk-to"
    params = {"agent_id": agent_id}

    for key, value in variables.items():
        params[f"var_{key}"] = value

    return f"{base_url}?{urlencode(params)}"

# Usage
variables = {
    "user_name": "John Doe",
    "account_type": "premium",
    "session_id": "sess_123"
}

url_method1 = generate_talk_to_url("agent_7101k5zvyjhmfg983brhmhkd98n6", variables)
url_method2 = generate_talk_to_url_with_params("agent_7101k5zvyjhmfg983brhmhkd98n6", variables)
```

#### Construção manual de URL

```
# Base64-encoded method
1. Create JSON: {"user_name": "John", "account_type": "premium"}
2. Encode to base64: eyJ1c2VyX25hbWUiOiJKb2huIiwiYWNjb3VudF90eXBlIjoicHJlbWl1bSJ9
3. Add to URL: https://elevenlabs.io/app/talk-to?agent_id=agent_7101k5zvyjhmfg983brhmhkd98n6&vars=eyJ1c2VyX25hbWUiOiJKb2huIiwiYWNjb3VudF90eXBlIjoicHJlbWl1bSJ9

# Individual parameters method
1. Add each variable with var_ prefix
2. URL encode values if needed
3. Final URL: https://elevenlabs.io/app/talk-to?agent_id=agent_7101k5zvyjhmfg983brhmhkd98n6&var_user_name=John&var_account_type=premium
```

## Boas práticas

#### Defina um fuso horário em vez de incluir a hora atual nos prompts

As variáveis no prompt de sistema, nos nós de [workflow](/docs/pt/eleven-agents/customization/agent-workflows) e nos [procedimentos](/docs/pt/eleven-agents/customization/procedures) são resolvidas a cada turno. Se um valor mudar entre turnos, o prompt não poderá ser armazenado em cache, o que aumenta o custo e a latência. `{{system__time_utc}}` e `{{system__time_second}}` mudam a cada turno; `{{system__time}}` e `{{system__time_minute}}` mudam a cada minuto.

Para informar ao agente a data e a hora atuais, defina um fuso horário com o botão de fuso horário no editor de Prompt de sistema (`conversation_config.agent.prompt.timezone`), em vez de incluir `{{system__time}}` ou `{{system__time_utc}}` no texto do prompt. Quando um fuso horário é definido, a plataforma adiciona a data e a hora atuais fora do prefixo do prompt armazenado em cache, para que seu prompt de sistema permaneça em cache entre os turnos. Sem um fuso horário, o agente não recebe a data e a hora atuais.

Se o seu prompt precisar da data ou da hora em linha, combine `{{system__time_date}}`, `{{system__time_hour}}` e `{{system__timezone}}` (por exemplo, `Today is {{system__time_date}}, hour {{system__time_hour}} ({{system__timezone}})`). Elas mudam no máximo uma vez por hora.

#### Vincule variáveis de estado em tempo real a parâmetros e cabeçalhos de ferramentas

Se uma ferramenta precisar de um valor marcado com †, vincule-o ao parâmetro ou cabeçalho da ferramenta em vez de incluí-lo no prompt. Os parâmetros da ferramenta são resolvidos apenas quando a ferramenta é chamada, portanto não afetam o armazenamento do prompt em cache. O LLM já visualiza a conversa, então `{{system__conversation_history}}` raramente é necessário nos prompts.

#### Considere alternativas aos contadores de turnos nos prompts

Se o seu prompt verifica contadores de turnos como `{{system__agent_turns}}`, considere estas alternativas. Use `first_message` para cumprimentos ou avisos iniciais estáticos.

Para o comportamento da primeira resposta, você pode formular a instrução com base no histórico da conversa (por exemplo, *"On your first reply, when you have not yet greeted the caller..."*). Isso depende de o LLM seguir a instrução; portanto, teste com seu modelo e mantenha o contador de turnos se os resultados forem menos confiáveis.

Se o contador apenas decide quando ramificar ou escalar, uma [condição de expressão de borda de workflow](/docs/pt/eleven-agents/customization/agent-workflows#edges-and-flow-control) ou uma [expressão de etapa If](/docs/pt/eleven-agents/customization/procedures/structured-procedures#if-else-if-and-else) de procedimento estruturado (como `system__agent_turns >= 5`) pode lidar com isso fora do prompt. Isso não abrange casos em que o LLM precisa do próprio valor.

#### Use secret\_\_ apenas para valores que ficam em cabeçalhos de ferramentas

Adicione o prefixo `secret__` a tokens de autenticação e chaves de API para que eles só possam ser vinculados a cabeçalhos de ferramentas e nunca sejam enviados ao LLM. Como os valores `secret__` são ocultados como `<REDACTED>` na API de conversas (os webhooks de transcrição pós-chamada ainda recebem os valores originais), transmita como variáveis dinâmicas normais os valores que você precisa recuperar da API de conversas ou transmita um identificador não confidencial e procure o valor confidencial no seu próprio sistema.

#### Não use system\_\_user_id para autenticação

`system__user_id` é fornecido pelo cliente para rastreamento e análises e não é verificado pelo ElevenAgents. Verifique a identidade do chamador com um [webhook de início de conversa](/docs/pt/eleven-agents/customization/personalization#conversation-initiation-webhooks), um token assinado em uma variável de cabeçalho `secret__` ou uma chamada de ferramenta de verificação antes de expor dados da conta.

#### Configure marcadores para testes e prévias

Defina valores padrão em `dynamic_variable_placeholders` para cada variável personalizada usada nos seus prompts, primeiras mensagens e ferramentas. As conversas de prévia no painel e os [testes de simulação](/docs/pt/eleven-agents/customization/agent-testing) não executam webhooks de início de conversa; portanto, as variáveis não definidas permanecem como marcadores literais `{{variable_name}}` durante os testes.

## Solução de problemas

#### Variáveis não substituídas

Verifique se:

* Os nomes das variáveis correspondem exatamente (diferenciam maiúsculas de minúsculas)
* As variáveis usam chaves duplas: `{{variable_name}}`
* As variáveis estão incluídas no objeto `dynamic_variables`

#### Erros de tipo

Certifique-se de que:

* Os valores das variáveis correspondem ao tipo esperado
* Os valores são apenas strings, números ou valores booleanos