Zmienne dynamiczne

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

Omówienie

Zmienne dynamiczne można stosować w wielu elementach agenta:

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

Oto kilka przykładów zastosowania zmiennych dynamicznych:

• Personalizacja powitań imionami użytkowników
• Uwzględnianie danych konta w odpowiedziach
• Przekazywanie danych do wywołań narzędzi
• Dostosowanie zachowania do poziomu subskrypcji
• Dostęp do informacji systemowych, takich jak ID rozmowy lub czas jej trwania

Zmienna dynamiczna może zawierać dowolną wartość JSON:

Gdy lista lub obiekt zostaną wstawione do promptu, adresu URL lub innego szablonu tekstu, są dodawane jako tekst JSON. Parametr narzędzia powiązany ze zmienną listową otrzymuje samą listę.

Zmienne dynamiczne są zwracane bez zmian w API szczegółów rozmowy oraz w webhookach po rozmowie, w tym zmienne system__ opisane poniżej. Analizuj dynamic_variables jako mapę wartości JSON. Nie odrzucaj nieznanych kluczy ani typów wartości, ponieważ możemy dodać nowe zmienne system__.

Systemowe zmienne dynamiczne

Twój agent ma dostęp do wbudowanych zmiennych system__* w każdej rozmowie bez konfiguracji w czasie działania. Te zmienne mają zastrzeżony prefiks przestrzeni nazw system__ i aktualizują się automatycznie w trakcie rozmowy. Własne zmienne dynamiczne nie mogą używać prefiksu system__ ani nadpisywać zmiennych systemowych.

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

Tożsamość agenta i rozmowy

Czas i strefa czasowa

Telefonia i wiadomości

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

Stan rozmowy dla każdej tury

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: Treść tekstowa tury
• tool_requests: Tablica wywołań narzędzi wykonanych przez agenta z rozpoznanymi 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, takich jak webhooki lub własne LLM-y, albo do uwzględniania historii rozmowy w promptach podagentów podczas przekazywania rozmowy.

Przesłane pliki

system__uploaded_file_ids zawiera ID plików dołączonych przez użytkownika na czacie, na przykład w widżecie lub WhatsAppie. Aktualizuje się w każdej turze, więc plik dołączony w bieżącej wiadomości jest już na liście, gdy agent wywołuje narzędzie.

Aby przetworzyć załącznik, gdy rozmowa nadal trwa, powiąż listę z parametrem tablicowym narzędzia serwerowego wraz z system__conversation_id. Jeśli agent wywoła narzędzie, zanim użytkownik dołączy plik, parametr otrzyma pustą listę.

"request_body_schema": {
  "type": "object",
  "required": ["file_ids", "conversation_id"],
  "properties": {
    "file_ids": {
      "type": "array",
      "description": "",
      "dynamic_variable": "system__uploaded_file_ids",
      "items": { "type": "string", "description": "File ID" }
    },
    "conversation_id": {
      "type": "string",
      "dynamic_variable": "system__conversation_id"
    }
  }
}

Twój serwer pobiera następnie każdy plik za pomocą klucza API:

curl https://api.elevenlabs.io/v1/convai/conversations/$CONVERSATION_ID/files/$FILE_ID \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -o attachment

Odpowiedzią jest oryginalny plik z jego Content-Type (na przykład image/jpeg lub application/pdf). ID pliku, który nie należy do rozmowy, zwraca 404. Ostatnie ID na liście oznacza najnowszy przesłany plik.

Tajne zmienne dynamiczne

Tajne zmienne dynamiczne są uzupełniane tak samo jak zwykłe zmienne dynamiczne, ale informują ElevenAgents, że należy ich używać tylko w nagłówkach zmiennych dynamicznych i nigdy nie wysyłać do dostawcy LLM jako części promptu systemowego ani pierwszej wiadomości agenta.

Używaj tajnych zmiennych dynamicznych dla tokenów uwierzytelniania lub prywatnych ID, których nie należy wysyłać do LLM. Aby utworzyć tajną zmienną dynamiczną, dodaj prefiks 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 należy wyodrębnić, ustaw ścieżki obiektów w 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ą tak, by zawierała e-mail pierwszego użytkownika, ustaw przypisanie w ten sposób.

Przypisania konfiguruje się dla każdego narzędzia webhooka; zobacz przypisania narzędzi w dokumentacji API.

Przewodnik

Wymagania wstępne:

• Konto ElevenLabs
• Skonfigurowany agent ElevenAgents (aby go utworzyć, postępuj zgodnie z krótkim przewodnikiem)

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 agenta. Jest to szczególnie przydatne przy osadzaniu spersonalizowanych agentów na stronach internetowych, w e-mailach lub kampaniach marketingowych.

Metody parametrów URL

Są dwa sposoby 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: Osobne 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, osobne 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