Dynamische variabelen

Dynamische variabelen stellen je in staat runtimewaarden in de berichten, systeemprompts en tools van je agent in te voegen. Hiermee kun je elk gesprek personaliseren met gebruikersspecifieke gegevens zonder meerdere agents te maken.

Overzicht

Dynamische variabelen kunnen worden geïntegreerd in verschillende onderdelen van je agent:

• Systeemprompts om gedrag en context aan te passen
• Eerste berichten om begroetingen te personaliseren
• Toolparameters en headers om gebruikersspecifieke gegevens door te geven

Hier zijn enkele voorbeelden waarin dynamische variabelen nuttig zijn:

• Begroetingen personaliseren met gebruikersnamen
• Accountgegevens opnemen in antwoorden
• Gegevens doorgeven aan tool calls
• Gedrag aanpassen op basis van abonnementsniveaus
• Systeemgegevens raadplegen zoals gespreks-ID of gespreksduur

Dynamische systeemvariabelen

Je agent heeft toegang tot deze automatisch beschikbare systeemvariabelen:

• system__agent_id - Unieke identificatiecode van de agent die het gesprek heeft gestart (blijft gedurende het hele gesprek hetzelfde)
• system__current_agent_id - Unieke identificatiecode van de momenteel actieve agent (wijzigt na agenttransfers)
• system__caller_id - Telefoonnummer van de beller (alleen spraakoproepen)
• system__called_number - Telefoonnummer van de bestemming (alleen spraakoproepen)
• system__call_duration_secs - Gespreksduur in seconden
• system__time_utc - Huidige UTC-tijd (ISO-indeling)
• system__time - Huidige tijd in de opgegeven tijdzone (leesbare indeling, bijvoorbeeld “vrijdag, 12:33 12 december 2025”)
• system__timezone - Door de gebruiker opgegeven tijdzone (moet geldig zijn voor tzinfo)
• system__conversation_id - Unieke gespreksidentificatiecode van ElevenLabs
• system__call_sid - Call SID (alleen Twilio-oproepen)
• system__call_id - Unieke identificatiecode voor de SIP-trunkoproep (alleen SIP-trunkoproepen)
• system__agent_turns - Het totale aantal gespreksbeurten dat de agent tijdens dit gesprek heeft gehad.
• system__current_agent_turns - Het aantal gespreksbeurten dat de huidige agent heeft gehad. Wordt gereset wanneer het gesprek naar een andere agent wordt overgedragen.
• system__current_subagent_turns - Het aantal gespreksbeurten dat de huidige subagent heeft gehad. Wordt gereset wanneer de workflow naar een andere node overgaat.
• system__is_text_only - True als het gesprek alleen in tekstmodus plaatsvindt, anders false.
• system__conversation_history - JSON-geserialiseerde weergave van de huidige gespreksgeschiedenis. Wordt pas geëvalueerd op het moment dat ernaar wordt verwezen. Zie hieronder de indelingsdetails.

Systeemvariabelen:

• Zijn beschikbaar zonder runtimeconfiguratie
• Hebben het voorvoegsel system__ (gereserveerd voorvoegsel)
• Worden tijdens het gesprek automatisch bijgewerkt

Indeling van de gespreksgeschiedenis

De variabele system__conversation_history bevat een JSON-object met de volgende structuur:

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

Elke invoer bevat een role ("user", "agent" of "tool") en een van de volgende:

• message — de tekstinhoud van de beurt
• tool_requests — een array met tool calls die de agent heeft gedaan, met opgeloste parameterwaarden
• tool_results — een array met toolantwoorden

Als een toolresultaat of parameter een geneste gespreksgeschiedenis bevat, wordt deze geredigeerd tot een placeholder (bijvoorbeeld [conversation_history (5 turns)]) om onbegrensde recursieve uitbreiding te voorkomen.

Deze variabele is nuttig om gesprekscontext door te geven aan tools (bijvoorbeeld webhooks, aangepaste LLM’s) of om tijdens overdrachten gespreksgeschiedenis op te nemen in prompts voor subagents.

Geheime dynamische variabelen

Geheime dynamische variabelen worden op dezelfde manier ingevuld als gewone dynamische variabelen, maar geven aan onze ElevenAgents aan dat deze alleen in headers voor dynamische variabelen mogen worden gebruikt en nooit als onderdeel van de systeemprompt of het eerste bericht van een agent naar een LLM-provider mogen worden gestuurd.

We raden aan deze te gebruiken voor authenticatietokens of privé-ID’s die niet naar een LLM mogen worden gestuurd. Om een geheime dynamische variabele te maken, geef je de dynamische variabele eenvoudig het voorvoegsel secret__.

Dynamische variabelen bijwerken vanuit tools

Tool calls kunnen dynamische variabelen maken of bijwerken als ze een geldig JSON-object retourneren. Geef met puntnotatie de objectpaden op die moeten worden geëxtraheerd. Als het veld of pad niet bestaat, wordt er niets bijgewerkt.

Voorbeeld van een response-object en puntnotatie:

• Status komt overeen met het pad: response.status
• Het e-mailadres van de eerste gebruiker in de users-array komt overeen met het pad: 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 een dynamische variabele bij te werken naar het e-mailadres van de eerste gebruiker, stel je de toewijzing als volgt in.

Toewijzingen zijn een veld van elke webhooktool, zoals hier gedocumenteerd.

Handleiding

Vereisten

• Een ElevenLabs-account
• Een geconfigureerde ElevenLabs Conversational Agent (maak er hier een)

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

Integratie met openbare Talk-to-pagina

De openbare Talk-to-pagina ondersteunt dynamische variabelen via URL-parameters, zodat je gesprekken kunt personaliseren wanneer je agentlinks deelt. Dit is vooral nuttig om gepersonaliseerde agents in websites, e-mails of marketingcampagnes in te sluiten.

Methoden voor URL-parameters

Er zijn twee methoden om dynamische variabelen door te geven aan de openbare Talk-to-pagina:

Methode 1: Base64-gecodeerde JSON

Geef variabelen door als een base64-gecodeerd JSON-object met de parameter vars:

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

De parameter vars bevat base64-gecodeerde JSON:

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

Methode 2: Afzonderlijke queryparameters

Geef variabelen door met queryparameters met het voorvoegsel var_:

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

Parameterprioriteit

Wanneer beide methoden tegelijkertijd worden gebruikt, krijgen afzonderlijke var_-parameters voorrang boven de base64-gecodeerde variabelen om conflicten te voorkomen:

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

In dit voorbeeld is user_name “John” (van var_user_name) in plaats van “Jane” (van de base64-gecodeerde vars).

Implementatievoorbeelden

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

Ondersteunde typen

Dynamische variabelen ondersteunen deze waardetypen:

Problemen oplossen