Upsert Runtime Values

​

What is Upsert Runtime Values?

​

When to Use It

• store a discovered value like {{report_path}}
• set a failure or status flag like {{missing_file}}
• accumulate arrays or objects across repeated steps
• merge structured data discovered in different phases of a workflow

• saving a discovered export path for later mark_file_for_export
• recording that a required file or patient was not found
• building up an {{orders}} array across loop iterations
• merging multiple extracted sections into one {{report_data}} object

​

Where It Is Available

• focused_action
• extract_prompt flows, especially async extraction agents

​

Basic Usage

{
  "report_path": "C:\\Reports\\output.pdf",
  "missing_file": true
}

• {{report_path}}
• {{missing_file}}

​

Common Prompt Patterns

​

Save a Discovered Value

Use focused_action to find the exported report file in Downloads.
Save the full path as {{report_path}} using upsert_runtime_values.

​

Record a Failure Flag

Use focused_action to check whether invoice {invoice_id} exists in the list.
If it is missing, use upsert_runtime_values to set {{missing_invoice}} to true,
then declare_task_failed.

​

Store Data During Extract Prompt

Take screenshot with extract_prompt="Extract customer_id and order_total and
store them as runtime values using upsert_runtime_values. Then provide a short
summary of the visible order." and process_async="batch"

​

Array and Object Operations

​

Example: Accumulating Across a Loop

For each order:
1. Use focused_action to extract order_id, customer_name, and total.
2. Use upsert_runtime_values with
   text='{"orders": {"$append": {"order_id": "...", "customer_name": "...", "total": ...}}}'
3. Use end_loop_iteration when finished.

​

Example: Merging Structured Sections

After extracting each section, use upsert_runtime_values with
text='{"report_data": {"$merge": {"section_name": {...extracted data...}}}}'

​

Best Practices

1. Use clear runtime variable names like {{report_path}} or {{missing_file}}.
2. Prefer booleans for simple failure flags.
3. Use $append and $merge instead of replacing large objects repeatedly.
4. Only store values you actually need later in the workflow or output.
5. If a missing value should stop the run, pair upsert_runtime_values with declare_task_failed.

​

Related Docs

• Focused Action
• Extract Prompt
• Looping Tools
• Generating Output Data