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.

Quick Start

1. Simple Variable Substitution

   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"
   
2. Dot Notation for Nested Data

   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"
   
3. Dynamic Variables with Graceful Fallback

   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

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

agent = Agent(
    instructions="Hello {{user.name}}! Theme: {{user.settings.theme}}",
    variables={
        "user": {
            "name": "Bob",
            "settings": {
                "theme": "light",
                "notifications": True
            }
        }
    }
)

Pattern 2: API Endpoint Templates

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

variables = {
    "company": {
        "departments": {
            "engineering": {
                "team_lead": "Charlie",
                "budget": 100000
            }
        }
    }
}

instruction = "Contact {{company.departments.engineering.team_lead}}"
# Resolves to: "Contact Charlie"

---

Best Practices

Use Descriptive Variable Names

Choose clear, descriptive names that make templates self-documenting.

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

Structure Data Hierarchically

Organize related data into logical groupings for cleaner templates.

# Organized structure
variables = {
    "user": {
        "profile": {"name": "Bob", "email": "[e-mail]"},
        "preferences": {"theme": "dark", "language": "en"}
    },
    "system": {
        "version": "1.2.0",
        "environment": "production"
    }
}

Handle Missing Data Gracefully

Design templates that degrade gracefully when optional data is missing.

# 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."

Avoid Deep Nesting

Keep dot-notation paths reasonably short for maintainability.

# Reasonable depth
{{config.database.host}}

# Too deep - consider flattening
{{app.modules.auth.providers.oauth.google.client_id}}

---

Related

Agent Configuration

Using variables in agent setup

Workflow Variables

Variable passing between workflow steps