Dynamische variabelen

Dynamische variabelen laten je runtimewaarden invoegen in de berichten, system prompts en tools van je agent. Zo kun je elk gesprek personaliseren met gebruikersspecifieke gegevens zonder meerdere agents te maken.

Overzicht

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

• System prompts 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 openen zoals de gespreks-ID of gespreksduur

Dynamische variabelen ondersteunen drie waardetypen:

Systeemvariabelen

Je agent heeft in elk gesprek zonder runtimeconfiguratie toegang tot ingebouwde system__*-variabelen. Deze variabelen hebben de gereserveerde naamruimte system__ als prefix en worden automatisch bijgewerkt naarmate het gesprek vordert. Aangepaste dynamische variabelen mogen de prefix system__ niet gebruiken of systeemvariabelen overschrijven.

Variabelen met † veranderen tussen beurten. Als je ze in prompttekst plaatst, kan dat promptcaching verhinderen. Zie Best practices voor alternatieven.

Identiteit van agent en gesprek

Tijd en tijdzone

Telefonie en berichten

Deze variabelen worden ingevuld wanneer dat van toepassing is voor telefonie- en berichtenkanalen:

Gespreksstatus per beurt

Indeling van gesprekshistorie

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 van de agent, met opgeloste parameterwaarden
• tool_results: Een array met toolantwoorden

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

Deze variabele is nuttig om gesprekscontext door te geven aan tools (zoals webhooks of aangepaste LLM’s) of om gesprekshistorie op te nemen in subagent-prompts tijdens overdrachten.

Geheime dynamische variabelen

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

Gebruik geheime dynamische variabelen voor authenticatietokens of privé-ID’s die niet naar een LLM mogen worden gestuurd. Voeg de prefix secret__ toe aan de dynamische variabele om een geheime dynamische variabele te maken.

Dynamische variabelen bijwerken vanuit tools

Tool calls kunnen dynamische variabelen maken of bijwerken als ze een geldig JSON-object retourneren. Stel de objectpaden in met puntnotatie om aan te geven wat moet worden geëxtraheerd. Als het veld of pad niet bestaat, wordt niets bijgewerkt.

Voorbeeld van een responsobject en puntnotatie:

• Status komt overeen met het pad: response.status
• Het e-mailadres van de eerste gebruiker in de gebruikersarray 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"
      }
    ]
  }
}

Stel de toewijzing als volgt in om een dynamische variabele bij te werken naar het e-mailadres van de eerste gebruiker.

Toewijzingen worden geconfigureerd voor elke webhooktool; zie tooltoewijzingen in de API-referentie.

Handleiding

Vereisten:

• Een ElevenLabs-account
• Een geconfigureerde ElevenAgents-agent (volg de quickstart om er een te maken)

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

Integratie met openbare praatpagina

De openbare praatpagina ondersteunt dynamische variabelen via URL-parameters, zodat je gesprekken kunt personaliseren wanneer je agentlinks deelt. Dit is vooral nuttig voor het insluiten van gepersonaliseerde agents in websites, e-mails of marketingcampagnes.

Methoden voor URL-parameters

Er zijn twee methoden om dynamische variabelen door te geven aan de openbare praatpagina:

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 de prefix var_:

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

Parameterprioriteit

Wanneer beide methoden tegelijk worden gebruikt, hebben afzonderlijke var_-parameters voorrang op 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" (uit var_user_name) in plaats van "Jane" (uit 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);

Best practices

Problemen oplossen