> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# 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

> **Info**
>
> Dynamische Variablen eignen sich ideal, um nutzerspezifische Daten einzufügen, die nicht fest in der
> Konfiguration Ihres Agents hinterlegt werden sollten.

## 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](#conversation-history-format) finden Sie unten.

Systemvariablen:

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

> **Warning**
>
> Benutzerdefinierte dynamische Variablen dürfen das reservierte Präfix `system__` nicht verwenden.

### Format des Konversationsverlaufs

Die Variable `system__conversation_history` enthält ein JSON-Objekt mit folgender Struktur:

```json
{
  "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.

> **Warning**
>
> Geheime Werte werden als `<REDACTED>` maskiert zurückgegeben, auch in Webhooks nach dem Anruf und in der
> Conversations API. Verwenden Sie das Präfix `secret__` nicht für Werte, die Sie nach der
> Konversation wieder auslesen müssen. Übergeben Sie diese als reguläre dynamische Variablen oder übergeben Sie eine nicht sensible Kennung und rufen
> Sie den sensiblen Wert in Ihrem eigenen System ab.

## Dynamische Variablen über Tools aktualisieren

[Tool-Aufrufe](https://elevenlabs.io/docs/eleven-agents/customization/tools) 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`

**`JSON`**

```JSON title="JSON"
{
  "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.

![Abfrageparameter](/docs/_fern-img/95ff0cae8613eafa8bc4312e7cafa39ac0eab34d2fd2b21f0894a30775366110.webp)

Zuweisungen sind ein Feld jedes Webhook-Tools und werden [hier](/docs/de/eleven-agents/api-reference/tools/create#response.body.tool_config.SystemToolConfig.assignments) dokumentiert.

## Anleitung

### Voraussetzungen

* Ein [ElevenLabs-Konto](https://elevenlabs.io)
* Ein konfigurierter ElevenLabs Conversational Agent ([hier erstellen](/docs/de/eleven-agents/quickstart))

#### Dynamische Variablen in Prompts definieren

Fügen Sie Variablen mit doppelten geschweiften Klammern `{{variable_name}}` hinzu in:

* System-Prompts
* Ersten Nachrichten
* Tool-Parametern

![Dynamische Variablen in Nachrichten](/docs/_fern-img/84a9870018a436215fe8d6563a47f42b1b45e005c56dffff3b37dbfe8a25adf3.webp)

![Dynamische Variablen in Nachrichten](/docs/_fern-img/052ab733ff3ecb2512218c70d82a4337764577b0082cdc4b2fb4415d273d2cbe.webp)

#### Dynamische Variablen in Tools definieren

Sie können dynamische Variablen auch in der Tool-Konfiguration definieren.
Um eine neue dynamische Variable zu erstellen, setzen Sie den Werttyp auf Dynamische Variable und klicken Sie auf die Schaltfläche `+`.

![Platzhalter festlegen](/docs/_fern-img/7da35479f409f1505dc528e78d782d74e226fa51b2a5d3b6ede3929359be8ddd.webp)

![Platzhalter festlegen](/docs/_fern-img/21856929c95fe77b274dc1a849668c144554719cd468a225d110295ae94c7713.webp)

#### Platzhalter festlegen

Konfigurieren Sie Standardwerte für Tests, ohne Variablen zur Laufzeit zu übergeben.

#### Über das Dashboard aktualisieren

Legen Sie im Dashboard des Agents Standardwerte für jede dynamische Variable fest.

![Platzhalter festlegen](/docs/_fern-img/dbea803919e315240202a3cb355ef7f62f25a5182d9aa99d0916177349c70ae4.webp)

#### Über die CLI aktualisieren

#### Agent-Konfiguration abrufen

```bash
elevenlabs agents pull --agent "<agent-name>"
```

#### \`agent_configs/\<agent-name>.json\` bearbeiten

Legen Sie `conversation_config.agent.dynamic_variables.dynamic_variable_placeholders` fest. Jeder Schlüssel ist der Variablenname; der Wert ist der beim Testen verwendete Platzhalter:

```json
{
  "conversation_config": {
    "agent": {
      "dynamic_variables": {
        "dynamic_variable_placeholders": {
          "user_name": "Angelo",
          "account_type": "premium"
        }
      }
    }
  }
}
```

#### Änderungen übertragen

```bash
elevenlabs agents push --agent "<agent-name>"
```

#### Über die API aktualisieren

```python
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs()

elevenlabs.conversational_ai.agents.update(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    conversation_config={
        "agent": {
            "dynamic_variables": {
                "dynamic_variable_placeholders": {
                    "user_name": "Angelo",
                    "account_type": "premium",
                }
            }
        },
    },
)
```

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", {
  conversationConfig: {
    agent: {
      dynamicVariables: {
        dynamicVariablePlaceholders: {
          user_name: "Angelo",
          account_type: "premium",
        },
      },
    },
  },
});
```

#### Variablen zur Laufzeit übergeben

Geben Sie beim Starten einer Konversation die dynamischen Variablen in Ihrem Code an:

> **Tip**
>
> Stellen Sie sicher, dass Sie das aktuelle [SDK](/docs/de/eleven-agents/libraries/python) installiert haben.

**`Python`**

```python title="Python" focus={10-23} maxLines=25
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())
```

**`JavaScript`**

```javascript title="JavaScript" focus={7-20} maxLines=25
import { Conversation } from '@elevenlabs/client';

class VoiceAgent {
  ...

  async startConversation() {
    try {
        // Request microphone access
        await navigator.mediaDevices.getUserMedia({ audio: true });

        this.conversation = await Conversation.startSession({
            agentId: 'agent_id_goes_here', // Replace with your actual agent ID

            dynamicVariables: {
                user_name: 'Angelo'
            },

            ... add some callbacks here
        });
    } catch (error) {
        console.error('Failed to start conversation:', error);
        alert('Failed to start conversation. Please ensure microphone access is granted.');
    }
  }
}
```

**`Swift`**

```swift title="Swift"
let dynamicVars: [String: DynamicVariableValue] = [
  "customer_name": .string("John Doe"),
  "account_balance": .number(5000.50),
  "user_id": .int(12345),
  "is_premium": .boolean(true)
]

// Create session config with dynamic variables
let config = SessionConfig(
    agentId: "agent_7101k5zvyjhmfg983brhmhkd98n6",
    dynamicVariables: dynamicVars
)

// Start the conversation
let conversation = try await Conversation.startSession(
    config: config
)
```

**`Widget`**

```html title="Widget"
<elevenlabs-convai
  agent-id="agent_7101k5zvyjhmfg983brhmhkd98n6"
  dynamic-variables='{"user_name": "John", "account_type": "premium"}'
></elevenlabs-convai>
```

## 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:

```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

#### JavaScript-URL-Erstellung

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

#### Python-URL-Erstellung

```python
import base64
import json
from urllib.parse import urlencode, quote

def generate_talk_to_url(agent_id, variables):
    """Generate URL with base64-encoded variables"""
    base_url = "https://elevenlabs.io/app/talk-to"
    encoded_vars = base64.b64encode(json.dumps(variables).encode()).decode()
    return f"{base_url}?agent_id={agent_id}&vars={encoded_vars}"

def generate_talk_to_url_with_params(agent_id, variables):
    """Generate URL with individual var_ parameters"""
    base_url = "https://elevenlabs.io/app/talk-to"
    params = {"agent_id": agent_id}

    for key, value in variables.items():
        params[f"var_{key}"] = value

    return f"{base_url}?{urlencode(params)}"

# Usage
variables = {
    "user_name": "John Doe",
    "account_type": "premium",
    "session_id": "sess_123"
}

url_method1 = generate_talk_to_url("agent_7101k5zvyjhmfg983brhmhkd98n6", variables)
url_method2 = generate_talk_to_url_with_params("agent_7101k5zvyjhmfg983brhmhkd98n6", variables)
```

#### Manuelle URL-Erstellung

```
# Base64-encoded method
1. Create JSON: {"user_name": "John", "account_type": "premium"}
2. Encode to base64: eyJ1c2VyX25hbWUiOiJKb2huIiwiYWNjb3VudF90eXBlIjoicHJlbWl1bSJ9
3. Add to URL: https://elevenlabs.io/app/talk-to?agent_id=agent_7101k5zvyjhmfg983brhmhkd98n6&vars=eyJ1c2VyX25hbWUiOiJKb2huIiwiYWNjb3VudF90eXBlIjoicHJlbWl1bSJ9

# Individual parameters method
1. Add each variable with var_ prefix
2. URL encode values if needed
3. Final URL: https://elevenlabs.io/app/talk-to?agent_id=agent_7101k5zvyjhmfg983brhmhkd98n6&var_user_name=John&var_account_type=premium
```

## Unterstützte Typen

Dynamische Variablen unterstützen diese Werttypen:

#### String

Textwerte

#### Zahl

Numerische Werte

#### Boolesch

True/false-Werte

## Fehlerbehebung

#### Variablen werden nicht ersetzt

Prüfen Sie Folgendes:

* Variablennamen stimmen exakt überein (Groß-/Kleinschreibung beachten)
* Variablen verwenden doppelte geschweifte Klammern: `{{ variable_name }}`
* Variablen sind in Ihrem Objekt dynamic_variables enthalten

#### Typfehler

Stellen Sie Folgendes sicher:

* Variablenwerte entsprechen dem erwarteten Typ
* Werte sind nur Strings, Zahlen oder boolesche Werte