Passer à la navigation

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 :

Chaîne
Valeurs textuelles
Nombre
Valeurs numériques
Booléen
Valeurs vrai/faux
Liste
Tableaux de toutes valeurs JSON
Objet
Données clé-valeur imbriquées

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

VariableTypeDescriptionExemple
system__agent_idstringIdentifiant unique de l’agent qui a démarré la conversation. Ne change jamais au cours d’une conversation."agent_8401kp8bt0jdf14rzzcv5veq94yg"
system__current_agent_idstringIdentifiant unique de l’agent actuellement actif. Se met à jour lorsque la conversation est transférée à un autre agent."agent_8401kp8bt0jdf14rzzcv5veq94yg"
system__conversation_idstringIdentifiant unique de la conversation ElevenLabs."conv_1801kp8qtb2begztn7zyf446v4jk"
system__user_idstring | nullID utilisateur fourni par le client à des fins de suivi et d’analyse. Ne doit pas être utilisé pour l’authentification."G6yhJW8MktQdhUquvXD1iKpPHql2"
system__initiator_idstring | nullIdentifiant correspondant à la méthode d’authentification utilisée pour démarrer la conversation."user_1801kp8qtb2begztn7zyf446v4jk"
system__channelstringCanal par lequel la conversation a été démarrée."slack_integration"
system__is_text_onlybooleantrue lorsque la conversation se déroule en mode texte uniquement (chat) ; false pour les appels téléphoniques.true
system__environmentstringEnvironnement dans lequel se déroule la conversation, utilisé pour résoudre les variables d’environnement."production"

Heure et fuseau horaire

VariableTypeDescriptionExemple
system__timezonestring | nullFuseau horaire configuré (conversation_config.agent.prompt.timezone) ou fuseau horaire IANA fourni par l’appelant. UTC par défaut s’il n’est pas défini."America/New_York"
system__time †stringDate et heure actuelles dans le fuseau horaire configuré (%A, %H:%M %d %B %Y). Réévaluées à chaque tour (changent une fois par minute)."Friday, 12:33 12 December 2025"
system__time_utc †stringHorodatage UTC actuel au format ISO 8601. Réévalué à chaque tour."2025-12-12T12:33:45.123456+00:00"
system__time_datestringDate actuelle dans le fuseau horaire configuré (ou UTC si aucun n’est défini) (%A, %d %B %Y). Change une fois par jour."Friday, 12 December 2025"
system__time_hourintegerHeure actuelle (0–23) dans le fuseau horaire configuré (ou UTC si aucun n’est défini). Change au plus une fois par heure.12
system__time_minute †integerMinute actuelle (0–59) dans le fuseau horaire configuré (ou UTC si aucun n’est défini). Change une fois par minute.33
system__time_second †integerSeconde actuelle (0–59) dans le fuseau horaire configuré (ou UTC si aucun n’est défini). Change à chaque tour.45

Téléphonie et messagerie

Ces variables sont renseignées lorsque cela s’applique aux canaux de téléphonie et de messagerie :

VariableTypeDescriptionExemple
system__caller_idstring | nullNuméro de téléphone de l’appelant (téléphone/SMS/WhatsApp/Amazon Connect)."+14155552671"
system__called_numberstring | nullNuméro de téléphone appelé."+18005551234"
system__call_sidstring | nullSID d’appel Twilio (appels Twilio uniquement)."CA3498076234a8bbf65c8f09fb8ad7ac1b"
system__call_idstring | nullID d’appel SIP (appels via trunk SIP uniquement)."757f72cf-e80f-44f7-87d6-a961ffbf5b3d"

État de la conversation par tour

VariableTypeDescriptionExemple
system__call_duration_secs †integerTemps écoulé de la conversation en secondes. Réévalué à chaque tour.142
system__agent_turns †integerNombre total de tours de l’agent dans la conversation jusqu’à présent. Augmente à chaque tour.5
system__current_agent_turns †integerNombre de tours de l’agent actuel ; revient à 0 après un transfert d’agent.3
system__current_subagent_turns †integerNombre de tours de l’agent dans le nœud de workflow actuel ; revient à 0 lors d’une transition de nœud.2
system__conversation_history †stringTranscription de la conversation sérialisée en JSON jusqu’au tour actuel ({"entries": [{"role": "user", "message": "..."}]}). Consultez le format de l’historique de conversation.'{"entries": [...]}'
system__uploaded_file_ids †string[] | nullID de chaque fichier joint par l’utilisateur dans la conversation jusqu’à présent, du plus ancien au plus récent. null jusqu’à ce qu’un fichier soit joint. Consultez les fichiers importés.["01a1c47f-1427-71ab-9898-775cce521078"]

Format de l’historique de conversation

La variable system__conversation_history contient un objet JSON présentant la structure suivante :

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

Chaque entrée comprend un role ("user", "agent" ou "tool") et l’un des éléments suivants :

  • message : le contenu textuel du tour
  • tool_requests : un tableau d’appels d’outils effectués par l’agent, avec les valeurs de paramètres résolues
  • tool_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.

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

Votre serveur télécharge ensuite chaque fichier avec votre clé API :

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

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
JSON
{
"response": {
"status": 200,
"message": "Successfully found 5 users",
"users": [
"user_1": {
"user_name": "test_user_1",
"email": "test_user_1@email.com"
}
]
}
}

Pour mettre à jour une variable dynamique avec l’email du premier utilisateur, définissez l’affectation comme suit.

Paramètres de requête

Les affectations sont configurées sur chaque outil webhook ; consultez les affectations d’outils dans le Guide de l’API.

Guide

Prérequis :

1

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

Variables dynamiques dans les messages

Variables dynamiques dans les messages

2

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éfinition des espaces réservés

Définition des espaces réservés

3

Définir des espaces réservés

Configurez des valeurs par défaut pour effectuer des tests sans transmettre de variables à l’exécution.

Définissez les valeurs par défaut de chaque variable dynamique dans le Dashboard de l’agent.

Définition des espaces réservés

4

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.

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

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 :

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

Le paramètre vars contient du JSON encodé en Base64 :

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

Méthode 2 : paramètres de requête individuels

Transmettez les variables avec des paramètres de requête préfixés par var_ :

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

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 :

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

Dans cet exemple, user_name sera "John" (depuis var_user_name) au lieu de "Jane" (depuis vars encodé en Base64).

Exemples d’implémentation

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

Bonnes pratiques

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.

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.

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.

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.

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.

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

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

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