> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Variable Substitution
> Dynamic variable substitution with {{var}} and {{var.property}} syntax
Variable substitution enables dynamic content replacement using `{{variable}}` placeholders that resolve at runtime, supporting both flat variables and dot-notation for nested data structures.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
subgraph "Variable Resolution"
A[📝 {{user.name}}] --> B[🔍 Look up]
B --> C[📊 variables["user"]["name"]]
C --> D[✅ "Alice"]
end
classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
classDef process fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef output fill:#10B981,stroke:#7C90A0,color:#fff
class A input
class B,C process
class D output
```
## Quick Start
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
agent = Agent(
name="Greeting Agent",
instructions="Say hello to {{name}}",
variables={"name": "World"}
)
result = agent.start("Greet the user")
# Instructions become: "Say hello to World"
```
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
agent = Agent(
name="Profile Agent",
instructions="Welcome {{user.name}}! Your role is {{user.role}}",
variables={
"user": {
"name": "Alice",
"role": "admin",
"settings": {"theme": "dark"}
}
}
)
result = agent.start("Welcome user")
# Instructions become: "Welcome Alice! Your role is admin"
```
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
agent = Agent(
name="Flexible Agent",
instructions="Process {{data.value}} or use {{fallback}} if missing",
variables={
"data": {"other": "something"}, # Missing 'value' key
"fallback": "default"
}
)
result = agent.start("Process data")
# Instructions become: "Process {{data.value}} or use default if missing"
# Note: {{data.value}} remains unchanged since 'value' key doesn't exist
```
***
## How It Works
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
A[📝 Input Text] --> B{🔍 Has {{var}}?}
B -->|No| C[✅ Return as-is]
B -->|Yes| D{📊 Dotted name?}
D -->|No| E[🔍 Provider Registry]
D -->|Yes| F[🗂️ Dict Traversal]
E --> G{✅ Found?}
F --> G
G -->|Yes| H[🔄 Replace]
G -->|No| I[📝 Keep Original]
H --> J[✅ Result]
I --> J
classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
classDef process fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef output fill:#10B981,stroke:#7C90A0,color:#fff
class A input
class B,D,E,F,G process
class C,H,I,J output
```
| Resolution Order | Description |
| ------------------------ | --------------------------------------------- |
| **1. Provider Registry** | Dynamic providers (for non-dotted names only) |
| **2. Dict Traversal** | Navigate nested dicts using dot notation |
| **3. Graceful Fallback** | Keep original `{{...}}` if not found |
***
## Configuration Options
| Pattern | Type | Description |
| -------------- | ----- | ------------------------------------------------------------ |
| `{{name}}` | `str` | Flat variable name - checks providers then static variables |
| `{{obj.prop}}` | `str` | Dot notation - traverses nested dicts only |
| `{{missing}}` | `str` | Missing variables remain as literal text (graceful fallback) |
**Traversal Rules:**
* Only **dict** objects are traversed (not lists, objects, or attributes)
* Provider registry is consulted **only for non-dotted names**
* Missing segments result in graceful fallback (no errors)
***
## Common Patterns
### Pattern 1: User Configuration
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
agent = Agent(
instructions="Hello {{user.name}}! Theme: {{user.settings.theme}}",
variables={
"user": {
"name": "Bob",
"settings": {
"theme": "light",
"notifications": True
}
}
}
)
```
### Pattern 2: API Endpoint Templates
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
variables = {
"api": {
"base_url": "https://api.example.com",
"version": "v1",
"endpoints": {
"users": "/users",
"posts": "/posts"
}
}
}
template = "{{api.base_url}}/{{api.version}}{{api.endpoints.users}}"
# Resolves to: "https://api.example.com/v1/users"
```
### Pattern 3: Multi-Level Data Access
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
variables = {
"company": {
"departments": {
"engineering": {
"team_lead": "Charlie",
"budget": 100000
}
}
}
}
instruction = "Contact {{company.departments.engineering.team_lead}}"
# Resolves to: "Contact Charlie"
```
***
## Best Practices
Choose clear, descriptive names that make templates self-documenting.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Good
variables = {
"user": {"name": "Alice", "role": "admin"},
"project": {"name": "Dashboard", "deadline": "2024-01-15"}
}
# Avoid
variables = {
"u": {"n": "Alice", "r": "admin"},
"p": {"n": "Dashboard", "d": "2024-01-15"}
}
```
Organize related data into logical groupings for cleaner templates.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Organized structure
variables = {
"user": {
"profile": {"name": "Bob", "email": "bob@example.com"},
"preferences": {"theme": "dark", "language": "en"}
},
"system": {
"version": "1.2.0",
"environment": "production"
}
}
```
Design templates that degrade gracefully when optional data is missing.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Template with fallback
template = "Welcome {{user.name}}! {{user.title}} is optional."
# Works with partial data
variables = {"user": {"name": "Carol"}}
# Result: "Welcome Carol! {{user.title}} is optional."
```
Keep dot-notation paths reasonably short for maintainability.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Reasonable depth
{{config.database.host}}
# Too deep - consider flattening
{{app.modules.auth.providers.oauth.google.client_id}}
```
***
## Related
Using variables in agent setup
Variable passing between workflow steps