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

# Upsert Runtime Values

> Store, merge, and accumulate runtime variables during workflow execution

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

<Note>
  In prompts, always refer to this tool as `upsert_runtime_values` exactly.
</Note>

## 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:

* [`focused_action`](/workflow-prompting/focused-action)
* [`extract_prompt`](/workflow-prompting/extract-prompt) flows, especially async extraction agents

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:

```json theme={null}
{
  "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

```text theme={null}
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

```text theme={null}
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

```text theme={null}
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.

| 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 Across a Loop

```text theme={null}
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

```text theme={null}
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](/workflow-prompting/focused-action)
* [Extract Prompt](/workflow-prompting/extract-prompt)
* [Looping Tools](/workflow-prompting/looping-tools)
* [Generating Output Data](/concepts/generating-output-data)