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.

Übersicht

Dynamische Variablen lassen sich in mehrere Bereiche 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, bei denen dynamische Variablen nützlich sind:

• Begrüßungen personalisieren mit Nutzernamen
• Kontodetails einbeziehen in Antworten
• Daten übergeben an Tool-Aufrufe
• Verhalten anpassen anhand von Abonnementstufen
• Auf Systeminformationen zugreifen wie Unterhaltungs-ID oder Anrufdauer

Dynamische Variablen unterstützen drei Werttypen:

Dynamische Systemvariablen

Ihr Agent hat in jeder Unterhaltung ohne Laufzeitkonfiguration Zugriff auf integrierte system__*-Variablen. Diese Variablen haben den reservierten Namespace-Präfix system__ und werden im Verlauf der Unterhaltung automatisch aktualisiert. Benutzerdefinierte dynamische Variablen dürfen das Präfix system__ nicht verwenden oder Systemvariablen überschreiben.

Mit † markierte Variablen ändern sich zwischen Gesprächsrunden. Wenn Sie sie in Prompt-Text platzieren, kann dies das Prompt-Caching verhindern. Alternativen finden Sie unter Best Practices.

Agenten- und Unterhaltungsidentität

Zeit und Zeitzone

Telefonie und Messaging

Diese Variablen werden für Telefonie- und Messaging-Kanäle ausgefüllt, wenn sie zutreffen:

Unterhaltungsstatus pro Gesprächsrunde

Format des Unterhaltungsverlaufs

Die Variable system__conversation_history enthält ein JSON-Objekt mit der folgenden 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 der Gesprächsrunde
• tool_requests: Ein Array von Tool-Aufrufen des Agenten mit aufgelösten Parameterwerten
• tool_results: Ein Array von Tool-Antworten

Wenn ein Tool-Ergebnis oder Parameter einen verschachtelten Unterhaltungsverlauf enthält, 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 Unterhaltungskontext an Tools weiterzugeben (z. B. Webhooks oder benutzerdefinierte LLMs) oder um während Übergaben Unterhaltungsverläufe in Subagent-Prompts einzubeziehen.

Geheime dynamische Variablen

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

Verwenden Sie geheime dynamische Variablen für Authentifizierungstokens oder private IDs, die nicht an ein LLM gesendet werden sollen. Um eine geheime dynamische Variable zu erstellen, stellen Sie der dynamischen Variable 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 festzulegen, was extrahiert werden soll, setzen Sie die Objektpfade mit Punktnotation. 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 Nutzer-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 werden für jedes Webhook-Tool konfiguriert. Siehe Tool-Zuweisungen in der API-Referenz.

Anleitung

Voraussetzungen:

• Ein ElevenLabs-Konto
• Ein konfigurierter ElevenAgents-Agent (folgen Sie dem Schnellstart, um einen zu 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(),
    # 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 personalisieren, wenn Sie Agenten-Links teilen. Das ist besonders nützlich, um personalisierte Agenten 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-kodiertes JSON

Übergeben Sie Variablen als Base64-kodiertes JSON-Objekt über den 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 mit dem Präfix var_:

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

Best Practices

Fehlerbehebung