Agent loops are state machines

Every agent framework demo shows the same thing: a while-loop that calls a model, maybe calls a tool, and hopefully stops. It works right up until it doesn't — and when it doesn't, you have no idea which turn went wrong or why.

Name your states

The fix that worked for me was embarrassingly old-fashioned: draw the workflow as an explicit state machine. Planning, researching, drafting, reviewing — each a named node with typed inputs and outputs, each with a defined set of transitions.

graph.add_node("plan", plan_step)
graph.add_node("research", research_step)
graph.add_node("review", review_step)

graph.add_conditional_edges(
    "review",
    lambda s: "done" if s.approved else "plan",
)

• +Every transition is loggable — the trace reads like a story, not a scroll of JSON.
• +Stop conditions become edges, not prayers.
• +Budgets attach to states: the research node gets N tool calls, full stop.

An agent that can't be stopped isn't autonomous — it's unsupervised.

None of this makes the model smarter. It makes the system legible, which turns out to matter more.