Appearance
Workflow Design
A workflow runs its steps top to bottom, one at a time, by default. Each workflow step can change that: skip itself or end the run when a condition is false, loop over a list, run alongside its neighbours, pause for a signal, or run a whole other workflow. Control flow is declared on the workflow, not written into prompts, so the model handles only the steps that need judgement.
All of this is part of the workflow's definition. It is frozen into each published version and shown in the version diff.
The workflow graph
The workflow page's Graph card draws the definition (the draft or any published version) from Start to End, one row per step. Parallel groups appear side by side in a frame, conditions as if … chips with their else branches, for-each steps as for each <key>, and wait and sub-workflow steps with their own markers.
A run's page shows the same graph as its Path: each step's status (Completed, Failed, Running, Skipped, Pending or Not reached), duration, a link to its step instance or child run, and the route the run took highlighted. See the workflow graph runbook.
Step conditions
A condition is a JMESPath expression checked just before the step would run. It reads the run's inputs by key and earlier steps' outputs (structuredOutput_N, toolResult_N, modelResponse_N, iterationSummary_N). JMESPath truthiness applies: false, null, "", [] and {} are false, and a missing key reads as null.
When the condition is false, the step is Skipped and its else action applies:
| Else action | Effect |
|---|---|
Skip (default) | Continue with the next step. |
JumpTo | Skip ahead to a later step. The target must come after this step. |
EndRun | Skip every remaining step and complete the run. |
| Intent | Condition | Else |
|---|---|---|
| Finish when nothing was found | length(structuredOutput_1.candidates) > \0`` | EndRun |
| Route high severity to review | structuredOutput_2.severity == 'high' | JumpTo the review step |
| Optional enrichment | enrich == 'true' (a run input) | Skip |
Jumps only go forward, so a workflow can never loop. Saving checks the syntax and refuses a condition that reads a key the step or a later step produces. An expression that fails at run time fails the run (StepCondition.EvaluationFailed) rather than guessing. Each skipped step leaves a step instance that says why. Set conditions from a step's ⋯ menu in the designer, or with PUT /api/workflows/steps/condition. See the workflow conditions runbook.
For-each steps
A for-each step runs once per item of a list in context, instead of asking the model to loop over the list itself (which tends to drop items).
| Field | Purpose |
|---|---|
iterateOverKey | The context key holding the list, e.g. structuredOutput_1. |
itemContextKey | The key each item is placed under for its run of the step. |
separator | How the source is split into items. |
maxDegreeOfParallelism | Items at a time, 1–32 (default 1). |
Each item runs in its own scope: it sees the run's context plus its own item, never another item's work. A failed item is recorded and the loop continues. The step then promotes one aggregate structuredOutput_N (in item order) and an iterationSummary_N with the counts and failed items. Finished items are checkpointed, so an interrupted run redoes only the items that had not finished.
Parallel groups
Adjacent steps that don't depend on each other can form a parallel group: they run at the same time and join before the next step. Choose the group's first and last step in the designer (⋯ → Run in parallel…), or use PUT /api/workflows/steps/parallel-group.
| Failure policy | Effect |
|---|---|
FailFast (default) | The first failure stops the other members and fails the run. |
WaitForAll | Every member finishes, then the run fails if any member failed, reporting all failures. |
Members see the context as it stood when the group started, never each other's output, and their outputs are promoted in step order at the join. A group cannot contain a wait step or a for-each step, and a member's condition can only skip that member. Parallel work is bounded by Execution:MaxDegreeOfParallelism (default 8) and paced by each model provider's rate limits. See the workflow parallelism runbook.
Wait steps
A wait step pauses the run until an outside signal arrives, typically a human review of something an earlier step staged. The run goes to Waiting, frees its worker and keeps its place, so it survives restarts.
| Field | Purpose |
|---|---|
correlationContextKey | The context key whose value identifies what the run waits for, e.g. the staged proposal's id. |
outcomeContextKey | The key the arriving outcome is written to, for later steps (and conditions) to read. |
timeoutSeconds | Optional deadline. Without one, the run waits indefinitely. |
timeoutAction | Fail the run, ResumeWithTimeoutOutcome (with timeoutOutcome), ReNotify (remind and extend the deadline) or Escalate (notify escalationTarget, up to maxEscalations times). |
The outcome arrives as a review-outcome event on Service Bus, or through POST /api/runoperations/paused/resume. After a wait, the rest of the run continues as whoever resumed it: the reviewer, or the subscriber's system identity for an event. Runs can also pause mid-step for a tool confirmation or a clarification.
Sub-workflows
Common sequences ("resolve entity", "file finding") can be written once as their own workflow and reused as a child run, in two ways.
As a step. A sub-workflow step names a published workflow (pinned to a version, or the latest) and maps the parent's context into the child's inputs with JMESPath expressions. It waits for the child, then maps chosen child values back as its structuredOutput_N. It calls no model or tool of its own, and it works inside for-each steps and parallel groups.
As a tool. An agent of type Orchestrator has an allowlist of workflow tools, each a published workflow with a name, a description and input keys. Every model step the Orchestrator runs is offered them alongside the step's own tools. Calling one starts a child run, waits for it, and returns its output to the model. In a conversation thread, the same tool launches an ordinary run in the background instead.
Either way, the child can do nothing the parent could not. It has no identity of its own: it runs as the parent's agent, for the same principal. Its tokens and cost roll up into the parent's, and they count toward the parent's token budget. Cancelling the parent cancels the whole tree. Nesting is limited by Execution:MaxSubWorkflowDepth (default 3), and cycles are refused when saving and again at run time. A child workflow cannot contain a wait step. See the sub-workflows runbook.
Where a run cannot pause
For-each items, parallel group members and child runs run alongside other work, so they cannot pause the run. Inside them, a call to a tool that requires confirmation is declined, and a model asking for clarification is told no one can be asked. Put steps that may need a person at the top level of a workflow.
Related
- Steps & Workflows: steps, versions, run policy and limits.
- Runs: what a run records as it moves through these constructs.
- Agents: Orchestrator agents and their workflow tools.