Dynamische Variablen

Dynamische Variablen ermöglichen es Ihnen, Laufzeitwerte in die Nachrichten, System-Prompts und Tools Ihres Agents einzufügen. So können Sie jede Konversation mit nutzerspezifischen Daten personalisieren, ohne mehrere Agents zu erstellen.

Überblick

Dynamische Variablen lassen sich in verschiedene Aspekte Ihres Agents integrieren:

• System-Prompts, um Verhalten und Kontext anzupassen
• Erste Nachrichten, um Begrüßungen zu personalisieren
• Tool-Parameter und Header, um nutzerspezifische Daten zu übergeben

Hier sind einige Beispiele, bei denen dynamische Variablen nützlich sind:

• Begrüßungen personalisieren mit Nutzernamen
• Kontodetails einbeziehen in Antworten
• Daten übergeben an Tool-Aufrufe
• Verhalten anpassen basierend auf Abonnementstufen
• Systeminformationen abrufen wie Konversations-ID oder Anrufdauer

Dynamische Systemvariablen

Ihr Agent hat Zugriff auf diese automatisch verfügbaren Systemvariablen:

• system__agent_id - Eindeutige Kennung des Agents, der die Konversation gestartet hat (bleibt während der gesamten Konversation unverändert)
• system__current_agent_id - Eindeutige Kennung des aktuell aktiven Agents (ändert sich nach Agent-Übergaben)
• system__caller_id - Telefonnummer des Anrufers (nur Sprachanrufe)
• system__called_number - Zieltelefonnummer (nur Sprachanrufe)
• system__call_duration_secs - Anrufdauer in Sekunden
• system__time_utc - Aktuelle UTC-Zeit (ISO-Format)
• system__time - Aktuelle Zeit in der angegebenen Zeitzone (menschenlesbares Format, z. B. “Freitag, 12:33 12. Dezember 2025”)
• system__timezone - Vom Nutzer angegebene Zeitzone (muss für tzinfo gültig sein)
• system__conversation_id - Eindeutige Konversationskennung von ElevenLabs
• system__call_sid - Anruf-SID (nur Twilio-Anrufe)
• system__call_id - Eindeutige Kennung für den SIP-Trunk-Anruf (nur SIP-Trunk-Anrufe)
• system__agent_turns - Die Gesamtzahl der Gesprächszüge, die der Agent in dieser Konversation durchgeführt hat.
• system__current_agent_turns - Die Anzahl der Gesprächszüge, die der aktuelle Agent durchgeführt hat. Wird zurückgesetzt, wenn die Konversation an einen anderen Agent übergeben wird.
• system__current_subagent_turns - Die Anzahl der Gesprächszüge, die der aktuelle Subagent durchgeführt hat. Wird zurückgesetzt, wenn der Workflow zu einem anderen Knoten wechselt.
• system__is_text_only - True, wenn die Konversation im reinen Textmodus läuft, andernfalls false.
• system__conversation_history - JSON-serialisierte Darstellung des aktuellen Konversationsverlaufs. Wird erst ausgewertet, wenn darauf verwiesen wird. Details zum Format finden Sie unten.

Systemvariablen:

• Sind ohne Laufzeitkonfiguration verfügbar
• Beginnen mit system__ (reserviertes Präfix)
• Werden während der Konversation automatisch aktualisiert

Format des Konversationsverlaufs

Die Variable system__conversation_history enthält ein JSON-Objekt mit folgender 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\"}" }]
    }
  ]
}

Jeder Eintrag enthält eine role ("user", "agent" oder "tool") und eines der folgenden Elemente:

• message — der Textinhalt des Gesprächszugs
• tool_requests — ein Array von Tool-Aufrufen durch den Agent, mit aufgelösten Parameterwerten
• tool_results — ein Array von Tool-Antworten

Wenn ein Tool-Ergebnis oder Parameter einen verschachtelten Konversationsverlauf enthält, wird dieser durch einen Platzhalter ersetzt (z. B. [conversation_history (5 turns)]), um eine unbegrenzte rekursive Erweiterung zu vermeiden.

Diese Variable ist nützlich, um Konversationskontext an Tools zu übergeben (z. B. Webhooks, benutzerdefinierte LLMs) oder um den Konversationsverlauf bei Übergaben in Prompts von Subagents einzubeziehen.

Geheime dynamische Variablen

Geheime dynamische Variablen werden genauso wie normale dynamische Variablen befüllt, weisen unsere ElevenAgents jedoch darauf hin, dass sie nur in Headern für dynamische Variablen verwendet und niemals als Teil des System-Prompts oder der ersten Nachricht eines Agents an einen LLM-Anbieter gesendet werden dürfen.

Wir empfehlen diese für Authentifizierungstoken oder private IDs, die nicht an ein LLM gesendet werden sollen. Um eine geheime dynamische Variable zu erstellen, stellen Sie der dynamischen Variablen einfach secret__ voran.

Dynamische Variablen über Tools aktualisieren

Tool-Aufrufe können dynamische Variablen erstellen oder aktualisieren, wenn sie ein gültiges JSON-Objekt zurückgeben. Um anzugeben, was extrahiert werden soll, legen Sie die Objektpfade mit Punktnotation fest. Wenn das Feld oder der Pfad nicht existiert, wird nichts aktualisiert.

Beispiel für ein Antwortobjekt und Punktnotation:

• Status entspricht dem Pfad: response.status
• Die E-Mail-Adresse des ersten Nutzers im Users-Array entspricht dem Pfad: 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"
      }
    ]
  }
}

Um eine dynamische Variable auf die E-Mail-Adresse des ersten Nutzers zu setzen, legen Sie die Zuweisung wie folgt fest.

Zuweisungen sind ein Feld jedes Webhook-Tools und werden hier dokumentiert.

Anleitung

Voraussetzungen

• Ein ElevenLabs-Konto
• Ein konfigurierter ElevenLabs Conversational Agent (hier erstellen)

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

Integration der öffentlichen Talk-to-Seite

Die öffentliche Talk-to-Seite unterstützt dynamische Variablen über URL-Parameter. So können Sie Konversationen personalisieren, wenn Sie Agent-Links teilen. Das ist besonders nützlich, um personalisierte Agents in Websites, E-Mails oder Marketingkampagnen einzubetten.

Methoden für URL-Parameter

Es gibt zwei Methoden, um dynamische Variablen an die öffentliche Talk-to-Seite zu übergeben:

Methode 1: Base64-codiertes JSON

Übergeben Sie Variablen als Base64-codiertes JSON-Objekt mit dem Parameter vars:

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

Der Parameter vars enthält Base64-codiertes JSON:

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

Methode 2: Einzelne Abfrageparameter

Übergeben Sie Variablen mit Abfrageparametern, denen var_ vorangestellt ist:

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

Parameterpriorität

Wenn beide Methoden gleichzeitig verwendet werden, haben einzelne var_-Parameter Vorrang vor den Base64-codierten Variablen, um Konflikte zu vermeiden:

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

In diesem Beispiel ist user_name “John” (aus var_user_name) statt “Jane” (aus den Base64-codierten vars).

Implementierungsbeispiele

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

Unterstützte Typen

Dynamische Variablen unterstützen diese Werttypen:

Fehlerbehebung