Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cyberdesk.io/llms.txt

Use this file to discover all available pages before exploring further.

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 eligible recorded 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:
  1. Capture: System takes a screenshot of the current state (Desktop #2)
  2. Load Cache: Retrieves the cached screenshot from the trajectory (Desktop #1)
  3. Prompt Framing: Cyberdesk wraps your instructions in a short action-replay prompt instead of the normal default context
  4. 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.
The red-circle note is only included when the recorded step has coordinate annotations.

​
In the Trajectory Editor

You can add or edit custom prompts in the trajectory viewer for recorded steps that have a pre-check snapshot:
  1. Navigate to a trajectory in the Workflows section
  2. Expand a recorded step to view details
  3. Find the Custom Cache Detection Prompt Override field in the pre-check snapshot area
  4. Add your prompt with explicit hit/miss criteria
  5. Save changes to update the trajectory
Steps added manually in the UI cannot use custom cache detection because they do not have a reference screenshot, and loop-control steps such as end_loop_iteration do not run cache detection. 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.

​
Form Validation

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.
The note about red circles is only included if coordinate annotations are present. When no custom prompt is set, the system uses its default cache detection logic, which considers workflow context, the recorded step/action, the agent’s last thought, parameter-level differences, and coordinate-shift hints when available.

​
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.