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:

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 para alternativas.

Identidade do agente e da conversa

Hora e fuso horário

Telefonia e mensagens

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

Estado da conversa por turno

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

Atualizar variáveis dinâmicas por ferramentas

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

{
  "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 configuradas em cada ferramenta de webhook; consulte atribuições de ferramentas na referência da API.

Guia

Pré-requisitos:

• Uma conta da ElevenLabs
• Um agente do ElevenAgents configurado (siga o guia de início rápido para criar um)

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

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:

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

Boas práticas

Solução de problemas