Skip to main content
Custom variables are accessible in:
  • Agent prompts via custom Jinja2 templates
  • Custom tools via ctx.shared_state.custom_variables

​
Quick Start

from droidrun import DroidAgent, DroidrunConfig

# Define custom prompts that render variables
custom_prompts = {
    "manager_system": """
{{ instruction }}

{% if variables %}
Available variables:
{% for key, value in variables.items() %}
- {{ key }}: {{ value }}
{% endfor %}
{% endif %}
    """
}

# Create agent with variables
config = DroidrunConfig()

agent = DroidAgent(
    goal="Send email to recipient with subject",
    config=config,
    variables={"recipient": "john@example.com", "subject": "Update"},
    prompts=custom_prompts  # Required to see variables
)

result = await agent.run()
Important: Default prompts don’t render variables. You must provide custom prompts via the prompts parameter.

​
How Variables Work

When you pass variables to DroidAgent:
  1. Stored in DroidAgentState.custom_variables
  2. Passed to prompt templates as variables dict
  3. Rendered in Jinja2 templates via {% if variables %} blocks
  4. Available to all child agents throughout the workflow
Access Summary:
  • ✅ Agent prompts (via custom Jinja2 templates)
  • ✅ Agents can read and pass to tools as arguments
  • ✅ Custom tools (via ctx.shared_state.custom_variables)

​
Basic Usage

from droidrun import DroidAgent, DroidrunConfig

# Define variables
variables = {
    "recipient": "alice@example.com",
    "message": "Hello from Droidrun!"
}

# Custom prompt to render variables
custom_prompts = {
    "fast_agent_system": """
You are an agent that controls Android devices.

{% if variables %}
Available variables:
{% for key, value in variables.items() %}
- {{ key }}: {{ value }}
{% endfor %}
{% endif %}

Use these variables when executing tasks.
    """
}

# Create agent
config = DroidrunConfig()

agent = DroidAgent(
    goal="Send message to recipient",
    config=config,
    variables=variables,
    prompts=custom_prompts
)

result = await agent.run()

​
Available Prompt Keys

Customize these prompts to render variables:
  • manager_system - Manager agent system prompt
  • executor_system - Executor agent system prompt
  • fast_agent_system - FastAgent system prompt
  • fast_agent_user - FastAgent user prompt
  • scripter_system - Scripter agent system prompt

​
Accessing Variables in Custom Tools

Custom tools can access variables via the ctx keyword argument (an ActionContext instance injected automatically): 
from droidrun import DroidAgent, DroidrunConfig

async def send_notification(title: str, *, ctx, **kwargs):
    """Send a notification using channel from custom variables.

    Args:
        title: Notification title
        ctx: ActionContext (injected automatically by the registry)
    """
    # Access custom variables via ctx.shared_state
    channel = ctx.shared_state.custom_variables.get("notification_channel", "default")
    return f"Sent '{title}' to {channel}"

custom_tools = {
    "send_notification": {
        "parameters": {
            "title": {"type": "string", "required": True},
        },
        "description": "Send a notification with title. Usage: {\"action\": \"send_notification\", \"title\": \"Alert\"}",
        "function": send_notification
    }
}

config = DroidrunConfig()

agent = DroidAgent(
    goal="Send notification with title 'Alert'",
    config=config,
    custom_tools=custom_tools,
    variables={"notification_channel": "alerts"}
)

​
Use Cases

​
Parameterized Workflows

# Define reusable workflow with different variables
for user in ["alice@example.com", "bob@example.com"]:
    agent = DroidAgent(
        goal="Send welcome email",
        config=config,
        variables={"recipient": user},
        prompts=custom_prompts
    )
    await agent.run()

​
Configuration Data

variables = {
    "api_endpoint": "https://api.example.com/v2",
    "timeout": 30
}

agent = DroidAgent(
    goal="Call API endpoint",
    config=config,
    variables=variables,
    prompts=custom_prompts
)

​
Key Points

  1. Custom prompts required - Default prompts don’t render variables in agent context
  2. Direct access in tools - Custom tools access ctx.shared_state.custom_variables via the ActionContext
  3. Available to all agents - Manager, Executor, FastAgent, Scripter all receive variables
  4. Jinja2 templates - Use {% if variables %} blocks in custom prompts
  5. Auto-injection - ctx (ActionContext) is injected automatically by the tool registry