> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asteroid.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Variants

> Run one workflow for many entities, each with its own scripts and files, selected by a variant key on every execution.

Variants let one workflow serve many entities. The graph, instructions and transitions are shared. Each entity, such as a clinic, gets its own scripts and files. Every execution names its entity with a **variant key**. Asteroid then loads that variant's files and no other variant's.

## When to use variants

Use variants when all of these hold:

* Many entities run the **same steps in the same order**. One graph fits all of them.
* The **details differ per entity**. Each one sets its own fields, default values or selectors.
* The number of entities is large or growing. Tens to hundreds of keys is normal.
* A fix to the graph or the instructions must reach **every** entity at once.

<Info>
  **Example: patient creation across clinics.** Every clinic runs the same flow in the EHR: search for the patient, open the new-patient form, fill it, save. The clinics differ only in small details. One clinic sets a default registration type. Another requires a referral source. Another files new patients under a named practitioner. Each clinic gets its own `fill_patient_form.js` that sets its own fields. The graph stays shared.
</Info>

Do not use variants for these cases:

| Situation | Use instead |
| - | - |
| Only data differs per run (a URL, an ID, a date). | [Inputs](/concepts/inputs-and-outputs) |
| Only credentials differ per run. | [Profiles](/concepts/profiles) and [credentials](/concepts/credentials) |
| The graph differs per entity (other nodes, other branches). | Separate workflows |
| A few entities with unrelated flows. | Separate workflows |
| Comparing two prompt or graph versions. | [Versions](/concepts/versions). A variant key does not change which workflow runs. |

## Turning it on

Variant mode can only be turned on by an Asteroid admin. Please reach out if you'd like variant mode to be turned on on your workflow.

## File layout

Per-variant files live under a `variants/<key>/` directory inside a node's shared folder. Files outside `variants/` are node-level and shared by every variant.

```
shared/<node-slug>/
  scripts/save_patient.js                          every variant gets it
  variants/
    northside_clinic/scripts/fill_patient_form.js  only runs with key northside_clinic
    northside_clinic/notes.md
    riverside_practice/scripts/fill_patient_form.js
```

Before an execution starts, Asteroid restores the node-level files plus the files of that execution's variant. Other variants' files are not restored. This applies to every node, including Agent nodes with no script. An Agent node sees only its own variant's notes and helpers.

See [Workflow filesystem](/concepts/filesystem) for the rest of the layout.

## Scripts: the `{{variant_key}}` placeholder

A node's `script_filepath` may contain the `{{variant_key}}` placeholder. Asteroid replaces it with the execution's key before it runs the script.

```
./variants/{{variant_key}}/scripts/fill_patient_form.js
  -> shared/<node-slug>/variants/northside_clinic/scripts/fill_patient_form.js
```

Publishing checks these rules:

* The placeholder appears exactly once.
* It is the segment directly under `variants/`. `./scripts/{{variant_key}}.js` is rejected.
* The workflow has variant mode on. The placeholder without it is rejected.

Write the literal `{{variant_key}}` in `script_filepath`. Directories use the real key.

Nodes can mix both kinds of path. One node can run a shared `./scripts/search_patient.js` while the next runs a per-variant script.

## When a variant has no script yet

A new variant often has no script yet. The script run then fails because the file is missing. `script_failure_action` decides what follows. See [Nodes](/concepts/nodes).

* `fallback_to_ai`: the model does the node's work from its instructions. Use this where a new variant must still run before its script exists.
* `cancel_execution`: the execution stops. Use this only where a script must exist.

A common pattern: run a new variant with `fallback_to_ai`, then save the working script under `variants/<key>/`. Later runs take the scripted path.

## Variant keys

Asteroid turns every key into a slug. It lowercases the key, collapses runs of other characters to `_`, trims a leading or trailing `_`, and cuts the key to 80 characters. `Northside Clinic` becomes `northside_clinic`. A key with no letter or digit is rejected.

Use a stable ID from your own system as the key. A display name that changes later leaves the old variant's files unused.

With variant mode on, every execution must carry a key:

| Trigger | Where the key goes |
| - | - |
| API | `executionOptions.variantKey` on the [execute request](/integrate/call-an-agent) |
| [Batches](/operate/batches) | One column mapped to **Variant Key**. Each row carries its own key. |
| [Schedules](/operate/schedules) | `executionOptions.variantKey`. Checked when the schedule is created. |

```json theme={null}
{
  "inputs": { "patient_name": "Jane Doe" },
  "executionOptions": { "variantKey": "northside_clinic" }
}
```

## Browsing variants

* The workflow's file view has a variant switcher. Pick one key to see only that variant's files.
* When you edit a workflow with [Astro](/build/in-the-platform), you can work in one variant. Only that variant's files load.