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.

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.

Do not use variants for these cases:

Situation	Use instead
Only data differs per run (a URL, an ID, a date).	Inputs
Only credentials differ per run.	Profiles and 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. 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 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.

• 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
Batches	One column mapped to Variant Key. Each row carries its own key.
Schedules	executionOptions.variantKey. Checked when the schedule is created.

{
  "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, you can work in one variant. Only that variant’s files load.