Skip to main content
Custom Cache Detection Instructions allow you to provide step-specific guidance to help the system accurately validate screen states during trajectory replay. This feature enhances cache detection reliability by adding human context about what matters most for each workflow step.
For an introduction to trajectories and how they work, see Trajectories 101. This page focuses specifically on custom cache detection instructions that improve trajectory validation accuracy.

​
The Problem

During trajectory replay, the system compares current screen states against cached screenshots to determine if it can safely reuse recorded actions. However, the default cache detection logic might not always know:
  • Which UI elements are critical vs. cosmetic for a specific step
  • What minor differences are acceptable (e.g., timestamps, dynamic content)
  • Special conditions that should invalidate the cache
  • Context about why a particular screen state was captured
Without this context, cache detection may:
  • Reject valid matches due to irrelevant differences (false negatives)
  • Accept invalid matches by missing critical changes (false positives)
  • Require human review to understand failures

​
The Solution

Custom Cache Detection Instructions let you add step-specific notes that guide the cache validation process. These instructions are:
  • Step-specific: Each trajectory step can have its own custom instructions
  • Human-written: Provide context that automated systems can’t infer
  • Integrated: Automatically included in cache comparison prompts
  • Recovery-aware: Passed to the recovery agent when cache misses occur

​
How It Works

​
During Cache Detection

When comparing screen states, the system incorporates your custom instructions into the validation prompt:
  1. Capture: System takes a screenshot of the current state
  2. Compare: Compares against the cached screenshot from the trajectory
  3. Custom Context: Your instructions are added to the comparison prompt with high priority
  4. Decision: The system evaluates whether states match, guided by your instructions

​
During Agent Recovery

When cache detection fails and the agent takes over:
  1. Context Extraction: System retrieves custom instructions from recent steps
  2. Priority Messaging: Instructions are highlighted as “CRITICAL” in the recovery prompt
  3. Guided Recovery: The agent uses your instructions to understand validation criteria
  4. Informed Actions: Agent makes decisions aware of what you considered important

​
In the Trajectory Editor

You can add or edit custom instructions in the trajectory viewer:
  1. Navigate to a trajectory in the Workflows section
  2. Expand any step to view details
  3. Find the “Custom Cache Detection Instructions” field in the Pre-check Snapshot
  4. Add your instructions (with helpful tooltip guidance)
  5. Save changes to update the trajectory

​
Example Use Cases

​
Highlighting Critical Elements

The "Submit Order" button must be visible and enabled. 
Ignore the order number displayed, as it will differ between runs.

​
Specifying Tolerances

The product list should show exactly 3 items. 
Item names will vary based on {product_category} parameter.
Focus on layout and count, not specific product details.

​
Defining Focus Areas

Only validate the left sidebar navigation. The main content area 
displays real-time data and will always differ.

​
Conditional Validation

If a modal is open, it should show "Processing..." status.
If the modal is closed, the page should show the results table.
Either state is valid - do not fail on this difference.

​
Structural Requirements

The form should have 4 input fields in vertical layout.
Field labels must match: Name, Email, Phone, Address.
Pre-filled values will differ based on {user_data}.

​
Best Practices

​
Be Specific About Intent

Good: “The confirmation dialog must be visible with the text ‘Are you sure?’” Less Good: “Check the dialog”

​
Focus on Structure Over Content

Good: “Three buttons arranged horizontally at the bottom” Less Good: “Check the buttons are correct”

​
Consider Parameter Variations

Good: “The username field should contain parameter value. Ignore the specific name shown.” Less Good: “Username should be John”

​
Identify Acceptable Differences

Good: “Timestamps and ‘Last Updated’ labels will differ - ignore these” Less Good: Don’t mention what to ignore at all

​
Provide Decision Criteria

Good: “If error banner is visible, cache is invalid. If form is clean, cache is valid.” Less Good: “Something might be wrong”

​
Keep It Concise

Aim for 1-3 sentences that capture the essential validation logic. The system still has the agent’s thought context and other signals.

​
When to Use Custom Instructions

Consider adding custom instructions when:
  • A step frequently has false positives or negatives
  • The validation criteria are subtle or nuanced
  • Dynamic content makes comparison challenging
  • You’ve observed specific failure patterns
  • The step is critical to workflow success
You don’t need custom instructions for every step - only where they add meaningful guidance beyond what the system can infer from the agent’s thoughts and standard comparison logic.

​
Technical Details

​
Data Storage

Custom instructions are stored in the pre_check_snapshot object of each trajectory step: 
{
  "pre_check_snapshot": {
    "screenshot": "...",
    "last_agent_thought": "...",
    "custom_cache_detection_instructions": "Your instructions here",
    "coordinates": [...]
  }
}

​
Integration Points

  1. Cache Comparison: Included in system prompt with “IMPORTANT” prefix
  2. Engine Propagation: Carried forward when falling back from cache to agent
  3. Tool Execution: Available as cached_custom_instructions kwarg
  4. Agent Recovery: Highlighted in recovery message with 🎯 emoji for visibility

​
Backward Compatibility

Trajectories without custom instructions continue to work normally. The field is optional and defaults to empty/unset.