Custom Cache Detection Prompts let you override the default cache-detection context for a specific recorded step. When set, Cyberdesk still compares the cached state (Desktop #1) with the current state (Desktop #2), but your instructions become the rules the model should use for whether the recorded action would still replay successfully.
For an introduction to trajectories and how they work, see Trajectories 101. This page focuses specifically on custom cache detection prompts that give you full control over trajectory validation. 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 Prompts give you full control over the validation logic. When you set a custom prompt:
- Default-context override: Your prompt replaces the standard workflow and step context Cyberdesk normally uses for cache detection
- Step-specific: Each trajectory step can have its own custom prompt
- Human-written: Provide exact validation criteria that automated systems can’t infer
- Direct Control: You define exactly what constitutes a cache hit vs miss for that recorded action
When a custom prompt is set, it replaces the default workflow and step context that Cyberdesk normally provides for cache detection. The model still receives the two screenshots and, when applicable, a note about the shared red-circle annotation. You must explicitly define what makes a cache hit vs cache miss, because those instructions are the only rules the model should use for the decision.
How It Works
During Cache Detection
When comparing screen states with a custom prompt:
- Capture: System takes a screenshot of the current state (Desktop #2)
- Load Cache: Retrieves the cached screenshot from the trajectory (Desktop #1)
- Prompt Framing: Cyberdesk wraps your instructions in a short action-replay prompt instead of the normal default context
- Decision: The system evaluates and returns cache hit or cache miss
The cache detection agent receives a prompt shaped like this:
<TASK>
Your task is to determine whether a cached action (originally successfully executed on desktop #1's state) would successfully replay on desktop #2's current state. Desktop #1 is verified to be a desired state to execute the cached action.
The user has provided the following custom cache detection instructions, that you should strictly adhere to. They are the only rules that apply to this decision.
<CUSTOM_CACHE_DETECTION_INSTRUCTIONS>
[Your custom prompt here]
</CUSTOM_CACHE_DETECTION_INSTRUCTIONS>
</TASK>
Note: Both screenshots have a red circle annotation at the same coordinate to help you identify if the UI has shifted.
In the Trajectory Editor
You can add or edit custom prompts in the trajectory viewer:
- Navigate to a trajectory in the Workflows section
- Expand any step to view details
- Find the
Custom Cache Detection Prompt Override field in the pre-check snapshot area
- Add your prompt with explicit hit/miss criteria
- Save changes to update the trajectory
You can also open a cache comparison in run history, click Improve Cache Detection, and save the same override back to the underlying trajectory step.
Example Use Cases
Since your custom prompt replaces the default context for that step, you must be explicit about what defines a cache hit vs miss.
Validating Critical Elements
Cache hit if the "Submit Order" button is visible and enabled.
Cache miss if the button is missing, disabled, or in a different position.
Ignore the order number displayed, as it will differ between runs.
Checking Layout Structure
Cache hit if the product list shows exactly 3 items in the same layout.
Cache miss if the item count differs or the layout has changed.
Item names will vary based on parameters - ignore text content, focus on structure.
Focus Area Validation
Only validate the left sidebar navigation.
Cache hit if the sidebar shows the same menu items in the same positions.
Cache miss if sidebar items are different or rearranged.
Ignore the main content area entirely - it displays real-time data.
Conditional States
Cache hit if EITHER:
- A modal is open showing "Processing..." status, OR
- The modal is closed and a results table is visible
Cache miss if neither condition is met.
Cache hit if the form has 4 input fields in vertical layout with labels: Name, Email, Phone, Address.
Cache miss if any field is missing or the layout differs.
Ignore the actual values in the fields - they will differ based on parameters.
Best Practices
Always Define Both Outcomes
Since you’re replacing the default cache-detection context, explicitly state both when it’s a cache hit and when it’s a cache miss.
Good: “Cache hit if the dialog is visible. Cache miss if it’s not visible or obscured.”
Less Good: “The dialog should be visible”
Be Specific About What to Check
Good: “Cache hit if three buttons are arranged horizontally at the bottom of the form.”
Less Good: “Check the buttons are correct”
Explicitly State What to Ignore
Good: “Ignore timestamps, ‘Last Updated’ labels, and dynamic content. Focus only on the form structure.”
Less Good: Assuming the system knows what to ignore
Consider Parameter Variations
Good: “The username field will contain different values based on parameters - ignore the actual text, just verify the field exists.”
Less Good: “Username should be John”
Handle Edge Cases
Good: “Cache hit if either the success modal OR the results table is visible. Cache miss if neither is present.”
Less Good: “Something might be wrong”
Keep It Clear
Aim for clear, unambiguous criteria. Remember: your prompt replaces Cyberdesk’s default cache-detection context for this step.
When to Use Custom Prompts
Consider adding a custom prompt when:
- A step frequently has false positives or negatives
- The validation criteria are subtle or nuanced
- Dynamic content makes default comparison unreliable
- You’ve observed specific failure patterns
- The step is critical to workflow success
- You need precise control over what defines a match
You don’t need custom prompts for every step - only where the default cache detection logic isn’t working well for your use case.
Technical Details
Data Storage
Custom prompts are stored in the pre_check_snapshot object of each trajectory step:
{
"pre_check_snapshot": {
"screenshot": "...",
"last_agent_thought": "...",
"custom_cache_detection_instructions": "Your prompt here",
"coordinates": { "x": 512, "y": 384 }
}
}
How Override Works
When a custom prompt is set, the cache detection agent receives:
<TASK>
Your task is to determine whether a cached action (originally successfully executed on desktop #1's state) would successfully replay on desktop #2's current state. Desktop #1 is verified to be a desired state to execute the cached action.
The user has provided the following custom cache detection instructions, that you should strictly adhere to. They are the only rules that apply to this decision.
<CUSTOM_CACHE_DETECTION_INSTRUCTIONS>
[Your custom prompt]
</CUSTOM_CACHE_DETECTION_INSTRUCTIONS>
</TASK>
Note: Both screenshots have a red circle annotation at the same coordinate to help you identify if the UI has shifted.
Backward Compatibility
Trajectories without custom prompts continue to work normally using the default cache detection logic. The field is optional and defaults to empty/unset. 
