Variables dinámicas

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

Descripción general

Puedes integrar variables dinámicas en varios aspectos de tu agente:

• En los prompts de sistema para personalizar el comportamiento y el contexto
• En los primeros mensajes para personalizar los saludos
• En los parámetros y encabezados de herramientas para pasar datos específicos del usuario

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

• Personalizar saludos con los nombres de los usuarios
• Incluir detalles de la cuenta en las respuestas
• Pasar datos a llamadas de herramientas
• Personalizar el comportamiento según los niveles 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 del 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 tras 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, p. ej., “Friday, 12:33 12 December 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 la llamada (solo llamadas de twilio)
• system__call_id - Identificador único de la llamada del 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 a continuación.

Las variables del sistema:

• Están disponibles sin configuración 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 — una matriz de llamadas a herramientas realizadas por el agente, con valores de parámetros resueltos
• tool_results — una matriz de respuestas de herramientas

Si el resultado o un parámetro de una herramienta contiene un historial de conversación anidado, se oculta con un marcador de posición (p. ej., [conversation_history (5 turns)]) para evitar una expansión recursiva sin límites.

Esta variable es útil para pasar el contexto de la conversación a herramientas (p. ej., webhooks o 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 igual 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.

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

Actualizar variables dinámicas desde herramientas

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

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

• Status corresponde a la ruta: response.status
• El correo electrónico del primer usuario de la matriz users 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 de 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 de conversación

La página pública de conversación admite variables dinámicas mediante parámetros de URL, lo que te permite personalizar las conversaciones al compartir enlaces de agentes. Esto resulta especialmente útil para insertar 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 pasar variables dinámicas a la página pública de conversación:

Método 1: JSON codificado en Base64

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

Pasa las 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 individuales var_ 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” (de 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 admitidos

Las variables dinámicas admiten estos tipos de valores:

Solución de problemas