Zmienne dynamiczne

Zmienne dynamiczne pozwalają wstawiać wartości z 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żna wykorzystać w wielu elementach agenta:

• Promptach systemowych, by dostosować zachowanie i kontekst
• Pierwszych wiadomościach, by personalizować powitania
• Parametrach i nagłówkach narzędzi, by przekazywać dane użytkownika

Oto kilka przykładów, gdy zmienne dynamiczne są przydatne:

• Personalizowanie powitań imionami użytkowników
• Uwzględnianie danych konta w odpowiedziach
• Przekazywanie danych do wywołań narzędzi
• Dostosowywanie zachowania zależnie od pakietu subskrypcji
• Dostęp do informacji systemowych, takich jak ID rozmowy czy czas trwania połączenia

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

Systemowe zmienne dynamiczne

Twój agent ma dostęp do wbudowanych zmiennych system__* w każdej rozmowie bez konfiguracji w czasie działania. Zmienne te mają zarezerwowany prefiks przestrzeni nazw system__ i aktualizują się automatycznie w trakcie rozmowy. Niestandardowe zmienne dynamiczne nie mogą używać prefiksu system__ ani zastępować zmiennych systemowych.

Zmienne oznaczone † zmieniają się między turami. Umieszczenie ich w tekście promptu może uniemożliwić cache’owanie promptu; alternatywy znajdziesz w sekcji Dobre praktyki.

Tożsamość agenta i rozmowy

Czas i strefa czasowa

Telefonia i wiadomości

Te zmienne są wypełniane, gdy mają zastosowanie w kanałach telefonicznych i wiadomości:

Stan rozmowy na turę

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:

• message: Treść tekstowa tury
• tool_requests: Tablica wywołań narzędzi wykonanych przez agenta wraz z rozstrzygniętymi wartościami parametrów
• tool_results: Tablica odpowiedzi narzędzi

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

Ta zmienna przydaje się do przekazywania kontekstu rozmowy do narzędzi (np. webhooków lub niestandardowych LLM-ów) albo do uwzględniania historii rozmowy w promptach podagentów podczas przekazywania rozmowy.

Sekretne zmienne dynamiczne

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

Używaj sekretnych zmiennych dynamicznych do tokenów autoryzacji lub prywatnych ID, których nie należy wysyłać do LLM. Aby utworzyć sekretną zmienną dynamiczną, dodaj przed nią prefiks secret__.

Aktualizowanie zmiennych dynamicznych z narzędzi

Wywołania narzędzi mogą tworzyć lub aktualizować zmienne dynamiczne, jeśli zwracają prawidłowy obiekt JSON. Aby określić, co należy wyodrębnić, ustaw ścieżki obiektów 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 users 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 konfigurujesz w każdym narzędziu webhooka; zobacz przypisania narzędzi w dokumentacji API.

Przewodnik

Wymagania wstępne:

• Konto ElevenLabs
• Skonfigurowany agent ElevenAgents (aby go utworzyć, skorzystaj z krótkiego przewodnika)

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

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

Priorytet parametrów

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

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 vars zakodowanego w Base64).

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

Dobre praktyki

Rozwiązywanie problemów