Case UW-006 is an ordinary request. A broker asks for a quote on a building with a 12-year-old roof (SUB-1006). The intake agent writes the submission, and the orchestrator asks the roof-data provider for its view of the roof. The provider does not answer. After 2,000 simulated milliseconds the call times out.
What runs next?
A list of steps cannot say. "intake, gather evidence, check eligibility, draft, ..." describes the day when everything answers. It has no line for a timeout. Should the orchestrator call the provider again? How often? If the second call fails too, should the run stop, or continue without the roof assessment, and if it continues, what may it recommend without that evidence?
Case UW-003 asks a similar question from the other side. The owner does not know the roof age, and the provider has no record. Every lookup answers, and the facts still do not allow approve or decline. Something has to choose another path.
The answers to both cases are built from three moves, the same three a first programming course teaches: do this then that, choose on a condition, repeat until done. This page names them for workflows, adds the five words an orchestrator needs to apply them, and writes the whole quote workflow with nothing else. On the Start page orchestration was defined as the logic that decides what runs next; here that logic gets its parts.
The agents here are scripted stand-ins and time is simulated, so these results show how the orchestration works, not how good or how fast any model is.
A step, and steps in sequence#
Start with the unit. A step is one piece of work that the orchestrator starts, waits for, and records. Looking up the roof is a step. Applying the rules is a step. Waiting for the underwriter is a step too: it starts, and it ends when a person acts. The orchestrator does not see inside a step; it sees that the step started, whether it succeeded, and what it returned.
The first move is the sequence: steps run one after another, and each starts only when the one before has finished. In the quote workflow the rules need the evidence and the evidence needs the submission, so check_eligibility comes after gather_evidence, which comes after intake. A sequence writes down a dependency.
In the example, the sequence of pipeline mode is a plain list in workflow.py:
DAG_STEPS = ["intake", "gather_evidence", "check_eligibility", "draft_recommendation", "verify_process",
"record_recommendation", "await_underwriter", "apply_decision"]
Case UW-002 walks it straight through: a masonry warehouse, roof 8 years, sprinklered. Its run takes the eight steps in order, with no retry and one decision by the underwriter. Its path line in the runner's output reads intake > gather_evidence > check_eligibility > draft_recommendation > verify_process > record_recommendation > await_underwriter > apply_decision.
A sequence is the easiest move to reason about, because there is one path. Its price is waiting. Each step waits for the one before, even when it does not need that step's result. The three lookups of gather_evidence do not depend on each other, which is why the example runs them at the same time inside one step; Concurrency is the home of that idea.
A condition picks a branch#
The second move answers UW-003. A condition is a yes-or-no test on what the run knows. "Is the roof age known?" is a condition. "Do the two roof ages differ by more than 5 years?" is another. A branch is the choice it drives: when the condition is true the run goes one way, otherwise another.
The quote workflow branches four ways on the outcome of the rules. The rules come from the policy fixture, an illustrative rule set invented for this series, and the function that applies them is plain code, core.py:check_rules. This is it, whole. A successful call proves only that these conditions give this outcome for these facts; it says nothing about whether the rules are good insurance practice, which they are not meant to be.
def check_rules(facts: dict[str, Any], rules: dict[str, dict[str, Any]]) -> dict[str, Any]:
"""The deterministic eligibility rules of the policy fixture. Same input, same result.
`facts` is the submission plus what the lookups added:
`provider_roof_age_years` and `roof_assessment_status` ("unavailable" when the lookup failed).
"""
app, prov = facts.get("roof_age_years"), facts.get("provider_roof_age_years")
if facts.get("roof_assessment_status") == "unavailable":
return {"outcome": "request_info", "rules": [], "missing": ["roof_assessment"]}
if app is None and prov is None:
return {"outcome": "request_info", "rules": ["R-ROOF-02"], "missing": ["roof_age_years"]}
if app is not None and prov is not None and abs(app - prov) > rules["R-ROOF-03"]["max_gap_years"]:
return {"outcome": "escalate", "rules": ["R-ROOF-03"], "missing": []}
age = prov if prov is not None else app
roof = rules["R-ROOF-01"]
if age > roof["max_roof_age_years"] and facts.get("wind_zone") == roof["wind_zone"]:
return {"outcome": "decline", "rules": ["R-ROOF-01"], "missing": []}
if (facts.get("occupancy") == "warehouse" and not facts.get("sprinklered")
and facts.get("area_sq_ft", 0) > rules["R-SPRK-01"]["max_area_sq_ft"]):
return {"outcome": "escalate", "rules": ["R-SPRK-01"], "missing": []}
return {"outcome": "approve", "rules": [], "missing": []}
Read it as a chain of branches, checked in order, with exactly one exit taken. For UW-003 both roof ages are None, so the second test is true and the run branches to request_info with missing = roof_age_years, citing R-ROOF-02. For UW-004 the application says 9 and the provider 22, so the third test sends it to escalate. For UW-001, a 31-year-old roof in wind zone C, the fourth sends it to decline. The order is part of the logic: a disputed roof age is escalated before anyone compares it with the limit, because nobody yet knows which age is true.
The recommendation these branches lead to is a proposal. The model recommends; a person decides. Every branch ends in the same next step, await_underwriter.
Common confusion. A condition is not a prompt instruction. "Escalate when the roof ages differ a lot" in a prompt is a request that a model may read differently on another day. abs(app - prov) > 5 in code is a condition: the same facts give the same answer every time, and a test can prove it.
A loop repeats until a termination condition holds#
The third move answers UW-006. A loop runs a step again until something says stop. That something is the termination condition: the test which, once true, ends the loop. For the roof lookup it reads: stop when the provider answered, or when no attempts are left.
Each try of the lookup is an attempt, counted by attempt_number, which starts at 1 for each step of each run. In the example, the loop around a tool call is engine.py:StepContext.call_with_retry. Before reading it, know what it proves: that the loop ends after at most max_attempts tries whatever the tool does, and that each try is recorded with its number. It does not prove that two attempts is the right number; that is a choice, and an illustrative one here.
def call_with_retry(self, name: str, outcome_for_attempt: Callable[[int], str], duration_for: Callable[[str], int],
max_attempts: int = 2, backoff_ms: int = 500) -> dict[str, Any]:
"""Call a tool; on a timeout or error wait `backoff_ms` and try again while attempts are left.
Each attempt is its own span with its attempt_number. Returns the last outcome and the attempts used.
"""
outcome = "error"
for attempt in range(1, max_attempts + 1):
outcome = outcome_for_attempt(attempt)
start = self.run["clock_ms"]
self.tick(duration_for(outcome))
ok = outcome in ("ok", "slow")
self.span(name, "tool", start, self.run["clock_ms"], "ok" if ok else "error", attempt_number=attempt,
outcome=outcome)
self.engine.log_tool(self.run, name, attempt, outcome, self.step.name)
if ok:
return {"outcome": outcome, "attempts": attempt, "ok": True}
if attempt < max_attempts:
self.event("tool_retry_scheduled", {"tool": name, "next_attempt": attempt + 1, "backoff_ms": backoff_ms})
self.tick(backoff_ms)
return {"outcome": outcome, "attempts": max_attempts, "ok": False}
The termination condition is written twice in that loop, and both halves matter. if ok: return ends it on success. The bound of range ends it on failure. A loop with only the first half waits for a provider that may never answer.
This method is used by loop mode; in pipeline mode the three lookups of gather_evidence run the same rule inside core.py:simulate_fanout. The command runs UW-006 in pipeline mode. A successful run shows two attempts of the roof lookup, both timed out, and the run continuing on another branch.
cd examples/uw-orchestrator
/opt/homebrew/bin/python3 run.py --case UW-006
Quote workflow · scripted stand-in agents (no model called) · simulated time · seed 7
UW-006 · The roof-data provider times out · dag mode · run-7641 · trace 277e5cb91254...
path: intake > gather_evidence > check_eligibility > draft_recommendation > verify_process > record_recommendation > await_underwriter
attempts: get_roof_assessment attempt_number 2 timeout
fan-in: roof_assessment failed [timeout, timeout], guidance ok [ok], similar_decisions ok [ok] · missing roof_assessment
guard: pass (Eligibility ran and every cited rule was retrieved.)
recommendation: request_info · cites - · missing roof_assessment · policy 2026.2 · stored row status stored
human_decision: none yet (waiting for: underwriter)
status: suspended · model calls 3 · tool calls 5 · simulated time 7.3 s
expected: as stated in the case
wrote 1 run file(s) in out/runs/ and out/summary.json
The loop ended because no attempts were left: [timeout, timeout]. Then a branch took over. The roof assessment is required, so its absence sends the run to request_info with missing = roof_assessment, and the underwriter receives a recommendation that says plainly what could not be checked. Two moves, a loop and then a branch, answer the question this page opened with.
Production pitfall. The dangerous loop is the one whose only exit is a model deciding it is done. In loop mode of the example, caseUW-904has a stand-in model that keeps searching the guidance with new wording. Its loop ends after 6 turns because a budget in code says so (budget_exhausted:turns), and code, not the model, then writes an escalation. Limits is the home of budgets.
State and transition: how the orchestrator chooses#
Two more words turn the three moves into something a program can execute.
The state of a run is everything the orchestrator has written down about it so far: its status (running, suspended, completed, failed, cancelled), the current step, and the status and result of every step. After the lookups of UW-006, the state says: running; gather_evidence succeeded; its result says that roof_assessment is missing.
A transition is a move from one state to another, caused by an event such as a step finishing. Each step of the quote workflow lists its transitions, and each transition has a condition. The two transitions out of gather_evidence are an excerpt of workflow.py:build_workflow:
"gather_evidence": Step("gather_evidence", step_gather_evidence, [
Transition("check_eligibility", lambda r: r["steps"]["gather_evidence"]["output"]["decision"] == "continue",
"fan-in complete: required evidence arrived"),
Transition("check_eligibility", ALWAYS, "fan-in: a required lookup is missing; the rules step records request_info"),
], agent="assessment agent"),
Both lead to the same next step, with different reasons; the rules step then records request_info when a required lookup is missing. The engine picks between them with the smallest piece of orchestration in the example, engine.py:Engine.next_step:
def next_step(self, run: dict[str, Any], step: Step) -> str | None:
"""The first transition whose guard is true decides what runs next."""
for t in step.transitions:
if t.guard(run):
self.event(run, "transition", step.name, {"to": t.to, "because": t.label})
return t.to
raise IllegalTransition(f"no guard of step {step.name} is true")
Three decisions sit in those six lines. The first true condition wins, so the order of transitions is part of the workflow. The choice is written to the event log with its reason. And if no condition is true, the engine raises an error instead of guessing. Spring Batch makes the same choice for its conditional flows: its documentation says that when a step's exit status matches no transition, "the framework throws an exception and the Job fails".
Diagram: State and transition · what the orchestrator writes down after one step, and how it picks the next
Read left to right for one moment of run UW-006. A step ends and changes the state. The orchestrator reads the transitions of that step in order and takes the first one whose condition is true. It saves the state, then starts the step the transition named.
- 1 · A step ends
- gather_evidence: The step returned a result. Its status moves from running to succeeded.
- 2 · The state
- Run state: What the orchestrator has recorded about the run so far: its status, the current step, each step's status and result.
- 3 · Pick the transition
- Transition 1: Its condition: the required lookups arrived. False here, so it is not taken.
- Transition 2: Its condition is always true. It goes to the same next step, which then records request_info.
- 4 · Save, then go on
- Checkpoint: The orchestrator saves the state and starts the next step. A restart would continue from here.
The event log of UW-006 shows the whole cycle for the first two steps: start, succeed, transition with its reason, save. These are events 1 to 15 of 34 from run.py --case UW-006 --verbose; the README of the example prints all of them.
1 0 ms run_started {"policy_version":"2026.2"}
2 0 ms checkpoint_saved
3 0 ms step_started intake {"attempt_number":1}
4 800 ms step_succeeded intake {"attempt_number":1}
5 800 ms transition intake {"to":"gather_evidence","because":"submission ready"}
6 800 ms checkpoint_saved intake
7 800 ms step_started gather_evidence {"attempt_number":1}
8 1550 ms lookup_attempt gather_evidence {"tool":"find_similar_decisions","attempt_number":1,"outcome":"ok","late":false}
9 1640 ms lookup_attempt gather_evidence {"tool":"search_guidance","attempt_number":1,"outcome":"ok","late":false}
10 3400 ms lookup_attempt gather_evidence {"tool":"get_roof_assessment","attempt_number":1,"outcome":"timeout","late":false}
11 5900 ms lookup_attempt gather_evidence {"tool":"get_roof_assessment","attempt_number":2,"outcome":"timeout","late":false}
12 5900 ms fan_in gather_evidence {"aggregated":["guidance","similar_decisions"],"missing_required":["roof_assessment"],"missing_optional":[],"d
13 5900 ms step_succeeded gather_evidence {"attempt_number":1}
14 5900 ms transition gather_evidence {"to":"check_eligibility","because":"fan-in: a required lookup is missing; the rules step records request_info
15 5900 ms checkpoint_saved gather_evidence
Event 14 is the second transition being taken, with its reason. Event 15 is the state being saved before the next step starts, so a restart would continue from check_eligibility; Durable workflows builds on that line.
For a backend engineer. A step is a Spring BatchStep, a sequence isstart(a).next(b), and a branch ison("FAILED").to(c). The retry loop is what a@Retryablemethod gives you; in Spring Framework 7 itsmaxRetriescounts the retries after the first call, so two attempts here ismaxRetries = 1there. The state is what aJobRepositorystores between executions. The comparison stops at the model: no batch step chooses the next step itself, and in loop mode of the example a model does exactly that, inside one step, which is why that loop needs a budget a batch job never needed.
The whole quote workflow, with three moves#
Put the moves together and the quote workflow needs nothing else. A sequence from intake to the rules. A loop around the roof lookup. A branch on the rule outcome. A sequence into the wait for a person.
Diagram: The quote workflow with three moves only · a sequence, one loop, one branch
Read left to right. The arrows between columns are the sequence: one step after another. The second column is a loop: try the roof lookup, and try again while attempts are left. The fourth column is a branch: the rule outcome picks exactly one of four routes. Every route then waits for a person. Click a box to see which case takes it.
- 1 · Sequence
- intake: The first step. Nothing else can start before the submission exists.
- 2 · Loop
- get_roof_assessment: Repeats while the lookup fails and attempts are left. The termination condition: an answer, or no attempts left.
- 3 · Sequence
- check_eligibility: Evaluates the conditions of the policy fixture on the facts. Same facts, same outcome.
- 4 · Branch
- approve: Taken when no rule blocks the submission.
- decline: Taken when the roof is over the limit in wind zone C.
- request_info: Taken when the roof age is unknown, or the provider never answered.
- escalate: Taken when the two roof ages differ by more than 5 years.
- 5 · Sequence
- await_underwriter: Every branch ends here: the run waits for an underwriter, or a senior underwriter for an escalation.
The example has a function that walks exactly this, for three facts of a submission and a number of provider timeouts: core.py:primitives_walk. It is a teaching reduction of the real workflow (no fan-out, no draft, no guard, no write), and it is the function behind the lab below. The script calls it for two settings. A successful run proves that the same three moves give a different route when one timeout is added; it does not prove anything about the full engine, which the earlier commands showed.
import core
from tools_sim import rules_for
rules = rules_for("2026.2")
for label, args in (("UW-001 facts", [True, 31, "C", 0]), ("Provider times out twice", [True, 12, "B", 2])):
r = core.primitives_walk(*args[:3], rules, args[3])
print(label, "->", r["route"], "| loop turns", r["loop_turns"])
for w in r["walk"]:
print(f" {w['primitive']:<8} {w['step']:<20} {w['note']}")
UW-001 facts -> decline | loop turns 1
sequence intake Email to submission.
loop get_roof_assessment attempt 1: answer
sequence check_eligibility Deterministic rules, in code.
branch decline R-ROOF-01
sequence await_underwriter A person decides.
Provider times out twice -> request_info | loop turns 2
sequence intake Email to submission.
loop get_roof_assessment attempt 1: timeout
loop get_roof_assessment attempt 2: timeout
sequence check_eligibility Deterministic rules, in code.
branch request_info missing roof_assessment
sequence await_underwriter A person decides.
Every line is labelled with the move it is. The first walk turns the loop once and branches on a rule. The second turns it twice, ends it on the bound, and branches on a missing fact. Set the facts yourself in the lab; the table after it holds five settings and their results.
| Setting | Roof age known | Roof age | Wind zone | Provider timeouts | Loop turns | Branch taken | Why |
|---|---|---|---|---|---|---|---|
Facts of UW-001 | yes | 31 | C | 0 | 1 | decline | R-ROOF-01 |
Facts of UW-002 | yes | 8 | A | 0 | 1 | approve | no rule applies |
Facts of UW-003 | no | B | 0 | 1 | request_info | R-ROOF-02, missing roof_age_years | |
| Provider times out once | yes | 12 | B | 1 | 2 | approve | no rule applies |
| Provider times out twice | yes | 12 | B | 2 | 2 | request_info | missing roof_assessment |
Rows four and five are the lesson of the page in one comparison. The building is the same. One more timeout ends the loop on its bound instead of on an answer, and the branch then takes a different route. The orchestration, not the facts of the building, decided the difference.
Who decides what runs next here#
For the three moves in the quote workflow, code decides. The sequence is a list in workflow.py. Every condition is a Python expression over recorded state. Every loop has a termination condition in code: two attempts for a lookup, a budget for the agent loop. A model decides only inside one step, in loop mode, which lookup to call next, and even there the loop's end is written in code. A person decides the one thing no move of the workflow decides: the underwriter's decision, which arrives from outside and ends the wait.
What this is not. The loop inside one agent, where the model asks for a tool turn after turn, is a loop in this page's sense, but its runtime is owned by Harness Engineering. How often a call should be retried in production, and what that does to a struggling service, is an operational guarantee owned by Agent Reliability. This page names the moves; those sites own their engineering.
The same idea in a coding agent. A coding agent runs a sequence (plan, edit, test, open a pull request), a branch (the tests pass or fail) and a loop (edit and test again). Its termination condition is the same pair as the roof lookup's: the tests pass, or the turn limit is reached. A coding agent that has only the first half keeps editing until something outside stops it.
Every orchestration framework offers these three moves under its own names: a list or chain of steps, conditional edges or routes, and a retry policy or loop with a maximum. When you read one, look for where the termination condition of each loop is written, and what happens when no branch matches. Frameworks reads the products on their own documentation.
Checklist#
- Every step has a name, and the orchestrator records its status and result.
- Every sequence reflects a real dependency; steps that do not depend on each other are not forced into a line.
- Every branch covers every outcome, and a state that matches no condition raises an error instead of falling through.
- Every condition is code over recorded state, not an instruction in a prompt.
- Every loop has a termination condition in code that becomes true even if the model never stops.
- A loop that ends without success leads to a named route, such as
request_info. - Every transition writes its reason to the event log.
The order of conditions is part of the workflowFirst true wins, so reordering two checks changes routes
Both check_rules and Engine.next_step take the first condition that is true. Two conditions can be true at once, and then their order decides the route. A submission with a disputed roof age (application 9, provider 31) and wind zone C satisfies both the R-ROOF-03 test and, by the provider's age, the R-ROOF-01 test. check_rules escalates, because the dispute is checked first. Swap the two tests and the same submission is declined on an age nobody has confirmed.
So a review of a workflow reads the order, not only the set of conditions. Two habits help. Write overlapping conditions in order of authority (a dispute to settle before a limit to apply) and say why in a comment. And test the overlaps on purpose: one case per pair of conditions that can both be true. Case UW-907, this site's own, sits on such a boundary (roof 25 on the application, 26 from the provider), and the guard routes it to a senior underwriter.
Termination that does not depend on the modelBounded loops, and the difference between ending and succeeding
A loop terminates when its termination condition becomes true. For a retry loop with a fixed number of attempts this is guaranteed by the bound. For an agent loop it is not: the model may never choose to finish. The example's agent loop therefore checks core.py:budget_check before every turn against four limits (6 turns, 8 tool calls, 12,000 simulated tokens, 30,000 simulated ms, all illustrative) and records which one ended it.
Ending is not succeeding. A loop that ends on its bound has produced no answer, and the workflow must say what happens next. The quote workflow always has an answer: a missing required lookup leads to request_info, and an agent loop ended by its budget leads to an escalation written by code (workflow.py:loop_draft). The termination reason is recorded in the run (termination_reason), because "finished" and "budget_exhausted:turns" mean different things to the person who reads the run later.
A wall-clock limit deserves a note. In the example, time is simulated and a limit on it is exact. In a real system a step that is already running when the limit passes must be interrupted or abandoned, and an abandoned call may still complete later and change something. Failures treats timeouts with that complication.
What must be in the stateIf the next decision needs it, it must be recorded, not held in a variable
The orchestrator decides the next step only from the state, so anything a later condition reads must be in the state when that condition runs. In the example, the result of gather_evidence carries decision, missing_required and missing_optional; the transitions and the rules step read those fields, not a local variable of the step.
This is what makes a restart possible. Engine.new_run keeps everything in one dictionary, and Engine.checkpoint saves a deep copy of it after each step. A process that dies loses its variables but not the checkpoint; Durable workflows shows case UW-901 resuming from it. The design choice here, saving the whole state after every step, is simple and costs one write per step. Storage design for such state belongs to Memory Engineering.
Two things are deliberately not in the state of the example: the model's working context (it belongs to the step that built it) and long-lived knowledge such as past decisions (it belongs to a store the step reads). Mixing them into the run state makes every checkpoint larger and every restart slower.
Two kinds of loop in one workflowA retry loop repeats the same work; an agent loop chooses different work
The quote workflow has two loops that look alike and are not. The retry loop repeats the same call with the same input; its only question is whether to try again. The agent loop of loop mode chooses a different tool each turn; its question is what to do next. The first has a fixed bound and a known worst case (two attempts, one backoff). The second has a path that varies between runs: case UW-010 takes 9 distinct paths in 20 trials in loop mode, and one path in pipeline mode.
Because of that, the two need different controls. A retry loop needs a bound, a backoff, and a call that is safe to repeat. An agent loop needs a budget, a permission list for its tools, and a check of its result at the exit. Shapes treats the agent loop as a shape of its own, and Control plane shows the guard at its exit.
In one breath#
Every workflow is a sequence of steps, a branch where a condition picks one path, and a loop that repeats until a termination condition holds. The orchestrator keeps the state of each run, and after every step it takes the first transition whose condition is true, writes down why, and saves. In the quote workflow all of those conditions are code: a timeout loops twice and then branches to request_info, a disputed roof age branches to escalate, and nothing ends a loop except a condition the model cannot override. A person decides only the one thing that is theirs: the decision at the end.
The three moves can describe the whole quote workflow, but they do not yet say how to write it down so that an engine can check it: which moves are legal from which state, which steps may run at the same time, what reacts to a person's decision arriving two days later, and what changes when a model picks the next step. Four common ways of writing that down, and what each one cannot express, are the subject of Shapes.