Skip to main content

​
What is Upsert Runtime Values?

upsert_runtime_values is a specialized tool for writing runtime variables explicitly during workflow execution. It is useful when the agent should do more than simply observe or extract text. Instead, it should store structured values that later workflow steps can reuse.
In prompts, always refer to this tool as upsert_runtime_values exactly.

​
When to Use It

Use upsert_runtime_values when you want to:
  • 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
Examples:
  • 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

upsert_runtime_values is not a general-purpose main-agent action. You will most commonly use it in: That means your top-level workflow prompt usually instructs a focused or extraction agent to call upsert_runtime_values as part of its work.

​
Basic Usage

The tool accepts JSON-like structured values keyed by runtime-variable name. Conceptually: 
{
  "report_path": "C:\\Reports\\output.pdf",
  "missing_file": true
}
After that, later steps can use:
  • {{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

upsert_runtime_values also supports Mongo-style operators for accumulating structured data instead of replacing it wholesale.
OperatorDescriptionExample
$appendAppend item to array{"items": {"$append": "new_item"}}
$prependPrepend item to array{"items": {"$prepend": "first"}}
$concatConcatenate arrays{"items": {"$concat": ["a", "b"]}}
$mergeShallow merge objects{"config": {"$merge": {"key": "val"}}}
$removeRemove first occurrence by value{"tags": {"$remove": "old"}}
$popRemove last element{"stack": {"$pop": true}}

​
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.