Variables dinámicas

Las variables dinámicas te permiten insertar valores de tiempo de ejecución en los mensajes, prompts de sistema y herramientas de tu agente. Así puedes personalizar cada conversación con datos específicos de usuario sin crear varios agentes.

Descripción general

Las variables dinámicas se pueden integrar en varios aspectos de tu agente:

• Prompts de sistema para personalizar el comportamiento y el contexto
• Primeros mensajes para personalizar saludos
• Parámetros y encabezados de herramientas para enviar datos específicos de usuario

Estos son algunos ejemplos en los que las variables dinámicas resultan útiles:

• Personalizar saludos con nombres de usuario
• Incluir detalles de la cuenta en las respuestas
• Enviar datos a llamadas de herramientas
• Personalizar el comportamiento según el nivel de suscripción
• Acceder a información del sistema como el ID de conversación o la duración de la llamada

Variables dinámicas del sistema

Tu agente tiene acceso a estas variables de sistema disponibles automáticamente:

• system__agent_id - Identificador único del agente que inició la conversación (se mantiene estable durante toda la conversación)
• system__current_agent_id - Identificador único del agente activo actualmente (cambia después de transferencias entre agentes)
• system__caller_id - Número de teléfono de quien llama (solo llamadas de voz)
• system__called_number - Número de teléfono de destino (solo llamadas de voz)
• system__call_duration_secs - Duración de la llamada en segundos
• system__time_utc - Hora UTC actual (formato ISO)
• system__time - Hora actual en la zona horaria especificada (formato legible, por ejemplo, “Viernes, 12:33 12 de diciembre de 2025”)
• system__timezone - Zona horaria proporcionada por el usuario (debe ser válida para tzinfo)
• system__conversation_id - Identificador único de conversación de ElevenLabs
• system__call_sid - SID de llamada (solo llamadas de twilio)
• system__call_id - Identificador único de la llamada de troncal SIP (solo llamadas de troncal SIP)
• system__agent_turns - Número total de turnos de conversación que ha realizado el agente durante esta conversación.
• system__current_agent_turns - Número de turnos de conversación que ha realizado el agente actual. Se restablece cada vez que la conversación se transfiere a otro agente.
• system__current_subagent_turns - Número de turnos de conversación que ha realizado el subagente actual. Se restablece cada vez que el workflow pasa a otro nodo.
• system__is_text_only - Verdadero si la conversación funciona en modo de solo texto; falso en caso contrario.
• system__conversation_history - Representación serializada en JSON del historial de conversación actual. Se evalúa de forma diferida en el momento en que se consulta. Consulta los detalles del formato más abajo.

Las variables del sistema:

• Están disponibles sin configuración en tiempo de ejecución
• Llevan el prefijo system__ (prefijo reservado)
• Se actualizan automáticamente durante toda la conversación

Formato del historial de conversación

La variable system__conversation_history contiene un objeto JSON con la siguiente estructura:

{
  "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 incluye un role ("user", "agent" o "tool") y uno de los siguientes elementos:

• message — el contenido de texto del turno
• tool_requests — un array de llamadas de herramientas realizadas por el agente, con valores de parámetros resueltos
• tool_results — un array de respuestas de herramientas

Si el resultado o parámetro de una herramienta contiene un historial de conversación anidado, se oculta con un marcador de posición (por ejemplo, [conversation_history (5 turns)]) para evitar una expansión recursiva ilimitada.

Esta variable resulta útil para enviar el contexto de la conversación a herramientas (por ejemplo, webhooks, LLM personalizados) o para incluir el historial de conversación en los prompts de subagentes durante las transferencias.

Variables dinámicas secretas

Las variables dinámicas secretas se rellenan de la misma forma que las variables dinámicas normales, pero indican a nuestros ElevenAgents que solo deben usarse en encabezados de variables dinámicas y nunca enviarse a un proveedor de LLM como parte del prompt de sistema o del primer mensaje de un agente.

Recomendamos usarlas para tokens de autenticación o ID privados que no deban enviarse a un LLM. Para crear una variable dinámica secreta, simplemente añade el prefijo secret__ a la variable dinámica.

Actualizar variables dinámicas desde herramientas

Las llamadas de herramientas pueden crear o actualizar variables dinámicas si devuelven un objeto JSON válido. Para especificar qué se debe extraer, define las rutas de objeto mediante notación de puntos. Si el campo o la ruta no existen, no se actualiza nada.

Ejemplo de un objeto de respuesta y notación de puntos:

• El estado corresponde a la ruta: response.status
• El correo electrónico del primer usuario del array de usuarios corresponde a la ruta: 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 actualizar una variable dinámica con el correo electrónico del primer usuario, configura la asignación así.

Las asignaciones son un campo de cada herramienta webhook, documentado aquí.

Guía

Requisitos previos

• Una cuenta de ElevenLabs
• Un agente conversacional de ElevenLabs configurado (crea uno aquí)

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

Integración con la página pública Habla con

La página pública Habla con admite variables dinámicas mediante parámetros de URL, lo que te permite personalizar conversaciones al compartir enlaces de agentes. Esto resulta especialmente útil para integrar agentes personalizados en sitios web, correos electrónicos o campañas de marketing.

Métodos de parámetros de URL

Hay dos métodos para enviar variables dinámicas a la página pública Habla con:

Método 1: JSON codificado en Base64

Envía variables como un objeto JSON codificado en base64 mediante el parámetro vars:

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

El parámetro vars contiene JSON codificado en base64:

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

Método 2: Parámetros de consulta individuales

Envía variables mediante parámetros de consulta con el prefijo var_:

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

Prioridad de parámetros

Cuando se usan ambos métodos a la vez, los parámetros var_ individuales tienen prioridad sobre las variables codificadas en base64 para evitar conflictos:

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

En este ejemplo, user_name será “John” (de var_user_name) en lugar de “Jane” (del parámetro vars codificado en base64).

Ejemplos de implementación

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

Las variables dinámicas admiten estos tipos de valores:

Solución de problemas