08. Why an Agent Needs a State Machine

A single model call may need only success and failure. Once tools are introduced, a task can stop while waiting for the model, validating arguments, awaiting permission, executing a tool, or recording a result.

A state machine defines finite states and legal transitions. It does not improve model reasoning. It lets the runtime determine its current condition, the next legal operation, and the recovery point after interruption.

Minimum states for a tool trace

unknown is essential. After interruption, the runtime may be unable to determine whether an external action finished. That condition is neither confirmed failure nor success.

Conversation history is not runtime state

History can show that the model requested a tool. It may not prove that arguments passed validation, the user approved, the process started, an external service accepted the request, or the result became durable.

Keeping those facts only in memory loses them when the CLI exits. Replaying conversation text may execute the same action twice.

Transitions and events are coupled

Every transition records previous state, next state, reason, and related identifiers. The runtime persists tool.started before execution and tool.completed after execution, then returns the result to the model.

This does not create an atomic transaction with an external API. An atomic transaction commits all operations or none. External services usually do not participate in the local transaction, so side effects still require idempotency keys or status queries.

Three interruption points

The third is the dangerous window. Treating “not recorded” as “not executed” duplicates side effects.

Goal, plan, and state are different

The goal describes the user’s desired outcome. The plan describes intended steps. State identifies the runtime’s executable phase. A model can revise a plan; it cannot declare tool_running to be completed.

The runtime advances state from confirmed events. Model output proposes candidate actions.

Concurrent events need state-version control

Tool completion, user cancellation, and timeout can arrive together. If each handler reads an old state and overwrites it, a later write erases an earlier decision. A state version or compare-and-swap condition allows a transition only when its predecessor version still matches.

Illegal transitions produce anomaly events. tool_started after completed, or denied directly entering recording, stops automatic progression.

Recovery is not a complete rerun

The recovery process reads the last committed state, checks unresolved external actions, and revalidates permission lifetime. It re-executes only steps proven safe. Conversation helps reconstruct semantic intent but does not replace process state, external receipts, or authorization records.

Passing recovery means no completed action was duplicated, no unresolved approval was skipped, and new events continued the original trace with increasing sequence numbers.

Acceptance testing

Terminate the process at every boundary and restore from durable records. Verify legal continuation, reuse of completed read-only results, status queries for unknown side effects, preservation of pending approval, and no re-execution of terminal tasks.

A correct answer proves one successful path. A state machine is validated by interrupted paths.

State answers what may happen now

History describes prior messages. State defines legal next transitions. The same messages can mean waiting for approval, executing, completed but not inserted, or inserted but not followed by another model call.

A checkpoint links arguments, authorization, execution intent, external receipt, and result. “Turn 3” alone is not recoverable state.

Event sourcing preserves transitions; a snapshot preserves current state for fast recovery. A snapshot records its final event sequence so later events are replayed once.

Concurrent completions use optimistic concurrency: a write succeeds only if the state version still matches. A failed writer reloads and merges.

Generated event sequences test combinations beyond the happy path.