Variables dynamiques

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 :

• Prompts système pour personnaliser le comportement et le contexte
• Premiers messages pour personnaliser les salutations
• Paramètres et en-têtes des outils pour transmettre des données propres à l’utilisateur

Voici quelques exemples d’utilisation des variables dynamiques :

• Personnaliser les salutations avec les noms des utilisateurs
• Inclure les détails du compte dans les réponses
• Transmettre des données lors d’appels d’outils
• Personnaliser le comportement selon les niveaux d’abonnement
• Accéder aux informations système telles que l’ID de conversation ou la durée de l’appel

Les variables dynamiques prennent en charge trois types de valeurs :

Variables dynamiques système

Votre agent a accès, dans chaque conversation et sans configuration à l’exécution, aux variables intégrées system__*. Ces variables sont préfixées par l’espace de noms réservé system__ et se mettent automatiquement à jour à mesure que la conversation progresse. Les variables dynamiques personnalisées ne peuvent pas utiliser le préfixe system__ ni remplacer les variables système.

Les variables marquées d’un † changent d’un tour à l’autre. Les placer dans le texte d’un prompt peut empêcher la mise en cache du prompt. Consultez les bonnes pratiques pour découvrir des alternatives.

Identité de l’agent et de la conversation

Heure et fuseau horaire

Téléphonie et messagerie

Ces variables sont renseignées lorsqu’elles s’appliquent aux canaux de téléphonie et de messagerie :

État de la conversation à chaque tour

Format de l’historique de conversation

La variable system__conversation_history contient un objet JSON ayant 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 le résultat d’un outil ou un paramètre contient un historique de conversation imbriqué, celui-ci est remplacé par un espace réservé (tel que [conversation_history (5 turns)]) afin d’éviter une expansion récursive illimitée.

Cette variable est utile pour transmettre le contexte de conversation à des outils, tels que des webhooks ou des LLM personnalisés, ou pour inclure l’historique de conversation dans les prompts de sous-agents lors des transferts.

Variables dynamiques secrètes

Les variables dynamiques secrètes sont renseignées de la même manière que les variables dynamiques normales, mais indiquent à ElevenAgents qu’elles doivent être utilisées uniquement dans les en-têtes de variables dynamiques et ne 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__.

Mettre à jour des variables dynamiques à partir d’outils

Les appels d’outils peuvent créer ou mettre à jour des variables dynamiques s’ils renvoient un objet JSON valide. Pour définir ce qui doit être extrait, définissez les chemins d’objet à l’aide de 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

{
  "response": {
    "status": 200,
    "message": "Successfully found 5 users",
    "users": [
      "user_1": {
        "user_name": "test_user_1",
        "email": "test_user_1@email.com"
      }
    ]
  }
}

Pour définir une variable dynamique sur l’email du premier utilisateur, configurez 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)

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 URL, ce qui vous permet de personnaliser les conversations lorsque vous partagez des liens d’agent. Cette fonctionnalité est particulièrement utile pour intégrer des agents personnalisés dans des sites web, des emails ou des campagnes marketing.

Méthodes de paramètres URL

Il existe deux méthodes pour transmettre des variables dynamiques à la page publique de conversation :

Méthode 1 : JSON encodé en Base64

Transmettez les variables sous forme d’objet JSON encodé en base64 à l’aide du 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 à l’aide de 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 sont prioritaires 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 aura la valeur "John" (provenant de var_user_name) au lieu de "Jane" (provenant de 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

Résolution des problèmes