Dynamiska variabler

Dynamiska variabler låter dig infoga värden vid körning i agentens meddelanden, systemprompter och verktyg. På så sätt kan du anpassa varje konversation med användarspecifika data utan att skapa flera agenter.

Översikt

Dynamiska variabler kan integreras i flera delar av din agent:

• Systemprompter för att anpassa beteende och kontext
• Första meddelanden för att anpassa hälsningar
• Verktygsparametrar och headers för att skicka användarspecifika data

Här är några exempel på när dynamiska variabler är användbara:

• Personliga hälsningar med användarnamn
• Kontouppgifter i svar
• Data till verktygsanrop
• Anpassat beteende baserat på prenumerationsnivåer
• Systeminformation som konversations-ID eller samtalslängd

Dynamiska variabler stöder tre värdetyper:

Dynamiska systemvariabler

Din agent har tillgång till inbyggda system__*-variabler i varje konversation utan konfiguration vid körning. Dessa variabler har det reserverade prefixet system__ och uppdateras automatiskt medan konversationen pågår. Anpassade dynamiska variabler kan inte använda prefixet system__ eller åsidosätta systemvariabler.

Variabler markerade med † ändras mellan turer. Om du placerar dem i prompttext kan det förhindra promptcachelagring. Se Bästa praxis för alternativ.

Agent- och konversationsidentitet

Tid och tidszon

Telefoni och meddelanden

Dessa variabler fylls i när det är relevant för telefoni- och meddelandekanaler:

Konversationstillstånd per tur

Format för konversationshistorik

Variabeln system__conversation_history innehåller ett JSON-objekt med följande 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\"}" }]
    }
  ]
}

Varje post innehåller en role ("user", "agent" eller "tool") och ett av följande:

• message: Turens textinnehåll
• tool_requests: En array med verktygsanrop som agenten har gjort, med lösta parametervärden
• tool_results: En array med verktygssvar

Om ett verktygsresultat eller en parameter innehåller en kapslad konversationshistorik maskeras den till en platshållare (som [conversation_history (5 turns)]) för att undvika obegränsad rekursiv expansion.

Den här variabeln är användbar för att skicka konversationskontext till verktyg (som webhooks eller anpassade LLM:er) eller för att inkludera konversationshistorik i underagentprompter vid överlämningar.

Hemliga dynamiska variabler

Hemliga dynamiska variabler fylls i på samma sätt som vanliga dynamiska variabler, men visar för ElevenAgents att de endast ska användas i headers för dynamiska variabler och aldrig skickas till en LLM-leverantör som en del av agentens systemprompt eller första meddelande.

Använd hemliga dynamiska variabler för autentiseringstoken eller privata ID:n som inte ska skickas till en LLM. Om du vill skapa en hemlig dynamisk variabel lägger du till prefixet secret__ före den dynamiska variabeln.

Uppdatera dynamiska variabler från verktyg

Verktygsanrop kan skapa eller uppdatera dynamiska variabler om de returnerar ett giltigt JSON-objekt. För att ange vad som ska extraheras anger du objektsökvägarna med punktnotation. Om fältet eller sökvägen inte finns uppdateras ingenting.

Exempel på ett svarsobjekt och punktnotation:

• Status motsvarar sökvägen: response.status
• Den första användarens e-postadress i users-arrayen motsvarar sökvägen: 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"
      }
    ]
  }
}

För att uppdatera en dynamisk variabel till den första användarens e-postadress ställer du in tilldelningen så här.

Tilldelningar konfigureras för varje webhook-verktyg. Se verktygstilldelningar i API-referensen.

Guide

Förutsättningar:

• Ett ElevenLabs-konto
• En konfigurerad ElevenAgents-agent (följ snabbstarten för att skapa en)

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

Integrering med offentlig talk-to-sida

Den offentliga talk-to-sidan stöder dynamiska variabler via URL-parametrar, så att du kan anpassa konversationer när du delar agentlänkar. Det är särskilt användbart när du bäddar in personliga agenter på webbplatser, i e-post eller i marknadsföringskampanjer.

Metoder för URL-parametrar

Det finns två metoder för att skicka dynamiska variabler till den offentliga talk-to-sidan:

Metod 1: Base64-kodad JSON

Skicka variabler som ett base64-kodat JSON-objekt med parametern vars:

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

Parametern vars innehåller base64-kodad JSON:

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

Metod 2: Enskilda frågeparametrar

Skicka variabler med frågeparametrar som har prefixet var_:

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

Parameterprioritet

När båda metoderna används samtidigt har enskilda var_-parametrar företräde framför de base64-kodade variablerna för att undvika konflikter:

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

I det här exemplet blir user_name "John" (från var_user_name) i stället för "Jane" (från den base64-kodade vars).

Implementeringsexempel

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

Bästa praxis

Felsökning