Variables dinámicas

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

Descripción general

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

• Prompts del sistema para personalizar el comportamiento y el contexto
• Primeros mensajes para personalizar los saludos
• 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 nombres de usuario
• Incluir datos 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 la conversación o la duración de la llamada

Las variables dinámicas admiten tres tipos de valores:

Variables dinámicas del sistema

Tu agente tiene acceso a variables integradas system__* en cada conversación sin necesidad de configuración en tiempo de ejecución. Estas variables llevan el prefijo del espacio de nombres reservado system__ y se actualizan automáticamente a medida que avanza la conversación. Las variables dinámicas personalizadas no pueden usar el prefijo system__ ni sobrescribir variables del sistema.

Las variables marcadas con † cambian entre turnos. Incluirlas en el texto del prompt puede impedir la caché de prompts; consulta las Buenas prácticas para ver alternativas.

Identidad del agente y de la conversación

Hora y zona horaria

Telefonía y mensajería

Estas variables se rellenan cuando corresponde en los canales de telefonía y mensajería:

Estado de la conversación por turno

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 parámetro de una herramienta contiene un historial de conversación anidado, se oculta con un marcador de posición (como [conversation_history (5 turns)]) para evitar una expansión recursiva ilimitada.

Esta variable es útil para pasar el contexto de la conversación a herramientas (como 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 de la misma forma que las variables dinámicas normales, pero indican a ElevenAgents que solo deben utilizarse en encabezados de variables dinámicas y que nunca deben enviarse a un proveedor de LLM como parte del prompt del sistema o el primer mensaje de un agente.

Usa variables dinámicas secretas para tokens de autenticación o ID privados que no deban enviarse a un LLM. Para crear una variable dinámica secreta, añade 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 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 de la matriz 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 de este modo.

Las asignaciones se configuran en cada herramienta webhook; consulta las asignaciones de herramientas en la referencia de la API.

Guía

Requisitos previos:

• Una cuenta de ElevenLabs
• Un agente de ElevenAgents configurado (sigue la guía de inicio rápido para crear uno)

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

Integración de la página pública para hablar con el agente

La página pública para hablar con el agente admite variables dinámicas mediante parámetros de URL, lo que te permite personalizar conversaciones al compartir enlaces de agentes. 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 pasar variables dinámicas a la página pública para hablar con el agente:

Método 1: JSON codificado en Base64

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

Precedencia de parámetros

Cuando se utilizan ambos métodos al mismo tiempo, 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);

Buenas prácticas

Solución de problemas