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:
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
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:
Varje post innehåller en role ("user", "agent" eller "tool") och något av följande:
message: Textinnehållet i turentool_requests: En array med verktygsanrop som agenten har gjort, med lösta parametervärdentool_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.
Servern laddar sedan ned varje fil med din API-nyckel:
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
För att uppdatera en dynamisk variabel till den första användarens e-postadress anger du 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)
Definiera dynamiska variabler i prompter
Lägg till variabler med dubbla klammerparenteser {{variable_name}} i dina:
- Systemprompter
- Första meddelanden
- Verktygsparametrar


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
Konfigurera standardvärden för testning utan att skicka variabler vid körning.
Uppdatera via instrumentpanelen
Uppdatera via CLI
Uppdatera via API:t
Ange standardvärden för varje dynamisk variabel på agentens instrumentpanel.

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.
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:
Parametern vars innehåller base64-kodad JSON:
Metod 2: Enskilda frågeparametrar
Skicka variabler med frågeparametrar som har prefixet var_:
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:
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
Generera URL med JavaScript
Generera URL med Python
Skapa URL manuellt
Bästa praxis
Ange en tidszon i stället för att lägga aktuell tid i promptar
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.
Koppla variabler med aktuellt tillstånd till verktygsparametrar och headers
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.
Överväg alternativ till tur-räknare 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.
Använd secret__ endast för värden som stannar i verktygsheaders
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.
Förlita dig inte på system__user_id för autentisering
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.
Konfigurera platshållare för testning och förhandsvisningar
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
Variabler ersätts inte
Kontrollera att:
- Variabelnamnen matchar exakt (skiftlägeskänsliga)
- Variabler använder dubbla klammerparenteser:
{{variable_name}} - Variablerna ingår i ditt
dynamic_variables-objekt
Typfel
Kontrollera att:
- Variabelvärdena matchar den förväntade typen
- Värdena endast är strängar, tal eller booleska värden