Agent Execution State Machine Prompt Template

This prompt is for AI platform engineers and workflow builders who need to define a strict lifecycle for an agent. Use it when an agent must move through a known set of states (idle, running, waiting_for_tool, completed, failed) and you need the model to enforce valid transitions, execute entry and exit actions, and reject invalid state changes. The primary job-to-be-done is generating a machine-readable state machine definition that your orchestration layer can parse and enforce deterministically, removing ambiguity from the agent's execution contract.

The ideal user is implementing a production agent harness where the execution graph is managed by an external runtime (e.g., Temporal, Prefect, a custom orchestrator). The required context includes the list of valid states, the events or triggers that cause transitions, and the side effects (tool calls, logging, human approvals) that must occur on entry or exit. This prompt is not for ad-hoc agent loops or freeform reasoning where the model decides its own execution flow. It is for systems where the execution contract must be deterministic and auditable, such as financial transaction agents, healthcare data processors, or any workflow requiring SOC 2 or similar compliance evidence.

Do not use this prompt when the agent's path is exploratory, when states are discovered at runtime, or when you are prototyping a single-agent loop. In those cases, a planning or task decomposition prompt is more appropriate. Before using the generated state machine, validate it against your orchestration engine's schema, test every transition with a dry-run harness, and ensure that unreachable states and missing error transitions are caught by your eval suite. The output is a specification, not a runtime—your application code must enforce it.

This template defines the core contract for an agent that must operate within a finite set of states. It is designed to be pasted directly into your system instructions or developer message. The prompt forces the model to track its current state, validate every transition against a predefined set of rules, and execute entry or exit actions. This is critical for workflows where an agent skipping a step or entering an invalid state would corrupt a multi-step process, such as a loan application review, a deployment pipeline, or a customer onboarding flow.

Below is the copy-ready template. Replace every square-bracket placeholder with the specific states, events, and constraints of your agent's lifecycle. The [STATE_DEFINITIONS] block is the heart of the machine; define each state with its valid transitions and associated actions. The [TRANSITION_GUARDS] block adds conditional logic that must be true before a transition is allowed. The [ERROR_HANDLING] block tells the agent what to do when an invalid transition is requested, preventing silent failures.

textCopy
You are an Agent Execution State Machine. Your behavior is strictly governed by a finite set of states and transitions. You must never enter a state not defined below.

## State Definitions
Your current state is tracked in a `current_state` variable. You must output your state after every action.

[STATE_DEFINITIONS]
# Example:
# IDLE: The initial state. Valid transitions: [RECEIVED_REQUEST].
#   Entry Action: Log "System ready."
# ANALYZING: The agent is processing the request. Valid transitions: [ANALYSIS_COMPLETE, ERROR_ENCOUNTERED].
#   Entry Action: Run the `decompose_task` tool.
#   Exit Action: Save the analysis result to `task_context`.
# COMPLETED: Terminal state. No valid transitions.
#   Entry Action: Run the `finalize_output` tool.

## Transition Guards
A transition is only valid if the guard condition evaluates to TRUE.

[TRANSITION_GUARDS]
# Example:
# IDLE -> ANALYZING: Guard `request_is_valid` must be TRUE.
# ANALYZING -> COMPLETED: Guard `analysis_confidence` must be greater than 0.9.

## Error Handling
If an invalid transition is requested, you must not execute it. Instead, transition to the `ERROR` state and report the violation.

[ERROR_HANDLING]
# Example:
# On Invalid Transition: Set state to `ERROR`, log the attempted transition from `current_state` with the invalid event, and output an `InvalidTransitionError` payload.

## Input
You will receive a series of events. For each event, determine the next state based on the current state and the event, validate the transition guard, execute entry/exit actions, and output the new state.

[INPUT]

After pasting the template, the most critical adaptation step is defining the [TRANSITION_GUARDS]. A state machine without guards is just a flowchart, and an LLM can easily hallucinate a transition if the guard isn't explicit. For high-risk workflows, the guard should reference a verifiable fact, such as a tool output or a field in the task_context. The [ERROR_HANDLING] block is your safety net; always define a default escalation path, such as transitioning to a HUMAN_REVIEW state, to prevent the agent from getting stuck in an error loop. Before deploying, run a suite of evals that deliberately request invalid transitions to confirm the agent refuses them and follows the error protocol.

The state machine prompt template is not a standalone artifact—it is a configuration generator that must be consumed by an execution harness. The harness reads the generated state machine definition (states, transitions, guards, entry/exit actions) and enforces it at runtime. This means the prompt output must be machine-parseable JSON conforming to a strict schema, and the harness must validate that schema before using the definition to drive agent behavior. Treat the prompt as a compile step: it produces the state machine spec, and the harness is the runtime that executes it.

Wire the prompt into your workflow with these concrete checks. Schema validation: Parse the model output against a JSON Schema that requires states (array of objects with name, type, entry_actions, exit_actions), transitions (array of objects with from, to, guard, priority), and initial_state. Reject any output missing required fields or containing transitions that reference undefined states. Unreachable state detection: After parsing, run a graph traversal from initial_state and flag any state with zero inbound transitions as a warning—these may indicate dead code in the agent lifecycle. Missing transition coverage: For each state, verify that every possible exit condition has a defined transition. If a state has an error exit in its documentation but no corresponding transition, surface this as a coverage gap before deployment. Retry logic: If the model produces invalid JSON or fails schema validation, retry up to 2 times with the validation errors injected into the prompt as feedback. After 3 total attempts, escalate to a human reviewer with the raw output and validation report. Logging: Record the prompt version, model, raw output, validation result, and any warnings in an audit log. This is critical for debugging state machine drift across prompt iterations.

Model choice matters here. Use a model with strong JSON mode and structured output support (GPT-4o, Claude 3.5 Sonnet, or Gemini with response_schema). Avoid models that struggle with complex nested schemas—a malformed state machine definition can cause the agent harness to enter undefined states at runtime. For high-risk workflows where incorrect state transitions could trigger irreversible side effects (e.g., sending customer communications, modifying production data), add a human approval gate after validation but before the harness loads the state machine. The reviewer checks for semantic correctness that automated validators miss: guard conditions that are too permissive, missing timeout transitions, or entry actions that violate business rules. Finally, version-lock the generated state machine definition alongside the prompt template. When you update the prompt, run a regression suite of known agent workflows through the new state machine in a dry-run harness before promoting to production.