Looping Tools

Looping tools allow you to repeat the same sequence of actions multiple times over a collection of items or a fixed count. The system learns the pattern once during the first iteration, then deterministically replays it for all remaining iterations.

Overview

Instead of manually repeating actions in a focused_action step, use start_loop and end_loop_iteration to automate repetitive tasks:

Learn once, replay many: The agent maps out one iteration, then the system replays it automatically
Access loop items: Use the special {{loop_item}} runtime variable to reference the current item in a focused_action step
Structured results: Get detailed summaries of all iterations including successes and failures
Cache friendly: Loops work seamlessly with trajectories for lightning-fast execution
Error handling: Loops exit early if errors occur, returning partial results

Actions

start_loop

Begin a loop iteration over a non-empty array or positive integer count. Parameters:

text: JSON array like ["item1", "item2", "item3"] or integer like 5 for counting loops. If the loop source is a variable, do not wrap the variable in quotes: use text={items}, text={$items}, or text={{items}}.

Usage:

Use start_loop with text=["Alice", "Bob", "Carol"]

What Happens:

System creates a loop context with all items
Sets current iteration to 0 (first item)
Agent completes ONE full iteration manually
Agent calls end_loop_iteration when done
System automatically replays remaining iterations

If the resolved text contains no items to process, the loop is skipped instead of started. That includes values like [], null, an empty string, or 0 / negative integer counts. In that case there is no active loop context, so you should continue with the steps after the loop and not call end_loop_iteration. The {{loop_item}} Variable: Access the current loop item using the special {{loop_item}} runtime variable:

Simple items: Type {{loop_item}} → types “Alice” during iteration 0
Nested objects: {{loop_item.name}} → accesses name field
Array elements: {{loop_item[0]}} → accesses first array element
Deep nesting: {{loop_item.user.emails[0]}} → accesses nested data

end_loop_iteration

Mark the current iteration as complete and trigger replay of remaining iterations. Parameters:

text: Summary of this iteration (can use runtime variables for dynamic info)

Usage:

Use end_loop_iteration with text="Processed user {{loop_item}}: status={{status}}"

What Happens:

System evaluates runtime variables in the summary text
Adds iteration result to the results array
If iteration 0: Captures trajectory steps and replays iterations 1 to N-1
If recovery iteration: Replays from current + 1 to N-1
Returns JSON summary of all iterations when complete

Summary Format:

{
  "total_iterations": 3,
  "completed_iterations": 3,
  "successful": 3,
  "skipped": 0,
  "failed": 0,
  "iteration_results": [
    {"iteration": 0, "status": "success", "summary": "Processed user Alice: status=complete"},
    {"iteration": 1, "status": "success", "summary": "Processed user Bob: status=complete"},
    {"iteration": 2, "status": "success", "summary": "Processed user Carol: status=complete"}
  ],
  "message": "Loop completed: 3 successful, 0 skipped, 0 failed"
}

skip_loop_iteration

Skip the rest of the current loop iteration and continue to the next loop item. This is intended for focused agents inside a loop context (i.e., when a focused_action is running during an active start_loop). Use it when the current loop item is not actionable (missing data, not found on screen, wrong state, etc.) and you want to move on gracefully. Parameters:

text: Brief reason why the iteration is being skipped (this will appear in the loop summary)

What Happens:

The system records the skip reason for the current iteration
Any remaining steps for that iteration are not executed
The loop proceeds to the next item (remaining iterations continue as usual)
The final loop summary includes status: "skipped" entries and a skipped count

Important (how loop replay works): The system records what you do in the first loop iteration (iteration 0) and replays those recorded steps for iterations 1..N-1.If iteration 0 immediately calls skip_loop_iteration, then the system didn’t learn any “real work” steps to replay — it mostly learned “skip”, so later iterations may also end up doing nothing useful.Recommendation: make sure iteration 0 is a normal “happy path” item (one that should be processed). Put a known‑good item first, or reorder/filter your input list so the first item won’t be skipped.If you’re running from a cached trajectory (muscle memory), this specific “iteration 0 teaches the replay” concern is not an issue — it’s fine if iteration 0 ends up being a skip_loop_iteration, because our system has already learned the full loop actions.

Example – Skip when the current item is missing:

Use start_loop with text=["Alice", "Bob", "Carol"]
Use focused_action: "Check whether {{loop_item}} exists in the list. If not found, skip this loop iteration."
(Inside focused_action, if not found) Use skip_loop_iteration with text="User not found: {{loop_item}}"
Continue with next item automatically
Use end_loop_iteration with text="Processed {{loop_item}}"

Loop Types

Array Loop

Iterate over a collection of items. Example - Loop over names:

Use start_loop with text=["Alice", "Bob", "Carol"]
Click on user {{loop_item}} in the list
Extract their email and save as {{user_email}}
Use end_loop_iteration with text="Processed {{loop_item}}: {{user_email}}"

Result: System executes the pattern for Alice, then automatically replays for Bob and Carol.

Integer Loop

Repeat actions a fixed number of times. The {{loop_item}} variable will be 0, 1, 2, etc. Positive integers create that many iterations; 0 or a negative count skips the loop entirely. Example - Download 5 reports:

Navigate to reports page
Use start_loop with text=5
Click on report number {{loop_item}}
Download the report
Use end_loop_iteration with text="Downloaded report {{loop_item}}"

Result: Executes for items 0, 1, 2, 3, 4.

Variable-Based Loop

Loop over data collected during the workflow using runtime or input variables. Example - Loop over runtime variable:

Use focused_action to extract all order IDs from the screen. Save as {{order_ids}} as a JSON array
Use start_loop with text={{order_ids}}
Navigate to order {{loop_item}}
Extract order details
Use end_loop_iteration with text="Processed order {{loop_item}}"

Example - Loop over input variable:

Input variables: {patient_ids: ["P001", "P002", "P003"]}

Use start_loop with text={patient_ids}
Search for patient {{loop_item}}
Extract medical records
Use end_loop_iteration with text="Extracted data for {{loop_item}}"

Passing Complex JSON Arrays via SDK

When creating a run programmatically, you can pass arrays of complex objects as input variables. The workflow can then loop over these objects and access nested fields. Workflow Prompt:

Use start_loop with text={patients}
Search for patient {{loop_item.mrn}}
Verify name matches {{loop_item.first_name}} {{loop_item.last_name}}
Navigate to the {{loop_item.department}} department
Extract the latest lab results
Use end_loop_iteration with text="Processed {{loop_item.first_name}} {{loop_item.last_name}}"

SDK Code to Create the Run:

TypeScript
Python

import { createCyberdeskClient } from 'cyberdesk';

const client = createCyberdeskClient('YOUR_API_KEY');

// Define your complex array of objects
const patients = [
  { mrn: 'MRN-001', first_name: 'Alice', last_name: 'Smith', department: 'Cardiology' },
  { mrn: 'MRN-002', first_name: 'Bob', last_name: 'Johnson', department: 'Neurology' },
  { mrn: 'MRN-003', first_name: 'Carol', last_name: 'Williams', department: 'Oncology' }
];

// Create the run with the array as an input variable
const { data: run } = await client.runs.create({
  workflow_id: 'your-workflow-id',
  machine_id: 'your-machine-id',
  input_values: {
    patients: patients  // Pass the array directly - SDK handles JSON serialization
  }
});

console.log('Run created:', run.id);

from cyberdesk import CyberdeskClient, RunCreate
import asyncio

async def create_run_with_loop_data():
    client = CyberdeskClient('YOUR_API_KEY')
    
    # Define your complex array of objects
    patients = [
        {'mrn': 'MRN-001', 'first_name': 'Alice', 'last_name': 'Smith', 'department': 'Cardiology'},
        {'mrn': 'MRN-002', 'first_name': 'Bob', 'last_name': 'Johnson', 'department': 'Neurology'},
        {'mrn': 'MRN-003', 'first_name': 'Carol', 'last_name': 'Williams', 'department': 'Oncology'}
    ]
    
    # Create the run with the array as an input variable
    run_data = RunCreate(
        workflow_id='your-workflow-id',
        machine_id='your-machine-id',
        input_values={
            'patients': patients  # Pass the array directly - SDK handles JSON serialization
        }
    )
    
    response = await client.runs.create(run_data)
    print(f'Run created: {response.data.id}')

asyncio.run(create_run_with_loop_data())

Accessing Nested Fields: Inside your loop, use dot notation to access object properties:

{{loop_item.mrn}} → "MRN-001"
{{loop_item.first_name}} → "Alice"
{{loop_item.department}} → "Cardiology"

For deeply nested data, chain the accessors: {{loop_item.address.city}} or {{loop_item.contacts[0].email}}

Advanced Patterns

Nested Data Access

When looping over objects or arrays, access nested fields: Example:

// Input: [{"name": "Alice", "dept": "Sales"}, {"name": "Bob", "dept": "Engineering"}]

Use start_loop with text={employees}
Search for employee {{loop_item.name}}
Navigate to {{loop_item.dept}} department
Use end_loop_iteration with text="Processed {{loop_item.name}} from {{loop_item.dept}}"

Combining With Async Extraction

Extract data asynchronously while looping for maximum efficiency: Example:

Use start_loop with text=["Form1", "Form2", "Form3"]
Navigate to {{loop_item}}
Take screenshot with extract_prompt="Extract all form data as JSON" and process_async="run"
Use end_loop_iteration with text="Queued extraction for {{loop_item}}"
All extractions complete at end of run before generating final output

Error Handling in Loops

Loops exit early if errors occur, returning partial results: Example:

Use start_loop with text={document_names}
Open document {{loop_item}}
If document fails to open, use declare_task_failed with message "Cannot open {{loop_item}}"
Process the document
Use end_loop_iteration with text="Completed {{loop_item}}"

If iteration 2 fails: Loop returns summary with iterations 0-1 successful, iteration 2 failed, and early_exit: true.

Cache Detection in Loops

By default, recorded loop steps use cache detection. end_loop_iteration and skip_loop_iteration are control steps, so they do not use cache detection. You can disable cache detection for an individual recorded loop step if a step is too noisy or causes unnecessary cache misses.

Enabling Loop Cache Detection

In the trajectory editor, cache detection is on by default for recorded loop steps that have a reference screenshot. Toggle Cache detection off to force replay for that step without a screenshot comparison. end_loop_iteration and skip_loop_iteration are control steps and do not use cache detection. Steps added later in the UI also cannot use cache detection because they have no reference screenshot.

Recovery Options

If cache detection fails mid-loop, the recovery agent is invoked with loop context and can:

Option	Use When	Result
`resume_trajectory`	Minor issue (popup, timing)	Retries cache detection
`end_loop_iteration`	You completed the iteration manually	Loop continues with remaining items
`skip_loop_iteration`	This item is problematic	Skips to next item
`declare_task_failed`	Workflow is broken	Task fails cleanly

If the recovery agent resolves the issue (via resume_trajectory, end_loop_iteration, or skip_loop_iteration), the trajectory is still saved. If the agent calls declare_task_failed, no trajectory is saved.

Loop cache detection is optional per step. Leave it on for steps where visual state matters, and turn it off for steps that are noisy or do not need a screenshot check.

Important Limitations

Nested Loops Not Supported: You cannot call start_loop while already in a loop. Complete the current loop first before starting a new one.If you attempt nested loops, the system will return an error: "Cannot start_loop while already in a loop. Call end_loop_iteration first."

Unclosed Loop Reminder: If you haven’t called end_loop_iteration after 20 steps, the system will append a reminder to your tool results. This prevents accidentally leaving loops open.

Complete Examples

Example 1: Discover and Process Patients (Runtime Variable Loop)

This example demonstrates a common pattern where the loop items are discovered during the run rather than passed as input. The agent extracts a list of patients from the screen and then loops over them. Workflow Prompt:

Navigate to patient management system
Login with {username} and {$password}
Navigate to "Today's Appointments" page
Use focused_action with instruction "Extract all patient IDs visible in the appointments table. Return them as a JSON array of objects with fields: id, name, appointment_time. Save the result as {{todays_patients}}"
Use start_loop with text={{todays_patients}}
Click on patient {{loop_item.name}} (ID: {{loop_item.id}})
Use focused_action to verify the patient record loaded successfully
Navigate to "Demographics" tab
Use screenshot with extract_prompt="Extract patient demographics as JSON with fields: name, dob, address, phone" and process_async="batch"
Navigate to "Insurance" tab
Use copy_to_clipboard with text="insurance_id" to copy the insurance ID
Use end_loop_iteration with text="Completed {{loop_item.name}} ({{loop_item.id}}) - Appointment: {{loop_item.appointment_time}}, Insurance: {{insurance_id}}"
System will automatically process remaining patients
Export final report with all patient data

Input Variables:

{
  "username": "admin"
}

What Happens:

Agent logs in and navigates to the appointments page

focused_action analyzes the screen and extracts patient data, saving it as {{todays_patients}}:

[
  {"id": "P12345", "name": "Alice Smith", "appointment_time": "9:00 AM"},
  {"id": "P67890", "name": "Bob Johnson", "appointment_time": "10:30 AM"},
  {"id": "P11223", "name": "Carol Williams", "appointment_time": "2:00 PM"}
]

start_loop begins iterating over this runtime-discovered array
Agent completes iteration 0 (Alice Smith) manually
System automatically replays iterations 1-2 for Bob and Carol
Each iteration accesses nested fields: {{loop_item.id}}, {{loop_item.name}}, {{loop_item.appointment_time}}

Key Pattern: The loop items aren’t known ahead of time—they’re discovered by focused_action during execution and stored as a runtime variable. This is powerful for workflows where you need to “find what’s on the screen, then process each item.”

Example 2: Batch Download Forms

Workflow Prompt:

Navigate to forms portal
Use start_loop with text=10
Click on form row {{loop_item}}
Click "Download PDF" button
Wait 2 seconds for download
Use end_loop_iteration with text="Downloaded form {{loop_item}}"
Use execute_terminal_command to run "Get-ChildItem $env:USERPROFILE\Downloads\*.pdf | Select-Object -First 10 | ConvertTo-Json" to list downloaded files

Execution Flow:

Iteration 0: Agent downloads form 0
Iterations 1-9: System automatically downloads forms 1-9
Terminal command lists all downloaded files
Total time: ~10 seconds (cached) vs ~5 minutes (uncached)

Example 3: Data Entry From Spreadsheet

Workflow Prompt:

Use execute_terminal_command to run "Import-Csv {csv_file_path} | ConvertTo-Json" to load spreadsheet data
Use focused_action to parse the JSON output and save the array as {{records}}
Navigate to data entry form
Use start_loop with text={{records}}
Click "New Record" button
Type {{loop_item.name}} in the Name field
Type {{loop_item.email}} in the Email field
Type {{loop_item.phone}} in the Phone field
Click "Save" button
Use focused_action to verify "Record saved successfully" message appears
Use end_loop_iteration with text="Entered record for {{loop_item.name}}"
Click "Close" to exit data entry

Result: Efficiently processes entire spreadsheet with validation at each step.

Best Practices

Use focused_action for validation in loops

Add focused_action steps within your loop to verify each iteration succeeded:

Use start_loop with text={items}
Process {{loop_item}}
Use focused_action to verify processing succeeded
Use end_loop_iteration with text="Verified {{loop_item}}"

This ensures errors are caught immediately per iteration.

Parameterize summaries with runtime variables

Make iteration summaries dynamic by using runtime variables:

Use end_loop_iteration with text="Processed {{loop_item}}: found {{count}} results, status={{status}}"

This creates rich per-iteration results you can analyze later.

Prefer small, focused loop bodies

Keep loop iterations concise (5-15 steps). For complex processing:

Use start_loop with text={orders}
Use focused_action to process order {{loop_item}} completely
Use end_loop_iteration with text="Completed {{loop_item}}"

Let focused_action handle complex logic per iteration.

Use runtime variables for conditional logic

Set flags during iterations for later decision-making:

Use start_loop with text={invoices}
Check invoice {{loop_item}} status
If unpaid, save unpaid_count via upsert_runtime_values
Use end_loop_iteration with text="Checked {{loop_item}}"
After loop: If {{unpaid_count}} &gt; 0, send notification email

Troubleshooting

Loop doesn't complete all iterations

Cause: An error occurred in one of the iterations.Solution: Check the loop summary’s iteration_results array to see which iteration failed and why. Add focused_action validation steps to catch errors early.

Loop is skipped immediately

Cause: The start_loop input resolved to no items, such as [], null, an empty string, or 0.Solution: Confirm the input or runtime variable really contains a JSON array (or a positive integer for counting loops). If it is intentionally empty, skip the loop body and continue with the steps that come after the loop. Do not call end_loop_iteration when no loop was started.

{{loop_item}} shows as literal text

Cause: Runtime variable replacement failed or loop wasn’t started.Solution: Ensure start_loop was called before using {{loop_item}}. Check that the loop items array is valid JSON.

Nested loop error

Cause: Attempted to call start_loop while already in a loop.Solution: Complete the current loop with end_loop_iteration before starting a new loop. Nested loops are not supported in the current version.

Loop reminder appears repeatedly

Cause: You haven’t called end_loop_iteration after 20+ steps.Solution: Call end_loop_iteration when the iteration is complete. The reminder appears every 20 steps to prevent accidental unclosed loops.

Focused Action

Dynamic validation and data extraction within loop iterations

Runtime Variables

Set and use runtime variables in loop summaries

Extract Prompt

Vision-based extraction with async processing in loops

Trajectories 101

How caching accelerates loop execution

Getting started

SDK Guides

Cyberdriver

Workflow Prompting

Webhooks

Concepts

Additional Details

Overview

Actions

start_loop

end_loop_iteration

skip_loop_iteration

Loop Types

Array Loop

Integer Loop

Variable-Based Loop

Passing Complex JSON Arrays via SDK

Advanced Patterns

Nested Data Access

Combining With Async Extraction

Error Handling in Loops

Cache Detection in Loops

Enabling Loop Cache Detection

Recovery Options

Important Limitations

Complete Examples

Example 1: Discover and Process Patients (Runtime Variable Loop)

Example 2: Batch Download Forms

Example 3: Data Entry From Spreadsheet

Best Practices

Troubleshooting

Focused Action

Runtime Variables

Extract Prompt

Trajectories 101

​Overview

​Actions

​start_loop

​end_loop_iteration

​skip_loop_iteration

​Loop Types

​Array Loop

​Integer Loop

​Variable-Based Loop

​Passing Complex JSON Arrays via SDK

​Advanced Patterns

​Nested Data Access

​Combining With Async Extraction

​Error Handling in Loops

​Cache Detection in Loops

​Enabling Loop Cache Detection

​Recovery Options

​Important Limitations

​Complete Examples

​Example 1: Discover and Process Patients (Runtime Variable Loop)

​Example 2: Batch Download Forms

​Example 3: Data Entry From Spreadsheet

​Best Practices

​Troubleshooting

​Related Tools

Focused Action

Runtime Variables

Extract Prompt

Trajectories 101

Overview

Actions

start_loop

end_loop_iteration

skip_loop_iteration

Loop Types

Array Loop

Integer Loop

Variable-Based Loop

Passing Complex JSON Arrays via SDK

Advanced Patterns

Nested Data Access

Combining With Async Extraction

Error Handling in Loops

Cache Detection in Loops

Enabling Loop Cache Detection

Recovery Options

Important Limitations

Complete Examples

Example 1: Discover and Process Patients (Runtime Variable Loop)

Example 2: Batch Download Forms

Example 3: Data Entry From Spreadsheet

Best Practices

Troubleshooting

Related Tools