Write down an agent state machine before its prompt
Represent an agent investigation with explicit states, transition guards, and terminal outcomes so its execution can be inspected and resumed safely.

For an engineer implementing an agent, a state machine makes the execution contract visible before prompt wording obscures it. It records what the system is doing, which observations allow it to proceed, and how it stops. The model can choose among permitted next actions while the application enforces the transition rules.
Consider a hypothetical read-only investigation of a failing repository test. The agent may inspect files and run a bounded test command. It may not edit code, install packages, or publish changes. Its final output is a diagnosis supported by file references and observed command results. Basic familiarity with Python functions, processes and the difference between proposing and executing an action is enough for the exercise.
Choose states with observable meanings
A useful first model has inspect, test, assess, and terminal states for diagnosed, needs_input, and budget_exhausted. Each state should mean something an operator can determine from stored data. “Thinking deeply” is not useful because it does not identify an external condition or an executable action.
In inspect, the agent selects an allowed file or search query. A successful read adds evidence and moves to assess. In test, the application starts a permitted command and stores its process handle. Assessment waits for an actual terminal result; a tool timeout while observing a live process is not proof that the process failed.
inspect -> assess -> inspect
-> test -> assess
-> diagnosed
-> needs_input
-> budget_exhausted
This sketch describes possible transitions, not a mandate to execute them all. A missing repository path may lead directly to needs_input. A clear test failure and matching source condition may justify diagnosed without repeatedly rerunning the same command.
The diagram places assessment between observations and decisions. The application should persist the observation before accepting a transition based on it. Otherwise, a restart can leave the system claiming to know a test result that was never stored.
Put guards on transitions
A transition guard is a condition the application checks. Before entering test, verify that the command is permitted, the working directory is correct, and enough time remains to observe or cancel it responsibly. Before entering diagnosed, require the evidence fields that the task contract says a diagnosis needs.
For this example, a diagnosis might require a reproduction identifier, a source location, a stated causal explanation, and a remaining-uncertainty field. These fields do not automatically make the explanation correct. They make missing evidence detectable and give a reviewer a useful artifact to inspect.
The ReAct paper studies interleaving reasoning and actions. A production state machine can adopt an observation-driven loop while making the allowed actions and stopping rules explicit. The paper’s benchmark results do not establish that this particular repository investigator will succeed; it needs its own task evaluation.
Store execution state separately from conversation
A conversation transcript is useful context, but it should not be the only record of a running command. Store a stable task identifier, current state, attempt number, process or job handle, and references to completed results. A resumed agent can then poll the existing operation instead of starting another one because the previous text was truncated.
The function calling guide, retrieved on September 20, 2026, separates model-requested calls from application execution. Preserve that separation in the state machine. A proposed test call becomes an executed operation only after the application validates and launches it.
For read-only work, repetition may mainly waste resources. A later extension that creates a ticket or modifies a file has stronger requirements. Persist intent and a stable operation identifier before dispatch, then record the actual result. Recovery should consult that operation record before deciding whether repeating the action is safe.
Replay a process that has not finished
A small reducer makes the distinction between launching, waiting and observing test completion testable. This Python exercise consumes trusted application events; it does not run a model or shell. The surrounding executor validates nonempty artifact and operation IDs, authenticates their origin and stores actual command output. A test_done event means a terminal process result was recorded, including its exit code, not that the test passed.
from dataclasses import dataclass, replace
@dataclass(frozen=True)
class State:
phase: str = "inspect"
job: str | None = None
result: str | None = None
sources: tuple = ()
def advance(s, kind, *, ref=None, job=None):
if s.phase in {"diagnosed", "needs_input", "budget_exhausted"}:
raise ValueError("terminal state")
if kind == "read_done" and s.phase in {"inspect", "assess"} and ref:
return replace(s, phase="assess", sources=s.sources + (ref,))
if kind == "request_test" and s.phase == "assess":
return replace(s, phase="launching", result=None)
if kind == "test_started" and s.phase == "launching" and job:
return replace(s, phase="waiting", job=job)
if s.phase == "waiting" and job == s.job:
if kind == "still_running":
return s
if kind == "test_done" and ref:
return replace(s, phase="assess", job=None, result=ref)
if kind == "diagnose" and s.phase == "assess" and s.sources and s.result:
return replace(s, phase="diagnosed")
if kind in {"needs_input", "budget_exhausted"}:
return replace(s, phase=kind)
raise ValueError("invalid transition or missing evidence")
s = advance(State(), "read_done", ref="src/date.ts@rev7:18")
s = advance(s, "request_test")
s = advance(s, "test_started", job="test-17")
s = advance(s, "still_running", job="test-17")
print(s.phase, s.job, s.result)
s = advance(s, "test_done", job="test-17", ref="results/test-17.json")
s = advance(s, "diagnose")
print(s.phase, s.job, s.result)
The first line is waiting test-17 None; the second is diagnosed None results/test-17.json. Polling did not supply a terminal result or spend a second test launch. A reply for test-18 is rejected. Attempting request_test while waiting is also rejected, and the immutable previous state remains available after either error. Once diagnosed, further events fail rather than silently reopening execution.
The diagnosed guard only establishes the presence of referenced source and result evidence. It does not prove a causal explanation or even inspect whether the result is relevant. A separate assessment must read those artifacts and produce the required explanation and uncertainty. The example intentionally makes this limit visible: a stale or unrelated result reference can satisfy the shape check but must fail substantive review.
Persist the accepted request_test transition before dispatch, then record the returned handle in test_started. A crash between these events leaves launching, which this tiny reducer cannot automatically reconcile. A real executor needs a durable operation ID and a way to look up whether launch occurred; restarting blindly could duplicate a test. Similarly, accepting a terminal budget event while a job is live preserves its handle, but does not cancel that process. Cleanup or a continued-observation handoff remains an executor responsibility.
The Thinking in LangGraph guide, retrieved September 21, 2026, recommends storing raw state and formatting prompts when needed. That advice supports keeping artifact references and operation identity separate from fluent conversation text. No LangGraph API is required by this reducer, and it does not reproduce the framework’s checkpoint or interrupt machinery. Those facilities need their own version-specific recovery tests if adopted.
Make budgets part of the state
Track remaining tool calls, elapsed time, and any cost limit the application enforces. Deduct usage based on actual execution records rather than the model’s estimate of how much work it has done. Reserve enough budget for a useful terminal explanation.
A simple policy might permit at most eight file inspections and two test runs for the teaching task. Those are example limits, not generally optimal values. If the second test is still running when the investigation deadline approaches, the application needs a documented handling rule: continue observing within a grace period, cancel if supported, or return a durable handle for later observation.
Do not let budget_exhausted masquerade as a diagnosis. The final message should list verified findings and the next unresolved check. A user can then decide whether to allocate more work. The state label should remain truthful even when the language model is inclined to produce a polished conclusion.
Exercise the awkward transitions
Test a file that disappears between selection and read, a command that returns a nonzero exit code, a command whose observation times out while it remains live, and a malformed tool request. Each case should produce a defined transition and preserve enough evidence to explain it.
Add a loop test where the agent repeatedly proposes the same unproductive inspection. The application can detect repeated action signatures and require a new hypothesis or stop after a stated limit. This protects the budget without pretending that repetition alone proves the task impossible.
Finally, inspect a completed trace from start to finish. Every transition should point to the observation or policy that justified it. If an operator cannot explain why the system moved from test to diagnosed, the missing information belongs in the execution record. A state machine is useful when it makes that gap visible before the agent’s final prose hides it.