Zmienne dynamiczne

Zmienne dynamiczne pozwalają wstawiać wartości czasu działania do wiadomości, promptów systemowych i narzędzi agenta. Dzięki temu możesz personalizować każdą rozmowę danymi użytkownika bez tworzenia wielu agentów.

Omówienie

Zmienne dynamiczne możesz zintegrować z wieloma elementami agenta:

• Promptami systemowymi, aby dostosować zachowanie i kontekst
• Pierwszymi wiadomościami, aby personalizować powitania
• Parametrami i nagłówkami narzędzi, aby przekazywać dane użytkownika

Oto kilka przykładów zastosowania zmiennych dynamicznych:

• Personalizowanie powitań imionami użytkowników
• Uwzględnianie danych konta w odpowiedziach
• Przekazywanie danych do wywołań narzędzi
• Dostosowywanie zachowania na podstawie poziomów subskrypcji
• Dostęp do informacji systemowych, takich jak identyfikator rozmowy lub czas trwania połączenia

Systemowe zmienne dynamiczne

Agent ma dostęp do tych automatycznie dostępnych zmiennych systemowych:

• system__agent_id - Unikalny identyfikator agenta, który rozpoczął rozmowę (pozostaje stały przez całą rozmowę)
• system__current_agent_id - Unikalny identyfikator aktualnie aktywnego agenta (zmienia się po przekazaniu do innego agenta)
• system__caller_id - Numer telefonu osoby dzwoniącej (tylko połączenia głosowe)
• system__called_number - Docelowy numer telefonu (tylko połączenia głosowe)
• system__call_duration_secs - Czas trwania połączenia w sekundach
• system__time_utc - Aktualny czas UTC (format ISO)
• system__time - Aktualny czas w określonej strefie czasowej (format czytelny dla człowieka, np. „piątek, 12:33, 12 grudnia 2025”)
• system__timezone - Strefa czasowa podana przez użytkownika (musi być prawidłowa dla tzinfo)
• system__conversation_id - Unikalny identyfikator rozmowy ElevenLabs
• system__call_sid - SID połączenia (tylko połączenia twilio)
• system__call_id - Unikalny identyfikator połączenia SIP trunk (tylko połączenia SIP trunk)
• system__agent_turns - Łączna liczba tur rozmowy wykonanych przez agenta w tej rozmowie.
• system__current_agent_turns - Liczba tur rozmowy wykonanych przez bieżącego agenta. Resetuje się przy przekazaniu rozmowy do innego agenta.
• system__current_subagent_turns - Liczba tur rozmowy wykonanych przez bieżącego subagenta. Resetuje się, gdy workflow przechodzi do innego węzła.
• system__is_text_only - True, jeśli rozmowa działa wyłącznie w trybie tekstowym, w przeciwnym razie false.
• system__conversation_history - Reprezentacja bieżącej historii rozmowy zserializowana do JSON. Jest obliczana leniwie w chwili odwołania. Zobacz poniżej szczegóły formatu.

Zmienne systemowe:

• Są dostępne bez konfiguracji w czasie działania
• Mają prefiks system__ (zastrzeżony prefiks)
• Są automatycznie aktualizowane przez całą rozmowę

Format historii rozmowy

Zmienna system__conversation_history zawiera obiekt JSON o następującej strukturze:

{
  "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\"}" }]
    }
  ]
}

Każdy wpis zawiera role ("user", "agent" lub "tool") oraz jedno z poniższych pól:

• message — tekstowa treść tury
• tool_requests — tablica wywołań narzędzi wykonanych przez agenta wraz z rozwiązanymi wartościami parametrów
• tool_results — tablica odpowiedzi narzędzi

Jeśli wynik narzędzia lub parametr zawiera zagnieżdżoną historię rozmowy, zostaje ona zastąpiona placeholderem (np. [conversation_history (5 turns)]), aby uniknąć nieograniczonego rekurencyjnego rozwijania.

Ta zmienna przydaje się do przekazywania kontekstu rozmowy do narzędzi (np. webhooków, własnych LLM-ów) lub do uwzględniania historii rozmowy w promptach subagentów podczas przekazywania rozmowy.

Tajne zmienne dynamiczne

Tajne zmienne dynamiczne są wypełniane tak samo jak zwykłe zmienne dynamiczne, ale informują nasze ElevenAgents, że powinny być używane wyłącznie w nagłówkach zmiennych dynamicznych i nigdy nie powinny być wysyłane do dostawcy LLM jako część promptu systemowego agenta lub pierwszej wiadomości.

Zalecamy ich użycie dla tokenów auth lub prywatnych identyfikatorów, których nie należy wysyłać do LLM-a. Aby utworzyć tajną zmienną dynamiczną, po prostu poprzedź ją prefiksem secret__.

Aktualizowanie zmiennych dynamicznych z narzędzi

Wywołania narzędzi mogą tworzyć lub aktualizować zmienne dynamiczne, jeśli zwrócą prawidłowy obiekt JSON. Aby określić, co ma zostać wyodrębnione, ustaw ścieżki obiektu za pomocą notacji kropkowej. Jeśli pole lub ścieżka nie istnieje, nic nie zostanie zaktualizowane.

Przykład obiektu odpowiedzi i notacji kropkowej:

• Status odpowiada ścieżce: response.status
• E-mail pierwszego użytkownika w tablicy użytkowników odpowiada ścieżce: 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"
      }
    ]
  }
}

Aby zaktualizować zmienną dynamiczną na e-mail pierwszego użytkownika, ustaw przypisanie w ten sposób.

Przypisania są polem każdego narzędzia webhook, opisanym tutaj.

Przewodnik

Wymagania wstępne

• Konto ElevenLabs
• Skonfigurowany agent konwersacyjny ElevenLabs (utwórz go tutaj)

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

Integracja z publiczną stroną rozmowy

Publiczna strona rozmowy obsługuje zmienne dynamiczne przez parametry URL, dzięki czemu możesz personalizować rozmowy podczas udostępniania linków do agentów. Jest to szczególnie przydatne przy osadzaniu spersonalizowanych agentów na stronach internetowych, w e-mailach lub kampaniach marketingowych.

Metody parametrów URL

Istnieją dwie metody przekazywania zmiennych dynamicznych do publicznej strony rozmowy:

Metoda 1: JSON zakodowany w Base64

Przekaż zmienne jako obiekt JSON zakodowany w Base64 za pomocą parametru vars:

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

Parametr vars zawiera JSON zakodowany w Base64:

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

Metoda 2: Pojedyncze parametry zapytania

Przekaż zmienne za pomocą parametrów zapytania z prefiksem var_:

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

Pierwszeństwo parametrów

Gdy obie metody są używane jednocześnie, pojedyncze parametry var_ mają pierwszeństwo przed zmiennymi zakodowanymi w Base64, aby zapobiec konfliktom:

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

W tym przykładzie user_name będzie mieć wartość „John” (z var_user_name) zamiast „Jane” (z zakodowanego w Base64 vars).

Przykłady implementacji

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

Obsługiwane typy

Zmienne dynamiczne obsługują te typy wartości:

Rozwiązywanie problemów