Variabili dinamiche
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:
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
Data, ora e fuso orario
Telefonia e messaggistica
Queste variabili vengono compilate quando applicabile per i canali di telefonia e messaggistica:
Stato della conversazione per turno
Formato della cronologia della conversazione
La variabile system__conversation_history contiene un oggetto JSON con la seguente struttura:
Ogni voce include un role ("user", "agent" o "tool") e uno dei seguenti elementi:
message: Il contenuto testuale del turnotool_requests: Un array di chiamate agli strumenti effettuate dall’agente, con i valori dei parametri risoltitool_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.
Il tuo server scarica quindi ogni file con la tua chiave API:
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
Per aggiornare una variabile dinamica con l’email del primo utente, imposta l’assegnazione come segue.

Le assegnazioni vengono configurate per ogni strumento webhook; consulta le assegnazioni degli strumenti nel Riferimento API.
Guida
Prerequisiti:
- Un account ElevenLabs
- Un agente ElevenAgents configurato (segui la guida rapida per crearne uno)
Definisci le variabili dinamiche nei prompt
Aggiungi le variabili usando doppie parentesi graffe {{variable_name}} in:
- Prompt di sistema
- Primi messaggi
- Parametri degli strumenti


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 +.


Imposta i segnaposto
Configura i valori predefiniti per i test senza passare variabili al runtime.
Aggiorna dalla dashboard
Aggiorna tramite la CLI
Aggiorna tramite l'API
Imposta i valori predefiniti per ogni variabile dinamica nella dashboard dell’agente.

Passa le variabili al runtime
Quando avvii una conversazione, fornisci le variabili dinamiche nel tuo codice:
Assicurati di aver installato l’SDK più recente.
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:
Il parametro vars contiene JSON codificato in base64:
Metodo 2: Parametri query singoli
Passa le variabili usando parametri query con prefisso var_:
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:
In questo esempio, user_name sarà "John" (da var_user_name) anziché "Jane" (da vars codificato in base64).
Esempi di implementazione
Generazione dell'URL in JavaScript
Generazione dell'URL in Python
Costruzione manuale dell'URL
Best practice
Imposta un fuso orario invece di inserire l'ora corrente nei prompt
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.
Collega le variabili di stato in tempo reale ai parametri e agli header degli strumenti
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.
Valuta alternative ai contatori di turni 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.
Usa secret__ solo per i valori che rimangono negli header degli strumenti
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.
Non fare affidamento su system__user_id per l'autenticazione
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.
Configura i segnaposto per i test e le anteprime
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
Le variabili non vengono sostituite
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
Errori di tipo
Assicurati che:
- I valori delle variabili corrispondano al tipo previsto
- I valori siano solo stringhe, numeri o valori booleani