Vai alla navigazione

Variabili dinamiche

Passa valori runtime per personalizzare il comportamento del tuo agente.

Le variabili dinamiche ti consentono di inserire valori runtime nei messaggi, nei prompt di sistema e negli strumenti del tuo agente. In questo modo puoi personalizzare ogni conversazione con dati specifici dell’utente senza creare più agenti.

Panoramica

Le variabili dinamiche possono essere integrate in diversi aspetti del tuo agente:

  • Nei prompt di sistema per personalizzare comportamento e contesto
  • Nei primi messaggi per personalizzare i saluti
  • Nei parametri e negli header degli strumenti per passare dati specifici dell’utente

Ecco alcuni esempi in cui le variabili dinamiche sono utili:

  • Personalizzare i saluti con i nomi degli utenti
  • Includere i dettagli dell’account nelle risposte
  • Passare dati alle chiamate degli strumenti
  • Personalizzare il comportamento in base al piano di abbonamento
  • Accedere alle informazioni di sistema come l’ID della conversazione o la durata della chiamata

Una variabile dinamica può contenere qualsiasi valore JSON:

Stringa
Valori di testo
Numero
Valori numerici
Booleano
Valori vero/falso
Elenco
Array di qualsiasi valore JSON
Oggetto
Dati chiave-valore annidati

Quando un elenco o un oggetto viene inserito in un prompt, URL o altro modello di testo, viene inserito come testo JSON. Un parametro dello strumento associato a una variabile elenco riceve l’elenco stesso.

Le variabili dinamiche vengono restituite così come sono nell’API dei dettagli della conversazione e nei webhook post-chiamata, incluse le variabili system__ riportate di seguito. Analizza dynamic_variables come una mappa di valori JSON. Non rifiutare chiavi o tipi di valori che non riconosci, perché potrebbero essere aggiunte nuove variabili system__.

Variabili dinamiche di sistema

Il tuo agente ha accesso a variabili integrate system__* in ogni conversazione, senza configurazione runtime. Queste variabili hanno il prefisso dello spazio dei nomi riservato system__ e si aggiornano automaticamente man mano che la conversazione procede. Le variabili dinamiche personalizzate non possono usare il prefisso system__ né sovrascrivere le variabili di sistema.

Le variabili contrassegnate da † cambiano tra un turno e l’altro. Inserirle nel testo del prompt può impedire il caching del prompt; consulta le Best practice per le alternative.

Identità dell’agente e della conversazione

VariabileTipoDescrizioneEsempio
system__agent_idstringIdentificatore univoco dell’agente che ha avviato la conversazione. Non cambia mai durante una conversazione."agent_8401kp8bt0jdf14rzzcv5veq94yg"
system__current_agent_idstringIdentificatore univoco dell’agente attualmente attivo. Si aggiorna quando la conversazione viene trasferita a un altro agente."agent_8401kp8bt0jdf14rzzcv5veq94yg"
system__conversation_idstringIdentificatore univoco della conversazione di ElevenLabs."conv_1801kp8qtb2begztn7zyf446v4jk"
system__user_idstring | nullID utente fornito dal client per il tracciamento e l’analisi. Non deve essere considerato affidabile per l’autenticazione."G6yhJW8MktQdhUquvXD1iKpPHql2"
system__initiator_idstring | nullIdentificatore corrispondente al metodo di autenticazione usato per avviare la conversazione."user_1801kp8qtb2begztn7zyf446v4jk"
system__channelstringCanale attraverso cui è stata avviata la conversazione."slack_integration"
system__is_text_onlybooleantrue quando la conversazione è in esecuzione in modalità solo testo (chat); false per le chiamate vocali.true
system__environmentstringAmbiente in cui è in esecuzione la conversazione, usato per risolvere le variabili d’ambiente."production"

Data, ora e fuso orario

VariabileTipoDescrizioneEsempio
system__timezonestring | nullFuso orario configurato (conversation_config.agent.prompt.timezone) o fuso orario IANA fornito dal chiamante. Per impostazione predefinita è UTC se non configurato."America/New_York"
system__time †stringData e ora correnti nel fuso orario configurato (%A, %H:%M %d %B %Y). Ricalcolato a ogni turno (cambia una volta al minuto)."Friday, 12:33 12 December 2025"
system__time_utc †stringTimestamp UTC corrente in formato ISO 8601. Ricalcolato a ogni turno."2025-12-12T12:33:45.123456+00:00"
system__time_datestringData corrente nel fuso orario configurato (o UTC se non impostato) (%A, %d %B %Y). Cambia una volta al giorno."Friday, 12 December 2025"
system__time_hourintegerOra corrente (0–23) nel fuso orario configurato (o UTC se non impostato). Cambia al massimo una volta all’ora.12
system__time_minute †integerMinuto corrente (0–59) nel fuso orario configurato (o UTC se non impostato). Cambia una volta al minuto.33
system__time_second †integerSecondo corrente (0–59) nel fuso orario configurato (o UTC se non impostato). Cambia a ogni turno.45

Telefonia e messaggistica

Queste variabili vengono compilate quando applicabile per i canali di telefonia e messaggistica:

VariabileTipoDescrizioneEsempio
system__caller_idstring | nullNumero di telefono del chiamante (voce/SMS/WhatsApp/Amazon Connect)."+14155552671"
system__called_numberstring | nullNumero di telefono di destinazione chiamato."+18005551234"
system__call_sidstring | nullSID della chiamata Twilio (solo chiamate Twilio)."CA3498076234a8bbf65c8f09fb8ad7ac1b"
system__call_idstring | nullCall-ID SIP (solo chiamate tramite trunk SIP)."757f72cf-e80f-44f7-87d6-a961ffbf5b3d"

Stato della conversazione per turno

VariabileTipoDescrizioneEsempio
system__call_duration_secs †integerTempo di conversazione trascorso in secondi. Ricalcolato a ogni turno.142
system__agent_turns †integerNumero totale di turni dell’agente nella conversazione fino a questo momento. Aumenta a ogni turno.5
system__current_agent_turns †integerNumero di turni dell’agente corrente; viene reimpostato a 0 dopo un trasferimento dell’agente.3
system__current_subagent_turns †integerNumero di turni dell’agente nel nodo workflow corrente; viene reimpostato a 0 durante la transizione del nodo.2
system__conversation_history †stringTrascrizione della conversazione serializzata in JSON fino al turno corrente ({"entries": [{"role": "user", "message": "..."}]}). Consulta il formato della cronologia della conversazione.'{"entries": [...]}'
system__uploaded_file_ids †string[] | nullID di ogni file allegato dall’utente nella conversazione fino a questo momento, dal più vecchio. null finché non viene allegato un file. Consulta File caricati.["01a1c47f-1427-71ab-9898-775cce521078"]

Formato della cronologia della conversazione

La variabile system__conversation_history contiene un oggetto JSON con la seguente struttura:

{
"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\"}" }]
}
]
}

Ogni voce include un role ("user", "agent" o "tool") e uno dei seguenti elementi:

  • message: Il contenuto testuale del turno
  • tool_requests: Un array di chiamate agli strumenti effettuate dall’agente, con i valori dei parametri risolti
  • tool_results: Un array di risposte degli strumenti

Se il risultato di uno strumento o un parametro contiene una cronologia della conversazione annidata, viene oscurata con un segnaposto (ad esempio [conversation_history (5 turns)]) per evitare un’espansione ricorsiva illimitata.

Questa variabile è utile per passare il contesto della conversazione agli strumenti, come webhook o LLM personalizzati, oppure per includere la cronologia della conversazione nei prompt dei sotto-agenti durante i passaggi di consegne.

File caricati

system__uploaded_file_ids elenca gli ID dei file allegati dall’utente in chat, ad esempio nel widget o su WhatsApp. Si aggiorna a ogni turno, quindi un file allegato nel messaggio corrente è già nell’elenco quando l’agente chiama uno strumento.

Per elaborare un allegato mentre la conversazione è ancora attiva, associa l’elenco a un parametro array di uno strumento server, insieme a system__conversation_id. Se l’agente chiama lo strumento prima che l’utente abbia allegato un file, il parametro riceve un elenco vuoto.

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

Il tuo server scarica quindi ogni file con la tua chiave API:

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

La risposta è il file originale, con il relativo Content-Type (ad esempio image/jpeg o application/pdf). Un ID file che non appartiene alla conversazione restituisce 404. L’ultimo ID dell’elenco corrisponde al caricamento più recente.

Variabili dinamiche segrete

Le variabili dinamiche segrete vengono compilate nello stesso modo delle normali variabili dinamiche, ma indicano a ElevenAgents che devono essere utilizzate solo negli header delle variabili dinamiche e non devono mai essere inviate a un provider LLM come parte del prompt di sistema o del primo messaggio di un agente.

Usa le variabili dinamiche segrete per token di autenticazione o ID privati che non devono essere inviati a un LLM. Per creare una variabile dinamica segreta, anteponi secret__ alla variabile dinamica.

I valori segreti vengono archiviati in forma oscurata, quindi l’API delle conversazioni li restituisce come <REDACTED>. I webhook di trascrizione post-chiamata forniscono i valori originali, quindi assicurati che il tuo endpoint webhook li gestisca come segreti. Non usare il prefisso secret__ per i valori che devi rileggere dall’API delle conversazioni. Passali come normali variabili dinamiche oppure passa un identificatore non sensibile e recupera il valore sensibile nel tuo sistema.

Aggiornare le variabili dinamiche dagli strumenti

Le chiamate agli strumenti possono creare o aggiornare variabili dinamiche se restituiscono un oggetto JSON valido. Per specificare ciò che deve essere estratto, imposta i path degli oggetti usando la notazione con punti. Se il campo o il path non esiste, non viene aggiornato nulla.

Esempio di oggetto di risposta e notazione con punti:

  • Status corrisponde al path: response.status
  • L’email del primo utente nell’array users corrisponde al path: 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"
}
]
}
}

Per aggiornare una variabile dinamica con l’email del primo utente, imposta l’assegnazione come segue.

Parametri della query

Le assegnazioni vengono configurate per ogni strumento webhook; consulta le assegnazioni degli strumenti nel Riferimento API.

Guida

Prerequisiti:

1

Definisci le variabili dinamiche nei prompt

Aggiungi le variabili usando doppie parentesi graffe {{variable_name}} in:

  • Prompt di sistema
  • Primi messaggi
  • Parametri degli strumenti

Variabili dinamiche nei messaggi

Variabili dinamiche nei messaggi

2

Definisci le variabili dinamiche negli strumenti

Puoi anche definire variabili dinamiche nella configurazione dello strumento. Per creare una nuova variabile dinamica, imposta il tipo di valore su Variabile dinamica e fai clic sul pulsante +.

Impostazione dei segnaposto

Impostazione dei segnaposto

3

Imposta i segnaposto

Configura i valori predefiniti per i test senza passare variabili al runtime.

Imposta i valori predefiniti per ogni variabile dinamica nella dashboard dell’agente.

Impostazione dei segnaposto

4

Passa le variabili al runtime

Quando avvii una conversazione, fornisci le variabili dinamiche nel tuo codice:

Assicurati di aver installato l’SDK più recente.

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

Integrazione della pagina pubblica per parlare con l’agente

La pagina pubblica per parlare con l’agente supporta le variabili dinamiche tramite parametri URL, consentendoti di personalizzare le conversazioni quando condividi i link degli agenti. È particolarmente utile per incorporare agenti personalizzati in siti web, email o campagne di marketing.

Metodi dei parametri URL

Esistono due metodi per passare variabili dinamiche alla pagina pubblica per parlare con l’agente:

Metodo 1: JSON codificato in Base64

Passa le variabili come oggetto JSON codificato in base64 usando il parametro vars:

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

Il parametro vars contiene JSON codificato in base64:

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

Metodo 2: Parametri query singoli

Passa le variabili usando parametri query con prefisso var_:

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

Precedenza dei parametri

Quando entrambi i metodi vengono usati contemporaneamente, i singoli parametri var_ hanno la precedenza sulle variabili codificate in base64, per evitare conflitti:

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

In questo esempio, user_name sarà "John" (da var_user_name) anziché "Jane" (da vars codificato in base64).

Esempi di implementazione

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

Best practice

Le variabili nel prompt di sistema, nei nodi dei workflow e nelle procedure vengono risolte a ogni turno. Se un valore cambia tra un turno e l’altro, il prompt non può essere memorizzato nella cache, aumentando costi e latenza. {{system__time_utc}} e {{system__time_second}} cambiano a ogni turno; {{system__time}} e {{system__time_minute}} cambiano ogni minuto.

Per fornire all’agente la data e l’ora correnti, imposta un fuso orario con il pulsante del fuso orario nell’editor del Prompt di sistema (conversation_config.agent.prompt.timezone) invece di inserire {{system__time}} o {{system__time_utc}} nel testo del prompt. Quando è impostato un fuso orario, la piattaforma aggiunge la data e l’ora correnti al di fuori del prefisso del prompt memorizzato nella cache, così il prompt di sistema resta nella cache tra un turno e l’altro. Senza un fuso orario, l’agente non riceve la data e l’ora correnti.

Se il prompt richiede la data o l’ora in linea, combina {{system__time_date}}, {{system__time_hour}} e {{system__timezone}} (ad esempio, Oggi è {{system__time_date}}, ore {{system__time_hour}} ({{system__timezone}})). Queste variabili cambiano al massimo una volta all’ora.

Se uno strumento richiede un valore contrassegnato con †, collegalo al parametro o all’header dello strumento invece di inserirlo nel prompt. I parametri degli strumenti vengono risolti solo quando lo strumento viene chiamato, quindi non influiscono sulla cache del prompt. L’LLM vede già la conversazione, quindi {{system__conversation_history}} è raramente necessario nei prompt.

Se il prompt controlla contatori di turni come {{system__agent_turns}}, valuta queste alternative. Usa first_message per saluti iniziali o comunicazioni statiche.

Per il comportamento della prima risposta, puoi formulare l’istruzione in base alla cronologia della conversazione (ad esempio, “Nella tua prima risposta, quando non hai ancora salutato il chiamante…”). Questo si basa sul fatto che l’LLM segua l’istruzione, quindi testalo con il tuo modello e mantieni il contatore di turni se i risultati sono meno affidabili.

Se il contatore decide solo quando diramare il flusso o inoltrare la conversazione, una condizione di espressione su un edge del workflow o un’espressione del passaggio If in una procedura strutturata (come system__agent_turns >= 5) può gestirlo al di fuori del prompt. Questo non copre i casi in cui l’LLM necessita del valore stesso.

Aggiungi il prefisso secret__ ai token di autenticazione e alle chiavi API affinché possano essere collegati solo agli header degli strumenti e non vengano mai inviati all’LLM. Poiché i valori secret__ sono oscurati come <REDACTED> nell’API delle conversazioni (i webhook di trascrizione post-chiamata ricevono comunque i valori originali), passa come variabili dinamiche normali i valori che devi leggere nuovamente dall’API delle conversazioni oppure passa un identificatore non sensibile e recupera il valore sensibile nel tuo sistema.

system__user_id viene fornito dal client per il monitoraggio e l’analisi e non è verificato da ElevenAgents. Verifica l’identità del chiamante tramite un webhook di avvio della conversazione, un token firmato in una variabile header secret__ o una chiamata a uno strumento di verifica prima di esporre i dati dell’account.

Imposta valori predefiniti in dynamic_variable_placeholders per ogni variabile personalizzata usata nei prompt, nei primi messaggi e negli strumenti. Le anteprime delle conversazioni nella dashboard e i test di simulazione non eseguono i webhook di avvio della conversazione, quindi durante i test le variabili non impostate rimangono come segnaposto letterali {{variable_name}}.

Risoluzione dei problemi

Verifica che:

  • I nomi delle variabili corrispondano esattamente (con distinzione tra maiuscole e minuscole)
  • Le variabili usino doppie parentesi graffe: {{variable_name}}
  • Le variabili siano incluse nel tuo oggetto dynamic_variables

Assicurati che:

  • I valori delle variabili corrispondano al tipo previsto
  • I valori siano solo stringhe, numeri o valori booleani