What is Focused Action?
Focused Action is a specialized tool that enables your agent to make observations and decisions that need to be evaluated dynamically during every workflow run, even when the workflow is cached and running deterministically via trajectories.In your prompts, always refer to this tool as
focused_action (lowercase, with underscore).Trajectories & Focused Actions: When a workflow trajectory is being replayed, focused actions still execute dynamically to capture fresh data. This allows cached workflows to handle dynamic content while maintaining fast execution. Cyberdesk saves the outer
focused_action call as the trajectory step, but the focused agent’s internal clicks and keystrokes are not recorded as separate steps. During a pure full-cache-hit replay, Cyberdesk does not save a brand-new trajectory unless the workflow falls back to the agent or recovery path. Learn more about how trajectories work.Why Focused Action Exists
In Cyberdesk’s caching system, workflows are recorded and can be replayed deterministically. However, certain actions require real-time evaluation:- Dynamic Selection: Choosing different items from a list based on runtime criteria
- Data Extraction: Capturing values that change between runs (prices, dates, patient data)
- Conditional Logic: Making decisions based on current screen content
How It Works
When you instruct the agent to usefocused_action, it:
- Records a screen snapshot for cache detection
- Launches a focused sub-agent that can take fresh screenshots and perform live computer actions as needed
- Stores the resulting observation for the run and continues the workflow with up-to-date information
When to Use Focused Action
1. Dynamic List Selection
2. Data Extraction for Output Schema
3. Conditional Workflow Branching
4. Verification Steps
How to Prompt for Focused Action
Best Practices
- Be Explicit: Include the exact token
focused_actionin your prompt, for exampleuse focused_action to ...orfocused_action: ... - Provide Context: Explain what the agent should look for and why
- Specify the Action: Clearly state what decision or extraction should occur
- Think Repeatability: Frame instructions for what should happen EVERY time
- Grant Broader Context Deliberately: If you want the focused agent to reread the full workflow prompt during recovery, explicitly mention
get_main_instructions
Prompt Template
Real-World Examples
Healthcare: Patient Record Selection
E-commerce: Dynamic Price Extraction
Finance: Transaction Verification
Document Processing: Dynamic Form Fields
Common Pitfalls to Avoid
❌ Incorrect Usage
✅ Correct Usage
Working with Runtime Variables
For a dedicated guide to
upsert_runtime_values, including array/object operators like $append and $merge, see Upsert Runtime Values.{{variable}} or by having the focused agent call upsert_runtime_values. extract_prompt can also set {{variables}} when the prompt explicitly asks it to save or store them. Once set, these variables can be used by any subsequent steps in the workflow.
Setting Runtime Variables
When you need to capture a value for later use, instruct the focused action to save it:Using Runtime Variables
Once set, runtime variables can be used in any subsequent action:{{invoice_id}}→{{invoice_id (currently: 'INV-12345')}}
Real-World Example: Dynamic File Discovery
Important: If the value is required and cannot be determined, instruct the focused action to call
declare_task_failed rather than continuing without setting the variable.Array and Object Operations
When usingupsert_runtime_values, you can use MongoDB-style operators to manipulate arrays and objects instead of replacing them entirely:
Example: Accumulating Items Across Loop Iterations
Example: Building a Summary Object
Sensitive Variables and Focused Actions
If your prompt includes
{$variable} (e.g., {$password}), the value is handled securely. The agent passes {$variable} verbatim to tools; plaintext is not exposed in thoughts or observations. The actual value is only resolved during the underlying computer action (e.g., when typing) and is deleted from the vault after the run.Best Practices
- Explicitly remind your agent to not repeat sensitive values in it’s thought process
- For extra peace of mind, we have org-level data retention rules you can set to delete all run data after a set number of days.
Example
Working with Output Schemas
When your workflow has an output schema that expects dynamic data, you have multiple extraction methods:- extract_prompt (recommended for large-scale, non-blocking extraction): Use
screenshotwithextract_promptandprocess_asyncfor vision-based extraction. Supports synchronous, batch-scoped, and run-scoped async modes. Best for: non-copyable content, parallel processing, large extractions that don’t affect navigation. - focused_action (recommended for dynamic decisions or runtime variables during navigation): Use when you must make a decision each run (branching, verification) and/or you need to set
{{runtime_variables}}for later steps that affect workflow flow. - copy_to_clipboard (fastest for copyable text): Deterministic clipboard-based extraction. Best for: selectable text fields like IDs, numbers, dates.
See Extract Prompt for comprehensive documentation on vision-based extraction with async processing modes.
Advanced Patterns
Chained Focused Actions
Chaining Runtime Variables
Fallback Handling
Multi-Criteria Selection
Model Override (Optional)
You can optionally specify which model to use for a focused action by adding themodel parameter:
Integration with Other Tools
Focused actions often work in conjunction with other workflow tools:Learn more about looping in Looping Tools.
Early Workflow Completion
Focused actions have exclusive access todeclare_task_succeeded, which allows them to signal that the entire workflow is complete:
declare_task_succeeded in the focused_action instructions when you want to enable that early-exit behavior.
Learn more about early success detection in Declare Task Succeeded.