Agent Workflows and State Machines

Learn how to structure agents as workflows: sequential and conditional flows, branching, parallel execution, explicit state transitions, and checkpoints that let a run resume after a failure.

30 minIntermediateCode Examples

The Core Idea: A workflow is a graph of steps. Each step does some work, updates the state and names the next step. Explicit branches, parallel steps and checkpoints make agents predictable and recoverable.

  1. Beginner: Sequential Workflows

A sequential workflow runs steps in a fixed order: classify the question, then research, then draft, then review. The language model can be used inside some steps, but your code decides the order.

Free agent loopWorkflow
Who picks the next stepThe model, every timeYour code, from a graph
PredictabilityLowerHigher
FlexibilityHigherLower
Best forOpen-ended tasksKnown processes with some model steps

Practical advice: Many successful products use workflows with small agent-like steps inside, because they are easier to test and cheaper to run.

  1. Beginner: Conditional Workflows and Branching

A conditional step looks at the state and chooses where to go next. This is branching:

ConditionBranch
Question mentions an invoiceBilling path
Question is technicalTechnical path
Draft failed the reviewGo back to drafting
Confidence is lowAsk a human

In the code: The classify step sets the kind of question, and the review step either approves the draft or sends the run back to draft. That second case is a loop inside the workflow.

  1. Medium: Parallel Execution

When subtasks do not depend on each other, run them at the same time. In the code, three sources are searched in parallel, so the total time is about that of the slowest one instead of the sum of all three.

PatternDescription
Fan-outStart several steps at once
Fan-inWait for all and combine the results
RaceUse the first good result and cancel the rest

Careful: Parallel steps must not write to the same state at the same time. Give each its own output and merge afterwards.

  1. Medium: State Transitions

Think of the workflow as a state machine: it is always in one state (a step), and each step ends by returning the next state. All the data lives in a shared state object.

PartRole
NodesSteps that do work
EdgesAllowed moves from one node to another
State objectData passed along and updated
Terminal statedone or failed
Why explicit states help
You can draw the machine, test each node alone, see exactly where a run is, and forbid illegal moves, which prevents many agent bugs.

  1. Advanced: Checkpoints

A checkpoint saves the state after each step. If the process crashes, is restarted or must wait for a human, the run resumes from the last checkpoint instead of starting over.

1
After every node: Write the state and the name of the next node to storage.
2
On start: Look for a checkpoint. If one exists, load it.
3
Continue: Run from the saved next node.
4
Clean up: Remove or archive checkpoints when the run finishes.

In the code: The run crashes after the research step. After a restart it loads the checkpoint and continues at the draft step. The classify and research work is not repeated.

Tip: Make steps idempotent (safe to run twice) so a resume after a partial step does not duplicate effects like sending an email.

  1. Visual Explanation: A Workflow With Branches, Parallel Steps and a Checkpoint

The figure shows the four nodes of the workflow in the code, then what happens when the run crashes and resumes.

Part 1 · The Workflow in the CodeBranch, parallel, loop
classifyBranch
Billing or technical?
↓
Chooses the path
researchParallel
3 sources searched at once
↓
Facts combined
draftWork
Writes an answer
↓
Goes to review
reviewLoop
First draft rejected, second approved
↓
done
Part 2 · A Crash and a ResumeCheckpoints save the day
Ran
Before crash
classify, research.
Crash
Process dies
Memory lost.
Load
Checkpoint
State and next node restored.
Resume
draft
No repeated work.
Click to see why steps should be idempotentCompare ▼
After a crash a step might run twice. If the step sends an email, the customer receives two. Idempotent steps, or an idempotency key, make a repeat harmless.

Part 1 labels each node with the pattern it demonstrates. Part 2 shows the crash and the resume. Open the bar to see why idempotent steps matter.

  1. Python Implementation: A State Machine With Parallel Steps and Checkpoints

This script implements a four-node workflow. It branches on the question type, searches three sources in parallel, loops between draft and review, saves a checkpoint after every node, simulates a crash, and resumes from the checkpoint.

workflow_state_machine.pyPython 3.10+ · standard library only
import json, os, tempfilefrom concurrent.futures import ThreadPoolExecutor CHECKPOINT = os.path.join(tempfile.mkdtemp(), "run.json") def save(state, next_node):    with open(CHECKPOINT, "w") as f:        json.dump({"state": state, "next": next_node}, f) def load():    with open(CHECKPOINT) as f:        data = json.load(f)    return data["state"], data["next"] # Each node does some work and names the next node (that is the state transition)def classify(s):    s["kind"] = "billing" if "invoice" in s["question"] else "technical"      # conditional branch    return "research" def research(s):    sources = ["knowledge_base", "faq", "tickets"]    with ThreadPoolExecutor(max_workers=3) as pool:                          # parallel execution        s["facts"] = list(pool.map(lambda name: "fact from " + name, sources))    return "draft" def draft(s):    s["attempts"] = s.get("attempts", 0) + 1    s["draft"] = "Answer built from " + str(len(s["facts"])) + " facts"    return "review" def review(s):    return "done" if s["attempts"] >= 2 else "draft"                         # first review rejects: loop back NODES = {"classify": classify, "research": research, "draft": draft, "review": review} def run(state, node, crash_after=None):    while node != "done":        finished = node        node = NODES[node](state)        save(state, node)                                                    # checkpoint after every node        print("ran", finished.ljust(9), "-> next:", node)        if finished == crash_after:            print("*** process crashed ***")            return None    return state state = {"question": "Why was my invoice charged twice?"}run(state, "classify", crash_after="research") print("--- restart: load the checkpoint and continue ---")state, node = load()final = run(state, node)print("Result:", final["kind"], "|", final["draft"], "| attempts:", final["attempts"])
EXPECTED OUTPUT (your numbers may differ slightly)
ran classify -> next: research
ran research -> next: draft
*** process crashed ***
--- restart: load the checkpoint and continue ---
ran draft -> next: review
ran review -> next: draft
ran draft -> next: review
ran review -> next: done
Result: billing | Answer built from 3 facts | attempts: 2

After the crash the run reloads its state and continues at the draft node. The review step rejects the first draft and approves the second, so draft runs twice, and the final state contains the type of question, the draft and the number of attempts.

Knowledge Check

Question 1: What is a checkpoint?
Question 2: Why run independent steps in parallel?

Key Points

✓A workflow is a graph of steps where your code controls the order.
✓Sequential flows run in a fixed order, conditional flows branch on the state.
✓Parallel execution runs independent steps at once (fan-out, then fan-in).
✓A state machine has nodes, edges, a shared state object and terminal states.
✓Checkpoints save the state after each step so runs can resume after a failure.
✓Make steps idempotent so that a repeat after a crash is harmless.

The Big Picture

Workflows in One Line

Nodes do work → return the next node → state is saved after each one → crashes become resumes

Workflows make agents predictable. Next you will make them reliable when things go wrong.

Up Next: No agent runs perfectly forever. In Error Handling and Recovery you will learn retries, fallbacks, timeouts and how to stop endless loops.