Skip to content
Tutorials Center
My learning

Topics

Lesson 34 of 39 ยท Frameworks and Deployment

Structured Agent Workflows and Graphs

Model an AI agent as a graph of steps with shared state, conditional edges, loops and checkpoints, and build a tiny runnable graph engine in Python.

A free-running agent loop ("think, call a tool, repeat") is flexible but unpredictable. Many real tasks have a known shape: classify the request, fetch data, draft a reply, check it, then send. For these, a workflow gives you control: you decide the steps and the model fills in the intelligence inside each step. A popular way to describe workflows is a graph: boxes (nodes) joined by arrows (edges), with a shared state moving through them.

In this lesson you will learn the difference between workflows and autonomous agents, how nodes, edges, state and checkpoints work, and you will build a working graph engine in plain Python with conditional branching and a retry loop.

Several frameworks offer graph engines for agents; none can run on this site. The engine below is a small plain-Python stand-in that shows the core ideas. The nodes are deterministic functions standing in for model calls.

Workflow or agent?

  • A workflow has a predefined path. Code decides what happens next. It is predictable, cheaper, easier to test and debug.
  • An agent lets the model decide the path. It can handle open-ended tasks, but is less predictable and costlier.

Most production systems are a mix: a workflow skeleton with one or two agentic steps inside it. A good rule: use the least autonomy that solves the problem. Reach for a free-running agent only when the steps genuinely cannot be known in advance.

Graph vocabulary

flowchart TD
  S["classify"] -->|"question"| A["retrieve"]
  S -->|"complaint"| B["escalate"]
  A --> D["draft"]
  D --> C["check"]
  C -->|"fails"| D
  C -->|"passes"| E["send"]

A support workflow. The check node can loop back to the draft node.

  • State: one shared object (usually a dictionary) holding everything the run knows: the input, retrieved documents, the draft, counters.
  • Node: a step. It reads the state and returns updates to it. A node may call a model, a tool or plain code.
  • Edge: a transition to the next node. It can be fixed or conditional (a function reads the state and picks the next node).
  • Start and end: where the run begins and where it stops.
  • Checkpoint: a saved copy of the state after each node, so a run can pause, resume or be replayed.

A tiny graph engine

Nodes return a dictionary that is merged into the state. Edges are either a node name or a function that picks one. A step limit stops accidental infinite loops.

Python Run a graph with a conditional branch

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice how readable the control flow is. The whole behavior is in NODES and EDGES, so you can print it, draw it and test each node alone.

Loops: draft, check, revise

A graph can contain cycles, which is how you build revise-until-good flows. Keep a counter in the state and exit after a maximum number of attempts.

Python A revise loop with an attempt limit

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The attempt cap is not optional. Without it, a stubborn checker plus a weak drafter loops forever and burns money.

Checkpoints and persistence

If the engine saves the state after every node, you gain:

  • Resume after a crash: restart from the last checkpoint instead of the beginning.
  • Human approval: pause at a node, wait days, then continue (see human-in-the-loop).
  • Time travel: reload an earlier checkpoint, change the state and try a different path, which is excellent for debugging.
  • Auditing: a full history of what the state was at each step.

Store checkpoints in a database, keyed by run id and step number. Keep the state JSON-serializable, so avoid putting open connections or objects with live handles into it.

Parallel branches and merging

Some nodes are independent (search three sources) and can run at the same time. The graph forks, runs the branches and joins at a node that merges their outputs. Decide how conflicting updates combine: append to a list, take the latest, or merge dictionaries. Define this rule once per state key.

Designing a good workflow

  1. Write the steps on paper before coding.
  2. Keep nodes small and single-purpose, so each can be evaluated alone (see evaluating agents).
  3. Put model calls only where judgment is needed; use plain code for routing that rules can do.
  4. Validate state at each boundary (types, required keys).
  5. Add limits: attempts, total steps, cost.
  6. Trace every node (see observability).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the main difference between a workflow and an autonomous agent?

    Workflows are predictable and controlled; agents are flexible but less predictable.
  2. 2. In an agent graph, what does a conditional edge do?

    A function reads the state and returns which node comes next.
  3. 3. Why include an attempt counter in a revise loop?

    Cycles must have an exit even when the check never passes.
  4. 4. What do checkpoints enable?

    Saved state after each node makes runs durable and inspectable.

Summary

  • Use the least autonomy that solves the task: workflows for known shapes, agents for open-ended ones, often a mix.
  • A graph has shared state, nodes that update it, and fixed or conditional edges.
  • Loops are powerful but need attempt and step limits.
  • Checkpoints give resume, human approval, time travel and audit trails.
  • Keep nodes small, state serializable and every transition traceable.

Next: Deploying Agents to Production