Skip to main content

​
Overview

Simplex uses an intelligent caching system that dramatically improves agent performance by remembering and reusing successful action sequences. When combined with the variables system, you can create powerful, reusable workflows that adapt to different inputs while maintaining fast execution through cached actions.

​
What is Agent Caching?

Agent caching automatically saves sequences of successful actions that your agents perform. When an agent encounters the same scenario again (like logging into a website), it can replay those cached actions instead of re-planning each step. This means:
  • Faster execution: Cached login flows complete in seconds instead of minutes
  • More reliable: Successfully executed action sequences are reused
  • Cost efficient: Fewer LLM calls for repetitive navigation and interactions
  • Organized by domain: Each URL domain has its own cache tree, keeping different sites separate

​
What are Variables?

Variables allow you to create dynamic, reusable workflows by using placeholders that get filled in at runtime. For example, you can create a single login workflow that works for different users by using {{username}} and {{password}} variables.

​
How Agent Caching Works

​
Cache Tree Structure

Simplex organizes cached actions in a tree structure for each agent and URL domain combination. Think of it like this: 
Root (example.com)
├── Click email field
│   ├── Type {{username}}
│   │   ├── Click password field
│   │   │   ├── Type {{password}}
│   │   │   │   └── Click login button
│   │   │   │       └── Wait 3s
│   │   │   └── [Alternative: Submit with Enter key]
Each path through the tree represents a sequence of actions that successfully completed. When multiple successful paths exist, the agent can choose the most appropriate one.

​
Automatic Caching During Execution

When your agent runs with caching enabled (the default), Simplex automatically:
  1. Checks for cached actions at each step
  2. Replays cached sequences when they match the current scenario
  3. Saves new successful actions to the cache tree
  4. Branches the tree when encountering new scenarios or when cached actions fail

​
Cache Replay and Execution

When an agent encounters a cached scenario:
  1. The system looks up the cache tree for the current agent + URL domain
  2. It finds matching cached action sequences
  3. It executes the cached actions in order
  4. If all cached actions succeed, execution continues from where the cache ends
  5. If a cached action fails (cache miss), the agent falls back to normal planning and creates a new branch in the tree

​
Cache Misses and Branching

A cache miss occurs when a cached action fails to execute. This could happen because:
  • The website’s interface changed
  • A dynamic element has a different ID or position
  • Network timing issues
When this happens, Simplex creates a new branch in the cache tree from the point of failure, allowing multiple successful paths to coexist.

​
The Variables System

​
Variable Syntax

Variables use double curly brace syntax: {{variable_name}} Variables can be used in:
  • Workflow action parameters
  • Agent task descriptions
  • Text input fields
  • URLs
  • Any string-based parameter

​
Where to Define Variables

Variables are defined at the workflow level in the workflow editor:
  1. Open your workflow in the dashboard
  2. Define variables in the workflow settings
  3. Use the variables in any action within that workflow

​
Variable Highlighting in the UI

The Simplex dashboard highlights variables with a yellow background, making it easy to see where dynamic values will be substituted: Example: Login with {{username}} appears with {{username}} highlighted

​
JSON Variable Expansion

Simplex supports complex variables containing JSON objects. When you pass a JSON object as a variable, it automatically expands into bracket notation for easy access: Input: 
{
  "form_info": {
    "field_1": "John",
    "field_2": "Doe"
  }
}
Automatic Expansion: 
{{form_info["field_1"]}} → "John"
{{form_info["field_2"]}} → "Doe"
This makes it easy to work with complex form data without manually flattening objects.

​
Using Cache Trees in the Dashboard

​
Viewing Cache Trees

To view your agent’s cache trees:
  1. Navigate to the Agent page in the dashboard
  2. Click on “View Cache Tree”
  3. Select a domain to see its cached action sequences

​
Understanding the Visualization

The cache tree visualization shows:
  • Nodes: Individual cached actions (Click, Type, Wait, etc.)
  • Edges: Connections showing action sequences
  • Action Details: Each node displays the action type and parameters
  • Branching: Multiple paths show alternative successful sequences

​
Managing Cache

You can manage your cache trees through the dashboard: Delete Individual Nodes
  • Click the trash icon on any cache node
  • Removes that specific action and its children from the tree
Delete Multiple Nodes
  • Select multiple nodes using checkboxes
  • Click “Delete Selected” to remove them all at once
Clear Domain Cache
  • Use the “Clear Cache” button to remove all cached actions for a specific domain
  • Useful when the website has changed significantly
Clear All Agent Cache
  • Remove all cached actions across all domains for an agent
  • Helpful when redesigning your agent’s approach

​
Variables in Workflows

​
Declaring Workflow Variables

In the workflow editor, define your variables in the workflow settings: 
// Example workflow variables
{
  "username": "",
  "password": "",
  "target_url": "https://example.com"
}

​
Using Variables in Actions

Variables can be used in any action parameter: Type Action: 
{
  "function": "type",
  "params": {
    "text": "{{username}}"
  }
}
Goto Action: 
{
  "function": "goto",
  "params": {
    "url": "{{target_url}}/dashboard"
  }
}
Agentic Action: 
{
  "function": "agentic",
  "params": {
    "task": "Login using {{username}} and {{password}}"
  }
}

​
Variable Substitution at Runtime

When you run a workflow, provide the variable values: 
# Python SDK example
simplex.run_workflow(
    workflow_id="workflow_123",
    variables={
        "username": "john@example.com",
        "password": "secure_password_123",
        "target_url": "https://portal.example.com"
    }
)
The system automatically substitutes all {{variable}} placeholders with the provided values before executing each action.

​
Best Practices

​
Caching Best Practices

Clear cache after workflow changes
  • When you modify a workflow’s logic, clear the cache to prevent using outdated action sequences
  • This ensures your agents use your new workflow design
Use caching for repetitive flows
  • Login sequences are perfect for caching
  • Navigation through consistent multi-step processes benefit greatly
  • Form filling with similar structures caches well
Monitor cache tree growth
  • Periodically review your cache trees to understand which paths agents are taking
  • Large, branching trees might indicate inconsistent website behavior
Domain-specific caching
  • Remember that cache is organized per domain
  • The same agent can have different cached sequences for different websites

​
Variable Best Practices

Use descriptive variable names 
// Good
{{customer_email}}
{{invoice_number}}

// Less clear
{{email}}
{{num}}
Define all variables upfront
  • List all variables in your workflow configuration
  • This makes it clear what inputs the workflow expects
Use variables for sensitive data
  • Never hardcode credentials
  • Always use variables like {{username}} and {{password}}
Leverage JSON expansion for complex forms
  • When dealing with multi-field forms, pass a JSON object
  • Let Simplex automatically expand it into accessible properties
Test variable substitution
  • Run workflows with test values first
  • Verify variables are being substituted correctly

​
Practical Examples

​
Example 1: Cached Login Flow

Create a reusable login workflow with caching: 
// Workflow definition
{
  "variables": ["username", "password"],
  "actions": [
    {
      "function": "goto",
      "params": {
        "url": "https://example.com/login"
      }
    },
    {
      "function": "agentic",
      "params": {
        "task": "Log in using {{username}} and {{password}}"
      }
    }
  ]
}
First Run:
  • Agent navigates to login page
  • Plans and executes login steps
  • Caches successful sequence
Subsequent Runs:
  • Instantly replays cached actions
  • Skips planning phase
  • Completes in seconds

​
Example 2: Form Filling with JSON Variables

Handle complex forms efficiently: 
// Run workflow with complex data
{
  "workflow_id": "form_filler",
  "variables": {
    "applicant": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "phone": "555-1234"
    }
  }
}
Use expanded variables in task: 
{
  "function": "agentic",
  "params": {
    "task": "Fill out the form with name: {{applicant[\"first_name\"]}} {{applicant[\"last_name\"]}}, email: {{applicant[\"email\"]}}"
  }
}

​
Example 3: Multi-Domain Workflow

A single agent working across multiple sites with separate caches: 
// Each domain maintains its own cache
{
  "actions": [
    {
      "function": "goto",
      "params": {"url": "https://site1.com"}
      // Uses site1.com cache
    },
    {
      "function": "agentic",
      "params": {"task": "Extract data"}
    },
    {
      "function": "goto",
      "params": {"url": "https://site2.com"}
      // Switches to site2.com cache
    },
    {
      "function": "agentic",
      "params": {"task": "Upload data"}
    }
  ]
}

​
Example 4: Using Cache with run_agent

You can enable/disable caching when running an agent in a workflow: 
{
  "function": "run_agent",
  "params": {
    "agent_name": "login_agent",
    // Cache is enabled by default, but you can control it:
    // "use_cache": false  // Uncomment to disable caching for this run
  }
}
This is useful when you want to force fresh execution even if cached actions exist.

​
Performance Impact

Caching provides significant performance improvements:
  • Login flows: 10-30 seconds → 2-5 seconds (60-80% faster)
  • Navigation sequences: Instant replay vs. planning each step
  • Cost reduction: Fewer LLM API calls for cached scenarios
  • Reliability: Proven action sequences are more consistent

​
Advanced Topics

​
Cache Persistence

Cache trees persist across sessions and are stored in your organization’s database. They remain available until explicitly cleared.

​
Cache Sharing

Within an organization, cache trees are specific to each agent. Different agents maintain separate cache trees even when working on the same domains.

​
Variable Validation

The system validates that all variables used in your workflow are defined. If you reference {{undefined_variable}}, you’ll receive an error before execution begins.

​
Nested Variables

Variables can reference other variables through JSON expansion: 
{
  "user": {
    "credentials": {
      "username": "john",
      "password": "secret"
    }
  }
}
Access as: {{user["credentials"]["username"]}}

​
Troubleshooting

Cache not being used
  • Verify caching is enabled for your agent run
  • Check that you’re on the same URL domain
  • Ensure the workflow hasn’t changed significantly
Variable not substituting
  • Confirm variable is defined in workflow settings
  • Check for typos in variable name (case-sensitive)
  • Verify variable value was provided at runtime
Cache causing errors
  • Website might have changed - clear the cache
  • Cached actions might be from an old version - rebuild cache with fresh run
JSON variable not expanding
  • Ensure JSON is valid
  • Check that you’re using correct bracket notation
  • Verify the nested path exists in your JSON structure
⌘I