Skip to main content
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 OrderDescription
1. Provider RegistryDynamic providers (for non-dotted names only)
2. Dict TraversalNavigate nested dicts using dot notation
3. Graceful FallbackKeep original {{...}} if not found

​
Configuration Options

PatternTypeDescription
{{name}}strFlat variable name - checks providers then static variables
{{obj.prop}}strDot notation - traverses nested dicts only
{{missing}}strMissing 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

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"}
}
Organize related data into logical groupings for cleaner templates.
# 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.
# 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.
# Reasonable depth
{{config.database.host}}

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

Agent Configuration

Using variables in agent setup

Workflow Variables

Variable passing between workflow steps