Dynamische Variablen

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

Überblick

Dynamische Variablen lassen sich in mehrere Aspekte Ihres Agenten 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, in 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
• Auf Systeminformationen zugreifen wie Unterhaltungs-ID oder Anrufdauer

Dynamische Systemvariablen

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

• system__agent_id - Eindeutige Kennung des Agenten, der die Unterhaltung gestartet hat (bleibt während der gesamten Unterhaltung unverändert)
• system__current_agent_id - Eindeutige Kennung des aktuell aktiven Agenten (ändert sich nach Agentenü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. “Friday, 12:33 12 December 2025”)
• system__timezone - Vom Nutzer angegebene Zeitzone (muss für tzinfo gültig sein)
• system__conversation_id - Eindeutige Unterhaltungskennung 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ächswechsel, die der Agent während dieser Unterhaltung durchgeführt hat.
• system__current_agent_turns - Die Anzahl der Gesprächswechsel, die der aktuelle Agent durchgeführt hat. Wird zurückgesetzt, wenn die Unterhaltung an einen anderen Agenten übergeben wird.
• system__current_subagent_turns - Die Anzahl der Gesprächswechsel, 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 Unterhaltung im reinen Textmodus läuft, andernfalls false.
• system__conversation_history - JSON-serialisierte Darstellung des aktuellen Gesprächsverlaufs. Wird erst ausgewertet, wenn darauf verwiesen wird. Siehe unten Formatdetails.

Systemvariablen:

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

Format des Gesprächsverlaufs

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ächswechsels
• tool_requests — ein Array von Tool-Aufrufen des Agenten mit aufgelösten Parameterwerten
• tool_results — ein Array von Tool-Antworten

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

Diese Variable ist nützlich, um Tools (z. B. Webhooks, benutzerdefinierten LLMs) Gesprächskontext zu übergeben oder um bei Übergaben Gesprächsverläufe in Subagent-Prompts einzubinden.

Geheime dynamische Variablen

Geheime dynamische Variablen werden auf dieselbe Weise wie normale dynamische Variablen befüllt, weisen unsere ElevenAgents jedoch darauf hin, dass sie nur in Headern dynamischer Variablen verwendet und nie als Teil des System-Prompts oder der ersten Nachricht eines Agenten an einen LLM-Anbieter gesendet werden dürfen.

Wir empfehlen, sie für Authentifizierungstoken oder private IDs zu verwenden, die nicht an ein LLM gesendet werden sollten. Um eine geheime dynamische Variable zu erstellen, setzen Sie einfach secret__ vor die dynamische Variable.

Dynamische Variablen über Tools aktualisieren

Tool-Aufrufe können dynamische Variablen erstellen oder aktualisieren, wenn sie ein gültiges JSON-Objekt zurückgeben. Um festzulegen, was extrahiert werden soll, setzen Sie die Objektpfade mit Punktnotation. Falls 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 aktualisieren, 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 Unterhaltungen beim Teilen von Agentenlinks personalisieren. Das ist besonders nützlich, um personalisierte Agenten in Websites, E-Mails oder Marketingkampagnen einzubetten.

URL-Parametermethoden

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

Methode 1: Base64-kodiertes JSON

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

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

Der Parameter vars enthält Base64-kodiertes JSON:

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

Methode 2: Einzelne Abfrageparameter

Übergeben Sie Variablen mit Abfrageparametern, die das Präfix var_ verwenden:

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-kodierten 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 dem Base64-kodierten 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