Dynamic variables

Dynamic variables allow you to inject runtime values into your agent’s messages, system prompts, and tools. This enables you to personalize each conversation with user-specific data without creating multiple agents.

Overview

Dynamic variables can be integrated into multiple aspects of your agent:

• System prompts to customize behavior and context
• First messages to personalize greetings
• Tool parameters to pass user-specific data

Here are a few examples where dynamic variables are useful:

• Personalizing greetings with user names
• Including account details in responses
• Passing data to tool calls
• Customizing behavior based on subscription tiers
• Accessing system information like conversation ID or call duration

System dynamic variables

Your agent has access to these automatically available system variables:

• system__agent_id - Unique agent identifier
• system__caller_id - Caller’s phone number (voice calls only)
• system__called_number - Destination phone number (voice calls only)
• system__call_duration_secs - Call duration in seconds
• system__time_utc - Current UTC time (ISO format)
• system__conversation_id - Unique conversation identifier

System variables:

• Are available without runtime configuration
• Are prefixed with system__ (reserved prefix)
• In system prompts: Set once at conversation start (value remains static)
• In tool calls: Updated at execution time (value reflects current state)

Guide

Prerequisites

• An ElevenLabs account
• A configured ElevenLabs Conversational Agent (create one here)

1
import os
2
import signal
3
from elevenlabs.client import ElevenLabs
4
from elevenlabs.conversational_ai.conversation import Conversation, ConversationConfig
5
from elevenlabs.conversational_ai.default_audio_interface import DefaultAudioInterface
6
7
agent_id = os.getenv("AGENT_ID")
8
api_key = os.getenv("ELEVENLABS_API_KEY")
9
client = ElevenLabs(api_key=api_key)
10
11
dynamic_vars = {
12
  "user_name": "Angelo",
13
}
14
15
config = ConversationConfig(
16
  dynamic_variables=dynamic_vars
17
)
18
19
conversation = Conversation(
20
  client,
21
  agent_id,
22
  config=config,
23
  # Assume auth is required when API_KEY is set.
24
  requires_auth=bool(api_key),
25
  # Use the default audio interface.
26
  audio_interface=DefaultAudioInterface(),
27
  # Simple callbacks that print the conversation to the console.
28
  callback_agent_response=lambda response: print(f"Agent: {response}"),
29
  callback_agent_response_correction=lambda original, corrected: print(f"Agent: {original} -> {corrected}"),
30
  callback_user_transcript=lambda transcript: print(f"User: {transcript}"),
31
  # Uncomment the below if you want to see latency measurements.
32
  # callback_latency_measurement=lambda latency: print(f"Latency: {latency}ms"),
33
)
34
35
conversation.start_session()
36
37
signal.signal(signal.SIGINT, lambda sig, frame: conversation.end_session())

Supported Types

Dynamic variables support these value types:

Troubleshooting