Hoppa till navigering

Dynamiska variabler

Skicka värden vid körning för att anpassa agentens beteende.

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ändarspecifik data utan att skapa flera agenter.

Översikt

Dynamiska variabler kan integreras i flera delar av agenten:

  • 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ändarspecifik data

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

  • Anpassa hälsningar med användarnamn
  • Inkludera kontouppgifter i svar
  • Skicka data till verktygsanrop
  • Anpassa beteende utifrån abonnemangsnivåer
  • Få åtkomst till systeminformation som konversations-ID eller samtalslängd

En dynamisk variabel kan innehålla vilket JSON-värde som helst:

Sträng
Textvärden
Tal
Numeriska värden
Booleskt värde
Sant/falskt-värden
Lista
Arrayer med valfria JSON-värden
Objekt
Kapslad nyckel-värde-data

När en lista eller ett objekt infogas i en prompt, URL eller annan textmall infogas den som JSON-text. En verktygsparameter som är bunden till en listvariabel tar emot själva listan.

Dynamiska variabler returneras oförändrade i API:t för konversationsdetaljer och i webhooks efter samtal, inklusive system__-variablerna nedan. Tolka dynamic_variables som en mapp med JSON-värden. Avvisa inte nycklar eller värdetyper som du inte känner igen, eftersom nya system__-variabler kan läggas till.

Systemets dynamiska variabler

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

Variabler märkta med † ändras mellan turer. Att placera dem i prompttext kan förhindra promptcachning. Se Bästa praxis för alternativ.

Agent- och konversationsidentitet

VariabelTypBeskrivningExempel
system__agent_idstringUnik identifierare för agenten som startade konversationen. Ändras aldrig under en konversation."agent_8401kp8bt0jdf14rzzcv5veq94yg"
system__current_agent_idstringUnik identifierare för den aktiva agenten. Uppdateras när konversationen överförs till en annan agent."agent_8401kp8bt0jdf14rzzcv5veq94yg"
system__conversation_idstringElevenLabs unika konversationsidentifierare."conv_1801kp8qtb2begztn7zyf446v4jk"
system__user_idstring | nullKlientangivet användar-ID för spårning och analys. Får inte betraktas som tillförlitligt för autentisering."G6yhJW8MktQdhUquvXD1iKpPHql2"
system__initiator_idstring | nullIdentifierare som motsvarar autentiseringsmetoden som användes för att starta konversationen."user_1801kp8qtb2begztn7zyf446v4jk"
system__channelstringKällkanalen som konversationen startades via."slack_integration"
system__is_text_onlybooleantrue när konversationen körs i läget endast text (chatt); false för röstsamtal.true
system__environmentstringMiljön som konversationen körs i och som används för att lösa miljövariabler."production"

Tid och tidszon

VariabelTypBeskrivningExempel
system__timezonestring | nullKonfigurerad tidszon (conversation_config.agent.prompt.timezone) eller IANA-tidszon som anges av uppringaren. UTC används som standard när den inte är inställd."America/New_York"
system__time †stringAktuellt datum och aktuell tid i den konfigurerade tidszonen (%A, %H:%M %d %B %Y). Utvärderas på nytt vid varje tur (ändras en gång per minut)."Friday, 12:33 12 December 2025"
system__time_utc †stringAktuell UTC-tidsstämpel i ISO 8601-format. Utvärderas på nytt vid varje tur."2025-12-12T12:33:45.123456+00:00"
system__time_datestringAktuellt datum i den konfigurerade tidszonen (eller UTC om ingen har angetts) (%A, %d %B %Y). Ändras en gång per dag."Friday, 12 December 2025"
system__time_hourintegerAktuell timme (0–23) i den konfigurerade tidszonen (eller UTC om ingen har angetts). Ändras högst en gång i timmen.12
system__time_minute †integerAktuell minut (0–59) i den konfigurerade tidszonen (eller UTC om ingen har angetts). Ändras en gång per minut.33
system__time_second †integerAktuell sekund (0–59) i den konfigurerade tidszonen (eller UTC om ingen har angetts). Ändras vid varje tur.45

Telefoni och meddelanden

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

VariabelTypBeskrivningExempel
system__caller_idstring | nullUppringarens telefonnummer (röst/SMS/WhatsApp/Amazon Connect)."+14155552671"
system__called_numberstring | nullDet uppringda telefonnumret."+18005551234"
system__call_sidstring | nullTwilio Call SID (endast Twilio-samtal)."CA3498076234a8bbf65c8f09fb8ad7ac1b"
system__call_idstring | nullSIP Call-ID (endast SIP-trunksamtal)."757f72cf-e80f-44f7-87d6-a961ffbf5b3d"

Konversationstillstånd per tur

VariabelTypBeskrivningExempel
system__call_duration_secs †integerFörfluten konversationstid i sekunder. Utvärderas på nytt vid varje tur.142
system__agent_turns †integerTotalt antal agentturer i konversationen hittills. Ökar vid varje tur.5
system__current_agent_turns †integerAntal agentturer för den aktuella agenten; återställs till 0 efter en agentöverföring.3
system__current_subagent_turns †integerAntal agentturer i den aktuella workflow-noden; återställs till 0 vid nodövergång.2
system__conversation_history †stringJSON-serialiserad konversationsutskrift fram till den aktuella turen ({"entries": [{"role": "user", "message": "..."}]}). Se Format för konversationshistorik.'{"entries": [...]}'
system__uploaded_file_ids †string[] | nullID:n för varje fil som användaren har bifogat i konversationen hittills, äldsta först. null tills en fil har bifogats. Se Uppladdade filer.["01a1c47f-1427-71ab-9898-775cce521078"]

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 något av följande:

  • message: Textinnehållet i turen
  • 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 redigeras den till en platshållare (till exempel [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.

Uppladdade filer

system__uploaded_file_ids listar ID:n för filerna som användaren bifogade i chatten, till exempel i widgeten eller på WhatsApp. Den uppdateras vid varje tur, så en fil som bifogas i det aktuella meddelandet finns redan i listan när agenten anropar ett verktyg.

För att bearbeta en bilaga medan konversationen fortfarande är aktiv binder du listan till en arrayparameter i ett serververktyg tillsammans med system__conversation_id. Om agenten anropar verktyget innan användaren har bifogat en fil får parametern en tom lista.

"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"
}
}
}

Servern laddar sedan ned varje fil med din API-nyckel:

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

Svaret är originalfilen med dess Content-Type (till exempel image/jpeg eller application/pdf). Ett fil-ID som inte tillhör konversationen returnerar 404. Det sista ID:t i listan är den senaste uppladdningen.

Hemliga dynamiska variabler

Hemliga dynamiska variabler fylls i på samma sätt som vanliga dynamiska variabler, men anger 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. Skapa en hemlig dynamisk variabel genom att lägga till prefixet secret__ framför den dynamiska variabeln.

Hemliga värden lagras redigerade, så konversations-API:t returnerar dem som <REDACTED>. Transkriptionswebhooks efter samtal levererar originalvärdena, så se till att din webhook-slutpunkt hanterar dem som hemligheter. Använd inte prefixet secret__ för värden som du behöver läsa tillbaka från konversations-API:t. Skicka dem som vanliga dynamiska variabler, eller skicka en icke-känslig identifierare och slå upp det känsliga värdet i ditt eget system.

Uppdatera dynamiska variabler från verktyg

Verktygsanrop kan skapa eller uppdatera dynamiska variabler om de returnerar ett giltigt JSON-objekt. Ange vad som ska extraheras genom att ställa in 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
JSON
{
"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 anger du tilldelningen så här.

Frågeparametrar

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

Guide

Förutsättningar:

1

Definiera dynamiska variabler i prompter

Lägg till variabler med dubbla klammerparenteser {{variable_name}} i dina:

  • Systemprompter
  • Första meddelanden
  • Verktygsparametrar

Dynamiska variabler i meddelanden

Dynamiska variabler i meddelanden

2

Definiera dynamiska variabler i verktyg

Du kan också definiera dynamiska variabler i verktygskonfigurationen. Om du vill skapa en ny dynamisk variabel ställer du in värdetypen på Dynamic variable och klickar på knappen +.

Ange platshållare

Ange platshållare

3

Ange platshållare

Konfigurera standardvärden för testning utan att skicka variabler vid körning.

Ange standardvärden för varje dynamisk variabel på agentens instrumentpanel.

Ange platshållare

4

Skicka variabler vid körning

När du startar en konversation anger du de dynamiska variablerna i din kod:

Kontrollera att du har den senaste SDK:n installerad.

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 har stöd för dynamiska variabler via URL-parametrar, så att du kan anpassa konversationer när du delar agentlänkar. Detta är särskilt användbart för att bädda in anpassade agenter på webbplatser, i e-postmeddelanden eller i marknadsföringskampanjer.

Metoder för URL-parametrar

Det finns två sätt 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

Parametrarnas prioritet

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

Variabler i systemprompten, noder i workflow och procedurer löses vid varje tur. Om ett värde ändras mellan turer kan prompten inte cachas, vilket ökar kostnaden och fördröjningen. {{system__time_utc}} och {{system__time_second}} ändras vid varje tur; {{system__time}} och {{system__time_minute}} ändras varje minut.

För att ge agenten aktuellt datum och tid anger du en tidszon med tidszonsknappen i systempromptredigeraren (conversation_config.agent.prompt.timezone) i stället för att placera {{system__time}} eller {{system__time_utc}} i prompttexten. När en tidszon är angiven lägger plattformen till aktuellt datum och tid utanför det cachade promptprefixet, så att din systemprompt förblir cachad mellan turer. Utan en tidszon får agenten inte aktuellt datum och tid.

Om din prompt behöver datumet eller timmen infogat, kombinera {{system__time_date}}, {{system__time_hour}} och {{system__timezone}} (till exempel I dag är det {{system__time_date}}, timme {{system__time_hour}} ({{system__timezone}})). Dessa ändras som mest en gång i timmen.

Om ett verktyg behöver ett värde markerat med † kopplar du det till verktygsparametern eller headern i stället för att lägga det i prompten. Verktygsparametrar löses bara när verktyget anropas, så de påverkar inte promptcachning. LLM:en ser redan konversationen, så {{system__conversation_history}} behövs sällan i promptar.

Om din prompt kontrollerar tur-räknare som {{system__agent_turns}} bör du överväga dessa alternativ. Använd first_message för statiska inledande hälsningar eller upplysningar.

För beteende vid första svaret kan du formulera instruktionen utifrån konversationshistoriken (till exempel “I ditt första svar, när du ännu inte har hälsat på den som ringer…”). Detta bygger på att LLM:en följer instruktionen, så testa det med din modell och behåll tur-räknaren om resultaten är mindre tillförlitliga.

Om räknaren bara avgör när du ska förgrena eller eskalera kan ett villkor för workflow-kantuttryck eller ett strukturerat procedursteg If-uttryck (som system__agent_turns >= 5) hantera det utanför prompten. Detta täcker inte fall där LLM:en behöver själva värdet.

Inled autentiseringstoken och API-nycklar med secret__ så att de bara kan kopplas till verktygsheaders och aldrig skickas till LLM:en. Eftersom secret__-värden maskeras som <REDACTED> i konversations-API:et (webhooks för transkribering efter samtal får fortfarande originalvärdena) bör du skicka värden som du behöver läsa tillbaka från konversations-API:et som vanliga dynamiska variabler, eller skicka en icke-känslig identifierare och slå upp det känsliga värdet i ditt eget system.

system__user_id tillhandahålls av klienten för spårning och analys och verifieras inte av ElevenAgents. Verifiera uppringarens identitet via en webhook för konversationsinitiering, en signerad token i en secret__-headervariabel eller ett anrop till ett verifieringsverktyg innan du visar kontodata.

Ange standardvärden i dynamic_variable_placeholders för varje anpassad variabel som används i dina promptar, första meddelanden och verktyg. Förhandsvisningskonversationer i dashboarden och simuleringstester kör inte webhooks för konversationsinitiering, så variabler som inte är angivna förblir bokstavliga {{variable_name}}-platshållare under testning.

Felsökning

Kontrollera att:

  • Variabelnamnen matchar exakt (skiftlägeskänsliga)
  • Variabler använder dubbla klammerparenteser: {{variable_name}}
  • Variablerna ingår i ditt dynamic_variables-objekt

Kontrollera att:

  • Variabelvärdena matchar den förväntade typen
  • Värdena endast är strängar, tal eller booleska värden