Dynamic Variables
Runtime Personalization · Agent Configuration Guide
Introduction
Dynamic variables allow you to inject runtime data into your agent’s
behavior without modifying or duplicating the agent itself.
Instead of hardcoding user-specific values into prompts or tools,
dynamic variables act as placeholders that are filled at conversation start
or during execution.
Dynamic variables make a single agent reusable across users, sessions,
plans, environments, and contexts.
Where Dynamic Variables Can Be Used
Dynamic variables can be referenced across multiple parts of an agent:
- System prompts to influence behavior and tone
- First messages to personalize greetings
- Tool inputs and parameters
- Headers or metadata passed during tool execution
This allows conversations to adapt dynamically without changing agent configuration.
Common Use Cases
- Personalizing responses with user names or identifiers
- Adjusting behavior based on subscription or plan type
- Passing account or session context into tools
- Including runtime metadata in responses
- Accessing conversation-level system information
Dynamic variables are ideal for data that changes per conversation
and should not be embedded permanently into prompts.
System-Provided Dynamic Variables
Some dynamic variables are automatically available at runtime.
These represent system and conversation metadata.
- system__agent_id — Identifier of the agent that initially started the conversation
- system__current_agent_id — Identifier of the agent that is currently handling the conversation
- system__conversation_id — Unique identifier assigned to the conversation session
- system__caller_id — Incoming caller’s phone number (voice conversations only)
- system__called_number — Phone number that was called by the user (voice conversations only)
- system__call_duration_secs — Total duration of the call in seconds
- system__time_utc — Current time in UTC format
- system__time — Current local time in a human-readable format
- system__timezone — Active timezone used for time formatting
- system__call_sid — Unique identifier of the voice call session
- system__agent_turns — Total number of responses generated by the initial agent during the conversation
- system__current_agent_turns — Number of responses generated by the currently active agent
- system__current_subagent_turns — Number of responses generated by the currently active sub-agent
These variables are read-only and available automatically.
Custom variables must not override them.
How Dynamic Variables Behave
Static vs Runtime Resolution
In system prompts and first messages, dynamic variables are resolved
once at the beginning of the conversation.
In tool execution, values may reflect the most recent runtime state.
Placeholder Format
Dynamic variables are referenced using double curly braces:
{{variable_name}}
If a variable is missing or undefined, the placeholder remains unresolved.
Updating Dynamic Variables from Tools
Tools can create or update dynamic variables by returning structured data.
Specific values can be extracted using object paths (dot notation)
when defining tool assignments.
If a path does not exist in the returned data,
the variable remains unchanged.
Supported Variable Types
- String — Text values
- Number — Numeric values
- Boolean — True or false values
Variable types should match their intended usage
to avoid runtime interpretation issues.
Best Practices
- Keep variable names clear and self-describing
- Avoid overusing dynamic variables unnecessarily
- Do not embed sensitive logic into prompts
- Validate runtime data before passing it
- Test conversations with missing and edge-case values
Do not rely on dynamic variables for enforcing security rules.
They are a personalization mechanism, not an authorization layer.
Final Notes
Dynamic variables enable scalable personalization without configuration sprawl.
When used correctly, they keep agents flexible, reusable,
and production-safe across diverse use cases.