Skip to main content

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
Without focused_action, these dynamic elements would be frozen to their first recorded values during cached runs.

How It Works

When you instruct the agent to use focused_action, it:
  1. Records a screen snapshot for cache detection
  2. Launches a focused sub-agent that can take fresh screenshots and perform live computer actions as needed
  3. Stores the resulting observation for the run and continues the workflow with up-to-date information
This happens every time the workflow runs, ensuring fresh data capture even in cached executions.

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

  1. Be Explicit: Include the exact token focused_action in your prompt, for example use focused_action to ... or focused_action: ...
  2. Provide Context: Explain what the agent should look for and why
  3. Specify the Action: Clearly state what decision or extraction should occur
  4. Think Repeatability: Frame instructions for what should happen EVERY time
  5. 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

If a focused action may need broader workflow context to recover from an unexpected state, explicitly mention get_main_instructions in that focused prompt. See Get Main Instructions.

Real-World Examples

Healthcare: Patient Record Selection

E-commerce: Dynamic Price Extraction

Finance: Transaction Verification

Document Processing: Dynamic Form Fields

Common Pitfalls to Avoid

Don’t use focused_action for static actionsIf the action is always the same (e.g., “click the Submit button”), you don’t need focused_action. It’s only for dynamic decisions and observations.

❌ Incorrect Usage

✅ Correct Usage

Working with Runtime Variables

Important: Runtime variables can be set by:
  • focused_action instructions that save to {{variable}}, and the focused agent’s explicit upsert_runtime_values calls
  • copy_to_clipboard with key names
  • extract_prompt extraction with its upsert_runtime_values tool (synchronous, process_async="batch", or process_async="run")
No other tool or action can create or update runtime variables.
For a dedicated guide to upsert_runtime_values, including array/object operators like $append and $merge, see Upsert Runtime Values.
Trajectory Editing: If you edit a focused action in a trajectory (changing the observation or instruction), you should also update the underlying workflow prompt to match. This ensures consistent behavior when the system falls back to the agent during cache misses. If you add a brand-new focused action step directly in the trajectory editor, that step cannot use cache detection because there is no reference screenshot to compare against. See Trajectories 101 for details.
Focused actions are a primary way to set runtime variables during navigation, either by prompting them to save to {{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:
When a focused action receives an instruction with an already-set runtime variable, it will see the current value in parentheses:
  • {{invoice_id}}{{invoice_id (currently: 'INV-12345')}}
This makes it clear what the current value is without confusion about assignment.

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 using upsert_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

Operators work with nested paths too: {"invoice.items": {"$append": {...}}} will append to the nested items array within invoice.

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 screenshot with extract_prompt and process_async for 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 the model parameter:
Prefer Computer Use Models: Focused actions work best with models that are known computer use models. The model picker in the prompt editor warns when you select a model that is not marked for computer use. Non-computer-use models may still be selectable, but they often won’t work correctly for actions that require clicking, typing, or navigation.
In the prompt editor, type model="" or use the / slash menu and select “Model Override” to access the model picker. See Model Configuration for details on per-action model overrides and available models.

Integration with Other Tools

Focused actions often work in conjunction with other workflow tools:
Runtime variables enable powerful integration patterns:
Focused actions work especially well inside loops for per-iteration validation:
Learn more about looping in Looping Tools.

Early Workflow Completion

Focused actions have exclusive access to declare_task_succeeded, which allows them to signal that the entire workflow is complete:
This is particularly useful during cached trajectory replay, where the focused action can dynamically determine that no further steps are needed. Because this ends the whole run immediately, include the exact phrase 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.