Variables dynamiques
Transmettez des valeurs d’exécution pour personnaliser le comportement de votre agent.
Les variables dynamiques vous permettent d’injecter des valeurs d’exécution dans les messages, les prompts système et les outils de votre agent. Vous pouvez ainsi personnaliser chaque conversation avec des données propres à l’utilisateur, sans concevoir plusieurs agents.
Vue d’ensemble
Les variables dynamiques peuvent être intégrées à plusieurs aspects de votre agent :
- Aux prompts système pour personnaliser le comportement et le contexte
- Aux premiers messages pour personnaliser les salutations
- Aux paramètres et en-têtes des outils pour transmettre des données propres à l’utilisateur
Voici quelques exemples où les variables dynamiques sont utiles :
- Personnaliser les salutations avec les noms des utilisateurs
- Inclure les détails du compte dans les réponses
- Transmettre des données aux appels d’outils
- Personnaliser le comportement selon les niveaux d’abonnement
- Accéder aux informations système comme l’ID de la conversation ou la durée de l’appel
Une variable dynamique peut contenir n’importe quelle valeur JSON :
Lorsqu’une liste ou un objet est inséré dans un prompt, une URL ou un autre modèle de texte, il est inséré sous forme de texte JSON. Un paramètre d’outil associé à une variable de liste reçoit la liste elle-même.
Les variables dynamiques sont renvoyées telles quelles dans l’API des détails de conversation et dans les webhooks post-appel, y compris les variables system__ ci-dessous. Analysez dynamic_variables comme un mappage de valeurs JSON. Ne refusez pas les clés ni les types de valeurs que vous ne reconnaissez pas, car de nouvelles variables system__ peuvent être ajoutées.
Variables dynamiques système
Votre agent a accès à des variables system__* intégrées dans chaque conversation, sans configuration à l’exécution. Ces variables sont préfixées par l’espace de noms réservé system__ et se mettent automatiquement à jour au fil de la conversation. Les variables dynamiques personnalisées ne peuvent pas utiliser le préfixe system__ ni remplacer des variables système.
Les variables marquées d’un † changent entre les tours. Les placer dans le texte du prompt peut empêcher la mise en cache du prompt ; consultez les bonnes pratiques pour des alternatives.
Identité de l’agent et de la conversation
Heure et fuseau horaire
Téléphonie et messagerie
Ces variables sont renseignées lorsque cela s’applique aux canaux de téléphonie et de messagerie :
État de la conversation par tour
Format de l’historique de conversation
La variable system__conversation_history contient un objet JSON présentant la structure suivante :
Chaque entrée comprend un role ("user", "agent" ou "tool") et l’un des éléments suivants :
message: le contenu textuel du tourtool_requests: un tableau d’appels d’outils effectués par l’agent, avec les valeurs de paramètres résoluestool_results: un tableau de réponses d’outils
Si un résultat d’outil ou un paramètre contient un historique de conversation imbriqué, il est expurgé et remplacé par un espace réservé (tel que [conversation_history (5 turns)]) afin d’éviter une expansion récursive non limitée.
Cette variable est utile pour transmettre le contexte de la conversation aux outils, tels que les webhooks ou les LLM personnalisés, ou pour inclure l’historique de conversation dans les prompts des sous-agents lors des transferts.
Fichiers importés
system__uploaded_file_ids répertorie les ID des fichiers que l’utilisateur a joints dans le chat, par exemple dans le widget ou sur WhatsApp. Cette liste est mise à jour à chaque tour. Ainsi, un fichier joint au message actuel y figure déjà lorsque l’agent appelle un outil.
Pour traiter une pièce jointe alors que la conversation est toujours active, associez la liste à un paramètre de tableau d’un outil serveur, avec system__conversation_id. Si l’agent appelle l’outil avant que l’utilisateur ait joint un fichier, le paramètre reçoit une liste vide.
Votre serveur télécharge ensuite chaque fichier avec votre clé API :
La réponse est le fichier d’origine, avec son Content-Type (par exemple image/jpeg ou application/pdf). Un ID de fichier qui n’appartient pas à la conversation renvoie 404. Le dernier ID de la liste correspond à l’importation la plus récente.
Variables dynamiques secrètes
Les variables dynamiques secrètes sont renseignées de la même manière que les variables dynamiques normales, mais elles indiquent à ElevenAgents qu’elles ne doivent être utilisées que dans les en-têtes de variables dynamiques et ne doivent jamais être envoyées à un fournisseur de LLM dans le prompt système ou le premier message d’un agent.
Utilisez des variables dynamiques secrètes pour les jetons d’authentification ou les ID privés qui ne doivent pas être envoyés à un LLM. Pour créer une variable dynamique secrète, préfixez la variable dynamique avec secret__.
Les valeurs secrètes sont stockées de façon expurgée. L’API des conversations les renvoie donc sous la forme <REDACTED>.
Les webhooks de transcription post-appel transmettent les valeurs d’origine. Assurez-vous donc que votre endpoint de webhook
les traite comme des secrets. N’utilisez pas le préfixe secret__ pour les valeurs que vous devez relire depuis l’API
des conversations. Transmettez-les comme variables dynamiques ordinaires, ou transmettez un identifiant non sensible et
recherchez la valeur sensible dans votre propre système.
Mettre à jour les variables dynamiques depuis les outils
Les appels d’outils peuvent créer ou mettre à jour des variables dynamiques s’ils renvoient un objet JSON valide. Pour indiquer ce qui doit être extrait, définissez les chemins d’objet avec la notation par points. Si le champ ou le chemin n’existe pas, aucune mise à jour n’est effectuée.
Exemple d’objet de réponse et de notation par points :
- Le statut correspond au chemin :
response.status - L’email du premier utilisateur dans le tableau users correspond au chemin :
response.users.0.email
Pour mettre à jour une variable dynamique avec l’email du premier utilisateur, définissez l’affectation comme suit.

Les affectations sont configurées sur chaque outil webhook ; consultez les affectations d’outils dans le Guide de l’API.
Guide
Prérequis :
- Un compte ElevenLabs
- Un agent ElevenAgents configuré (suivez le guide de démarrage rapide pour en concevoir un)
Définir des variables dynamiques dans les prompts
Ajoutez des variables avec des doubles accolades {{variable_name}} dans vos :
- Prompts système
- Premiers messages
- Paramètres d’outils


Définir des variables dynamiques dans les outils
Vous pouvez également définir des variables dynamiques dans la configuration de l’outil.
Pour créer une variable dynamique, définissez le type de valeur sur Variable dynamique et cliquez sur le bouton +.


Définir des espaces réservés
Configurez des valeurs par défaut pour effectuer des tests sans transmettre de variables à l’exécution.
Mettre à jour depuis le Dashboard
Mettre à jour via la CLI
Mettre à jour via l'API
Définissez les valeurs par défaut de chaque variable dynamique dans le Dashboard de l’agent.

Transmettre les variables à l'exécution
Lors du démarrage d’une conversation, fournissez les variables dynamiques dans votre code :
Assurez-vous d’avoir installé la dernière version du SDK.
Intégration à la page publique de conversation
La page publique de conversation prend en charge les variables dynamiques via des paramètres d’URL. Vous pouvez ainsi personnaliser les conversations lorsque vous partagez des liens d’agent. Cette fonctionnalité est particulièrement utile pour intégrer des agents personnalisés à des sites web, des emails ou des campagnes marketing.
Méthodes de paramètres d’URL
Deux méthodes permettent de transmettre des variables dynamiques à la page publique de conversation :
Méthode 1 : JSON encodé en Base64
Transmettez les variables sous la forme d’un objet JSON encodé en Base64 avec le paramètre vars :
Le paramètre vars contient du JSON encodé en Base64 :
Méthode 2 : paramètres de requête individuels
Transmettez les variables avec des paramètres de requête préfixés par var_ :
Priorité des paramètres
Lorsque les deux méthodes sont utilisées simultanément, les paramètres var_ individuels priment sur les variables encodées en Base64 afin d’éviter les conflits :
Dans cet exemple, user_name sera "John" (depuis var_user_name) au lieu de "Jane" (depuis vars encodé en Base64).
Exemples d’implémentation
Génération d'URL en JavaScript
Génération d'URL en Python
Construction manuelle de l'URL
Bonnes pratiques
Définissez un fuseau horaire au lieu d'ajouter l'heure actuelle aux prompts
Les variables du prompt système, des nœuds de workflow et des procédures sont résolues à chaque tour. Si une valeur change entre deux tours, le prompt ne peut pas être mis en cache, ce qui augmente le coût et la latence. {{system__time_utc}} et {{system__time_second}} changent à chaque tour ; {{system__time}} et {{system__time_minute}} changent chaque minute.
Pour fournir à l’agent la date et l’heure actuelles, définissez un fuseau horaire à l’aide du bouton de fuseau horaire dans l’éditeur de prompt système (conversation_config.agent.prompt.timezone) au lieu d’ajouter {{system__time}} ou {{system__time_utc}} au texte du prompt. Lorsqu’un fuseau horaire est défini, la plateforme ajoute la date et l’heure actuelles en dehors du préfixe du prompt mis en cache, afin que votre prompt système reste mis en cache d’un tour à l’autre. Sans fuseau horaire, l’agent ne reçoit pas la date et l’heure actuelles.
Si votre prompt doit inclure la date ou l’heure, combinez {{system__time_date}}, {{system__time_hour}} et {{system__timezone}} (par exemple, Nous sommes le {{system__time_date}}, il est {{system__time_hour}} h ({{system__timezone}})). Ces variables changent au maximum une fois par heure.
Liez les variables d'état en direct aux paramètres et en-têtes des outils
Si un outil nécessite une valeur marquée d’un †, liez-la au paramètre ou à l’en-tête de l’outil au lieu de l’ajouter au prompt. Les paramètres d’outil ne sont résolus que lorsque l’outil est appelé, ils n’affectent donc pas la mise en cache du prompt. Le LLM a déjà accès à la conversation, {{system__conversation_history}} est donc rarement nécessaire dans les prompts.
Envisagez des alternatives aux compteurs de tours dans les prompts
Si votre prompt vérifie des compteurs de tours tels que {{system__agent_turns}}, envisagez les alternatives suivantes. Utilisez first_message pour les salutations d’ouverture ou les divulgations statiques.
Pour le comportement de première réponse, vous pouvez formuler l’instruction autour de l’historique de la conversation (par exemple, « Lors de votre première réponse, lorsque vous n’avez pas encore salué l’appelant… »). Cette approche repose sur le respect de l’instruction par le LLM. Testez-la donc avec votre modèle et conservez le compteur de tours si les résultats sont moins fiables.
Si le compteur détermine uniquement quand créer une branche ou effectuer un transfert, une condition d’expression d’arête de workflow ou une expression d’étape If de procédure structurée (telle que system__agent_turns >= 5) peut le gérer en dehors du prompt. Cela ne couvre pas les cas où le LLM a besoin de la valeur elle-même.
Utilisez secret__ uniquement pour les valeurs qui restent dans les en-têtes d'outil
Préfixez les jetons d’authentification et les clés API avec secret__ afin qu’ils puissent uniquement être liés aux en-têtes d’outil et ne soient jamais envoyés au LLM. Comme les valeurs secret__ sont masquées par <REDACTED> dans l’API des conversations (les webhooks de transcription après appel reçoivent toujours les valeurs d’origine), transmettez comme variables dynamiques standard les valeurs que vous devez relire depuis l’API des conversations, ou transmettez un identifiant non sensible et recherchez la valeur sensible dans votre propre système.
Ne vous fiez pas à system__user_id pour l'authentification
system__user_id est fourni par le client à des fins de suivi et d’analyse, et n’est pas vérifié par ElevenAgents. Vérifiez l’identité de l’appelant via un webhook de démarrage de conversation, un jeton signé dans une variable d’en-tête secret__, ou un appel d’outil de vérification avant d’exposer des données de compte.
Configurez des valeurs de substitution pour les tests et les aperçus
Définissez des valeurs par défaut dans dynamic_variable_placeholders pour chaque variable personnalisée utilisée dans vos prompts, vos premiers messages et vos outils. Les aperçus de conversations dans le Dashboard et les tests de simulation n’exécutent pas les webhooks de démarrage de conversation. Les variables non définies restent donc des valeurs de substitution littérales {{variable_name}} pendant les tests.
Résolution des problèmes
Variables non remplacées
Vérifiez que :
- Les noms de variables correspondent exactement, en respectant la casse
- Les variables utilisent des doubles accolades :
{{variable_name}} - Les variables sont incluses dans votre objet
dynamic_variables
Erreurs de type
Assurez-vous que :
- Les valeurs des variables correspondent au type attendu
- Les valeurs sont uniquement des chaînes de caractères, des nombres ou des booléens