Dynamiska variabler

Dynamiska variabler låter dig infoga körningsvärden i agentens meddelanden, systemprompter och verktyg. Det gör att du kan anpassa varje konversation med användarspecifik data utan att skapa flera agenter.

Översikt

Dynamiska variabler kan användas i flera delar av din agent:

• Systemprompter för att anpassa beteende och kontext
• Första meddelanden för att anpassa hälsningar
• Verktygsparametrar och headers för att skicka användarspecifik data

Här är några exempel där dynamiska variabler är användbara:

• Anpassa hälsningar med användarnamn
• Inkludera kontouppgifter i svar
• Skicka data till verktygsanrop
• Anpassa beteende utifrån prenumerationsnivåer
• Få åtkomst till systeminformation som konversations-ID eller samtalslängd

Systemets dynamiska variabler

Din agent har åtkomst till dessa automatiskt tillgängliga systemvariabler:

• system__agent_id - Unik identifierare för agenten som initierade konversationen (förblir densamma under hela konversationen)
• system__current_agent_id - Unik identifierare för den aktiva agenten (ändras efter agentöverföringar)
• system__caller_id - Uppringarens telefonnummer (endast röstsamtal)
• system__called_number - Mottagarens telefonnummer (endast röstsamtal)
• system__call_duration_secs - Samtalslängd i sekunder
• system__time_utc - Aktuell UTC-tid (ISO-format)
• system__time - Aktuell tid i den angivna tidszonen (lättläst format, t.ex. “fredag, 12:33 12 december 2025”)
• system__timezone - Användarangiven tidszon (måste vara giltig för tzinfo)
• system__conversation_id - ElevenLabs unika konversationsidentifierare
• system__call_sid - Samtals-SID (endast Twilio-samtal)
• system__call_id - Unik identifierare för SIP-trunksamtalet (endast SIP-trunksamtal)
• system__agent_turns - Det totala antalet konversationsomgångar som agenten har gjort under den här konversationen.
• system__current_agent_turns - Antalet konversationsomgångar som den aktuella agenten har gjort. Återställs när konversationen överförs till en annan agent.
• system__current_subagent_turns - Antalet konversationsomgångar som den aktuella underagenten har gjort. Återställs när arbetsflödet övergår till en annan nod.
• system__is_text_only - True om konversationen körs i enbart textläge, annars false.
• system__conversation_history - JSON-serialiserad representation av den aktuella konversationshistoriken. Utvärderas först när den refereras. Se formatinformation nedan.

Systemvariabler:

• Är tillgängliga utan körningskonfiguration
• Har prefixet system__ (reserverat prefix)
• Uppdateras automatiskt under hela konversationen

Konversationshistorikens format

Variabeln system__conversation_history innehåller ett JSON-objekt med följande struktur:

{
  "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\"}" }]
    }
  ]
}

Varje post innehåller en role ("user", "agent" eller "tool") och ett av följande:

• message — omgångens textinnehåll
• tool_requests — en array med verktygsanrop som agenten har gjort, med lösta parametervärden
• tool_results — en array med verktygssvar

Om ett verktygsresultat eller en parameter innehåller en kapslad konversationshistorik maskeras den som en platshållare (t.ex. [conversation_history (5 turns)]) för att undvika obegränsad rekursiv expansion.

Den här variabeln är användbar för att skicka konversationskontext till verktyg (t.ex. webhooks, anpassade LLM:er) eller för att inkludera konversationshistorik i underagentprompter vid överlämningar.

Hemliga dynamiska variabler

Hemliga dynamiska variabler fylls i på samma sätt som vanliga dynamiska variabler, men visar för våra ElevenAgents att de endast ska användas i headers för dynamiska variabler och aldrig skickas till en LLM-leverantör som en del av agentens systemprompt eller första meddelande.

Vi rekommenderar att du använder dem för autentiseringstoken eller privata ID:n som inte ska skickas till en LLM. För att skapa en hemlig dynamisk variabel lägger du bara till prefixet secret__ framför den dynamiska variabeln.

Uppdatera dynamiska variabler från verktyg

Verktygsanrop kan skapa eller uppdatera dynamiska variabler om de returnerar ett giltigt JSON-objekt. Ange objektsökvägarna med punktnotation för att specificera vad som ska extraheras. Om fältet eller sökvägen inte finns uppdateras ingenting.

Exempel på ett svarsobjekt och punktnotation:

• Status motsvarar sökvägen: response.status
• Den första användarens e-postadress i users-arrayen motsvarar sökvägen: 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"
      }
    ]
  }
}

Om du vill uppdatera en dynamisk variabel till den första användarens e-postadress anger du tilldelningen så här.

Tilldelningar är ett fält för varje webhook-verktyg och dokumenteras här.

Guide

Förutsättningar

• Ett ElevenLabs-konto
• En konfigurerad ElevenLabs Conversational Agent (skapa en här)

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

Integrering med offentlig Talk-to-sida

Den offentliga Talk-to-sidan stöder dynamiska variabler via URL-parametrar, vilket gör att du kan anpassa konversationer när du delar agentlänkar. Det är särskilt användbart när du bäddar in anpassade agenter på webbplatser, i e-postmeddelanden eller i marknadsföringskampanjer.

Metoder för URL-parametrar

Det finns två metoder för att skicka dynamiska variabler till den offentliga Talk-to-sidan:

Metod 1: Base64-kodad JSON

Skicka variabler som ett base64-kodat JSON-objekt med parametern vars:

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

Parametern vars innehåller base64-kodad JSON:

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

Metod 2: Enskilda frågeparametrar

Skicka variabler med frågeparametrar som har prefixet var_:

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

Parameterprioritet

När båda metoderna används samtidigt har enskilda var_-parametrar företräde framför de base64-kodade variablerna för att undvika konflikter:

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

I det här exemplet blir user_name “John” (från var_user_name) i stället för “Jane” (från de base64-kodade vars).

Implementeringsexempel

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

Typer som stöds

Dynamiska variabler stöder följande värdetyper:

Felsökning