> ## 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.
# Focused Action
> Capture dynamic content and make context-aware decisions in cached workflows
## 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](/concepts/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](/concepts/trajectories).
## 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
```text theme={null}
"Navigate to the patient list, then use focused_action to find and click on
the patient whose name is {patient.name.full} and date of birth is {patient.demographics.dob}"
```
### 2. Data Extraction for Output Schema
```text theme={null}
"Once you reach the invoice details page, use focused_action to extract
the total amount, invoice number, and due date. These values will be
different for each run and should be included in the output."
```
### 3. Conditional Workflow Branching
```text theme={null}
"After submitting the form, use focused_action to check if an error message
appears. If it says 'Invalid credentials', try the alternate login method.
If it says 'Account locked', stop the workflow."
```
### 4. Verification Steps
```text theme={null}
"After clicking submit, use focused_action to verify that the success
message appears and contains the confirmation number starting with 'CNF-'"
```
## 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
```text theme={null}
"[Navigate to specific screen], then use focused_action to [specific observation/action].
[Explain what to look for and what to do with the information]"
```
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](/workflow-prompting/get-main-instructions).
## Real-World Examples
### Healthcare: Patient Record Selection
```text theme={null}
"Go to the patient search page and search for the last name {patient_last_name}.
Once the results load, use focused_action to find the patient whose full name
is {patient_full_name} and medical record number ends with {mrn_last_4}, saving their full MRN as {{patient_mrn}}.
Click on that patient's record to open their details. Later, when saving reports, use {{patient_mrn}}
in the filename."
```
### E-commerce: Dynamic Price Extraction
```text theme={null}
"Search for product SKU {product_sku} and open the product page. Use focused_action
to extract the current price, availability status, and any promotional discount
percentage. These values should be captured in the output schema as 'current_price',
'in_stock', and 'discount_percent' respectively."
```
### Finance: Transaction Verification
```text theme={null}
"After initiating the transfer of ${amount} to account {recipient_account},
use focused_action to verify the confirmation screen shows the correct amount
and recipient details. Extract the transaction ID for the output."
```
### Document Processing: Dynamic Form Fields
```text theme={null}
"Open the claim form for claim number {claim_id}. Use focused_action to
identify which optional sections are present (Medical History, Prior Authorization,
or Specialist Referral) and fill only those sections that appear."
```
## Common Pitfalls to Avoid
**Don't use focused\_action for static actions**
If 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
```text theme={null}
"Use focused_action to click the Submit button" // Static action, always the same
"Use focused_action to wait 3 seconds" // Static wait, not dynamic
```
### ✅ Correct Usage
```text theme={null}
"Use focused_action to click on the appointment slot that shows {preferred_time}"
"Use focused_action to wait until the processing message changes to 'Complete'"
```
## 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](/workflow-prompting/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](/concepts/trajectories) 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:
```text theme={null}
"Use focused_action to find the generated report file and note its full path,
something like 'C:\Reports\2024\Report_12345.pdf'. Save this as {{report_path}}."
```
### Using Runtime Variables
Once set, runtime variables can be used in any subsequent action:
```text theme={null}
"First, use focused_action to find the invoice number on the screen and save it as {{invoice_id}}.
Then navigate to the search page and type {{invoice_id}} in the search box.
Finally, use mark_file_for_export to export the file at C:\Invoices\{{invoice_id}}.pdf"
```
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
```text theme={null}
"1. Use focused_action to look at the downloads folder and find the most recent
file matching pattern 'Export_*.xlsx'. Save the full file path as {{export_file}}.
2. Use execute_terminal_command to run 'Copy-Item {{export_file}} D:\ProcessedReports\'
3. Use mark_file_for_export to export {{export_file}}"
```
**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:
| Operator | Description | Example |
| ---------- | -------------------------------- | ---------------------------------------- |
| `$append` | Append item to array | `{"items": {"$append": "new_item"}}` |
| `$prepend` | Prepend item to array | `{"items": {"$prepend": "first"}}` |
| `$concat` | Concatenate arrays | `{"items": {"$concat": ["a", "b"]}}` |
| `$merge` | Shallow merge objects | `{"config": {"$merge": {"key": "val"}}}` |
| `$remove` | Remove first occurrence by value | `{"tags": {"$remove": "old"}}` |
| `$pop` | Remove last element | `{"stack": {"$pop": true}}` |
#### Example: Accumulating Items Across Loop Iterations
```text theme={null}
"For each order in the list:
1. Use focused_action to extract the order details (order_id, customer_name, total)
2. Use upsert_runtime_values to append to the orders list:
text='{\"orders\": {\"$append\": {\"order_id\": \"...\", \"customer_name\": \"...\", \"total\": ...}}}'
3. Navigate to the next order
After the loop, {{orders}} will contain all extracted order data."
```
#### Example: Building a Summary Object
```text theme={null}
"After extracting each section of the report, use upsert_runtime_values to merge
the results: text='{\"report_data\": {\"$merge\": {\"section_name\": {...extracted data...}}}}'
This accumulates data from multiple sections into a single {{report_data}} 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
```text theme={null}
"Log in with email {email} and password {$password}. After submission, use focused_action to verify that the dashboard is visible without echoing the password in observations."
```
## Working with Output Schemas
When your workflow has an output schema that expects dynamic data, you have multiple extraction methods:
* **[extract\_prompt](/workflow-prompting/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](/workflow-prompting/copy-to-clipboard) (fastest for copyable text):** Deterministic clipboard-based extraction. Best for: selectable text fields like IDs, numbers, dates.
```text theme={null}
"Your output schema expects 'patient_vitals' containing blood pressure, heart rate, and temperature.
Option A - Extract Prompt (vision-based, can be async):
'Take screenshot with extract_prompt=\"Extract patient vitals as JSON:
{systolic, diastolic, heart_rate, temperature}\" and process_async=\"batch\"'
Option B - Focused Action (for decisions + extraction):
'Use focused_action to check if vitals are within normal range, extract the
values as JSON, and save heart_rate as {{patient_heart_rate}} for later use'
Option C - Copy to Clipboard (fastest for copyable fields):
'Triple-click the heart rate field and use copy_to_clipboard with key name
\"heart_rate\" to save as {{heart_rate}}'"
# Example: Parallel extraction with scrolling (extract_prompt)
"Extract all order data by scrolling through the orders table:
- Take screenshot with extract_prompt='Extract all visible orders as JSON
{order_id, customer, total, status}' and process_async='batch'
- Scroll down
- Take screenshot with extract_prompt='Extract all visible orders as JSON
{order_id, customer, total, status}' and process_async='batch'
- Repeat until bottom
All batch extractions complete in parallel before next agent step."
```
See [Extract Prompt](/workflow-prompting/extract-prompt) for comprehensive documentation on vision-based extraction with async processing modes.
## Advanced Patterns
### Chained Focused Actions
```text theme={null}
"Use focused_action to count how many unread messages are shown. Then,
for each unread message, use focused_action to open it and extract the
sender and subject line."
```
### Chaining Runtime Variables
```text theme={null}
"1. Use focused_action to find the file with Type DI4 in the current directory.
It should match pattern '*{import_file_name}*.D14'. Save the full path as {{di4_file_path}}.
2. Use focused_action to open {{di4_file_path}} and extract the total amount.
Save this as {{total_amount}}.
3. Navigate to the summary page and type 'Total: {{total_amount}}' in the field.
4. Use mark_file_for_export to export {{di4_file_path}}"
```
### Fallback Handling
```text theme={null}
"Use focused_action to look for the 'Download Report' button. If it's not
visible, use focused_action to check if there's an error message about
report generation still in progress, then wait 10 seconds and try again."
```
### Multi-Criteria Selection
```text theme={null}
"In the appointment list, use focused_action to find an available slot that
meets ALL of these criteria: {day_of_week}, after {earliest_time},
before {latest_time}, and with {preferred_doctor}."
```
## Model Override (Optional)
You can optionally specify which model to use for a focused action by adding the `model` parameter:
```text theme={null}
Use focused_action with model="Sonnet 4.5 (Thinking)" to find and click on
the patient whose name matches {patient_name}
```
**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](/concepts/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:
```text theme={null}
"Use focused_action to verify the report has finished generating (status shows 'Complete').
Once confirmed, use mark_file_for_export to export the report from
C:\Users\Reports\{report_date}.pdf and use save_screenshot_as_run_attachment
to capture the summary statistics shown on screen."
```
Runtime variables enable powerful integration patterns:
```text theme={null}
"Use focused_action to extract the transaction ID from the confirmation screen and
save it as {{transaction_id}}. Then use execute_terminal_command to run
'Add-Content -Path C:\Logs\transactions.log -Value "{{transaction_id}} - Processed at $(Get-Date)"'
to log the transaction. Finally, use save_screenshot_as_run_attachment to save
the confirmation as 'transaction_{{transaction_id}}.png'."
```
Focused actions work especially well inside loops for per-iteration validation:
```text theme={null}
"Use start_loop with text={order_ids}. For each order, navigate to {{loop_item}}
and use focused_action to verify the order status is 'Shipped' before continuing.
Use end_loop_iteration with text='Verified order {{loop_item}}'."
```
Learn more about looping in [Looping Tools](/workflow-prompting/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:
```text theme={null}
"Use focused_action to check if the invoice has already been processed.
If the status shows 'Complete' or 'Paid', use declare_task_succeeded
with message 'Invoice already processed - no action needed'."
```
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](/workflow-prompting/declare-task-succeeded).