Variáveis dinâmicas

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 saudações
• 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 saudações 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 ID da conversa ou duração da chamada

Variáveis dinâmicas do sistema

Seu agente tem acesso a estas variáveis do sistema disponíveis automaticamente:

• system__agent_id - Identificador exclusivo do agente que iniciou a conversa (permanece estável durante toda a conversa)
• system__current_agent_id - Identificador exclusivo do agente atualmente ativo (muda após transferências de agente)
• system__caller_id - Número de telefone de quem ligou (somente chamadas de voz)
• system__called_number - Número de telefone de destino (somente chamadas de voz)
• system__call_duration_secs - Duração da chamada em segundos
• system__time_utc - Horário UTC atual (formato ISO)
• system__time - Horário atual no fuso horário especificado (formato legível, por exemplo, “Friday, 12:33 12 December 2025”)
• system__timezone - Fuso horário fornecido pelo usuário (deve ser válido para tzinfo)
• system__conversation_id - Identificador exclusivo da conversa da ElevenLabs
• system__call_sid - SID da chamada (somente chamadas Twilio)
• system__call_id - Identificador exclusivo da chamada do tronco SIP (somente chamadas do tronco SIP)
• system__agent_turns - Número total de turnos de conversa realizados pelo agente durante esta conversa.
• system__current_agent_turns - Número de turnos de conversa realizados pelo agente atual. É redefinido sempre que a conversa é transferida para um agente diferente.
• system__current_subagent_turns - Número de turnos de conversa realizados pelo subagente atual. É redefinido sempre que o workflow faz a transição para um nó diferente.
• system__is_text_only - Verdadeiro se a conversa operar no modo somente texto; caso contrário, falso.
• system__conversation_history - Representação serializada em JSON do histórico atual da conversa. Avaliada de forma preguiçosa no momento em que é referenciada. Veja os detalhes do formato abaixo.

Variáveis do sistema:

• Estão disponíveis sem configuração de tempo de execução
• Têm o prefixo system__ (prefixo reservado)
• São atualizadas automaticamente durante toda a conversa

Formato do histórico da conversa

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

{
  "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 um 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 parâmetro de uma ferramenta contiver um histórico de conversa aninhado, ele será ocultado por um marcador (por exemplo, [conversation_history (5 turns)]) para evitar expansão recursiva ilimitada.

Essa variável é útil para transmitir o contexto da conversa a ferramentas (por exemplo, webhooks e LLMs personalizados) ou para incluir o histórico da conversa em 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 aos nossos ElevenAgents que elas só devem ser usadas em 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.

Recomendamos usá-las 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, basta adicionar o prefixo secret__ à variável dinâmica.

Atualizar variáveis dinâmicas com ferramentas

As chamadas de ferramentas 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 de objeto usando a notação de ponto. Se o campo ou caminho não existir, nada será atualizado.

Exemplo de objeto de resposta e 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

{
  "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.

As atribuições são um campo de cada ferramenta de webhook, documentado aqui.

Guia

Pré-requisitos

• Uma conta da ElevenLabs
• Um Agente Conversacional da ElevenLabs configurado (crie um aqui)

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(),
    # Simple 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())

Integração com a página pública Fale com

A página pública Fale com oferece suporte a variáveis dinâmicas por meio de parâmetros de URL, permitindo personalizar conversas ao compartilhar links de agentes. Isso é particularmente ú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 Fale com:

Método 1: JSON codificado em Base64

Transmita 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:

{ "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

// 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);

Tipos aceitos

As variáveis dinâmicas aceitam estes tipos de valor:

Solução de problemas