Agent Loop Detection and State Reset Prompt

This prompt is for agent runtime operators and developers who need to detect when an autonomous agent is stuck in a non-productive loop—repeating the same tool calls, revisiting the same failed states, or cycling through the same reasoning without making progress toward its goal. The job-to-be-done is automated loop detection with an actionable diagnosis, not just a timeout or a step-count limit. The ideal user is an engineering lead or AI builder integrating this detection into an agent harness that already has access to structured action logs, state snapshots, and tool-call histories. You need at least a sequence of recent agent actions with their outcomes and the current task objective before this prompt can produce a useful diagnosis.

Use this prompt when your agent runtime observes repeated action patterns, identical tool-call arguments, or a cycle of state changes that return to a previously visited state without advancing the task. It is designed for production agent loops where the cost of continued execution exceeds the cost of detection and intervention. The prompt produces a structured loop diagnosis with evidence of repetition, identifies which state fields are affected, and proposes a concrete reset or strategy change. It includes explicit false-positive checks so you are not resetting state when the agent is making slow but real progress through a large or repetitive but necessary task sequence.

Do not use this prompt as a substitute for proper timeout mechanisms, step-count limits, or basic cycle detection in your application code. It is not a real-time safety interlock for high-frequency control loops, and it should not be the only guardrail preventing infinite token spend. This prompt is most effective when wired into a monitoring layer that triggers it after a configurable threshold—such as N repeated tool calls with identical arguments or M state revisits within a time window. For regulated or high-risk domains, always route the loop diagnosis and proposed reset to a human reviewer before executing state mutations, especially when the reset involves discarding partial work or changing the agent's goal parameters. Pair this prompt with the State Integrity Validation Prompt Template to verify that the reset state is internally consistent before resuming execution.

This prompt template is designed to be injected into an agent's execution loop when a loop detection monitor fires. It receives the agent's recent action history, current internal state, and the original goal. The model's job is to diagnose whether a genuine non-productive loop exists, provide specific evidence, identify which state fields are stale or corrupted, and recommend a concrete reset or strategy change. The template includes explicit false-positive checks to prevent unnecessary resets when the agent is making legitimate progress through similar-looking steps.

codeCopy
You are an agent loop detector and state reset advisor. Your task is to analyze the agent's recent execution trace and determine whether it is stuck in a non-productive loop, or whether the repeated actions represent legitimate progress.

## INPUTS

[AGENT_GOAL]
[RECENT_ACTION_HISTORY]
[CURRENT_AGENT_STATE]
[LOOP_DETECTION_THRESHOLD]
[TOOL_CAPABILITIES]

## INSTRUCTIONS

1. **Analyze the action history** for repeated patterns. Look for:
   - Identical tool calls with identical arguments repeated [LOOP_DETECTION_THRESHOLD] or more times.
   - Cyclic sequences where the agent returns to a previous state without making progress toward [AGENT_GOAL].
   - Tool calls that produce errors or empty results but are retried without parameter changes.

2. **Perform false-positive checks** before declaring a loop:
   - Is each repeated action producing a different, valid output? If yes, this may be legitimate iteration.
   - Is the agent processing a list or paginated results where similar calls are expected? If yes, check whether the offset or cursor is advancing.
   - Is the agent exploring a search space with different parameters that happen to share a call structure? If yes, verify parameter variation.
   - Is there evidence of forward progress in [CURRENT_AGENT_STATE] that the action history alone might miss?

3. **If a genuine loop is detected**, produce a diagnosis with:
   - **Loop type**: exact-repeat | cyclic | error-retry | state-oscillation
   - **Evidence**: specific action indices, timestamps, or state comparisons that prove no progress.
   - **Affected state fields**: which parts of [CURRENT_AGENT_STATE] are stale, corrupted, or driving the loop.
   - **Root cause hypothesis**: why the agent is stuck (e.g., stale state field, missing tool, incorrect assumption, goal ambiguity).

4. **Propose a reset or strategy change**:
   - **State reset fields**: specific fields to clear, revert, or mark as uncertain.
   - **Strategy change**: alternative approach, different tool, or decomposition change.
   - **Escalation trigger**: if the loop has persisted beyond recovery, recommend human escalation with a summary.

5. **If no genuine loop is detected**, explain why the apparent repetition is legitimate and what progress indicators confirm this.

## OUTPUT SCHEMA

Return a JSON object with this exact structure:
{
  "loop_detected": boolean,
  "false_positive_check": {
    "legitimate_iteration": boolean,
    "pagination_or_cursor_advancing": boolean,
    "parameter_variation_present": boolean,
    "state_progress_evidence": string
  },
  "diagnosis": {
    "loop_type": "exact-repeat" | "cyclic" | "error-retry" | "state-oscillation" | null,
    "evidence": [string],
    "affected_state_fields": [string],
    "root_cause_hypothesis": string
  },
  "reset_recommendation": {
    "fields_to_reset": [string],
    "fields_to_mark_uncertain": [string],
    "strategy_change": string,
    "escalation_recommended": boolean,
    "escalation_summary": string
  },
  "confidence": 0.0-1.0,
  "reasoning_summary": string
}

## CONSTRAINTS

- Do not declare a loop without citing specific, timestamped evidence from [RECENT_ACTION_HISTORY].
- If confidence is below 0.7, recommend observation over reset.
- Never recommend clearing state fields that contain user-provided information or irreversible action records.
- If [RISK_LEVEL] is "high", always set escalation_recommended to true for any detected loop.

Adaptation guidance: Replace the square-bracket placeholders with your agent runtime's actual data structures. [AGENT_GOAL] should be the original objective string. [RECENT_ACTION_HISTORY] should be a structured log of the last N actions with timestamps, tool names, arguments, and results. [CURRENT_AGENT_STATE] should be the full state object your agent maintains. [LOOP_DETECTION_THRESHOLD] is an integer (typically 3-5) that defines how many repeats trigger analysis. [TOOL_CAPABILITIES] should list available tools so the model can suggest alternatives. [RISK_LEVEL] should be "low", "medium", or "high" based on the cost or irreversibility of the agent's actions. Wire this prompt into your agent's monitor callback so it fires before the next action is dispatched, not after additional wasted calls. Validate the output JSON against the schema before applying any state resets, and log every loop diagnosis for post-mortem analysis.

The loop detection prompt is not a standalone diagnostic; it is a guardrail that sits inside the agent's execution loop. After every N actions—or when a configurable staleness threshold is exceeded—the agent runtime should call this prompt with the recent action log, current state summary, and the original goal. The prompt returns a loop diagnosis, but the harness is responsible for deciding whether to trust it, act on it, or escalate. Treat the prompt output as a recommendation, not a command. In high-risk or irreversible workflows, require human approval before executing any state reset or strategy change proposed by the model.

Wire the prompt into the agent runtime as a synchronous check with a timeout. Pass the last [ACTION_COUNT] actions (default 10–20), the [CURRENT_STATE] object, and the [ORIGINAL_GOAL]. The model should return a structured JSON object with loop_detected (boolean), confidence (0–1), evidence (array of repeating action patterns with timestamps), affected_state_fields (array of state keys that appear stale or corrupted), and recommended_actions (array of reset, skip, replan, or escalate directives). Validate the output against this schema before acting on it. If confidence is below 0.7, log the diagnosis but do not trigger a reset automatically. If the output fails schema validation, retry once with a stricter prompt that includes the validation error. After two failures, escalate to a human operator with the raw action log and the failed outputs.

Implement a false-positive circuit breaker. Track how many times the loop detector fires within a session. If it fires more than [MAX_DETECTIONS] times (start with 3) without a human confirming a real loop, suppress automatic resets and escalate. This prevents the agent from thrashing between state resets when the underlying problem is a poorly scoped goal or an unavailable tool, not a true loop. Log every detection event with the full prompt input, model output, validation result, and the action taken (ignored, reset, escalated). These logs are essential for tuning the detection threshold and for postmortem analysis when an agent silently fails in production.

Model choice matters here. Use a model with strong instruction-following and structured output support for the detection prompt—GPT-4o, Claude 3.5 Sonnet, or equivalent. Avoid smaller or older models that may hallucinate loop patterns in random action sequences. If latency is critical, consider running the loop detector on a separate, cheaper model (like GPT-4o-mini or Claude Haiku) with a higher confidence threshold for action, and only escalate to a larger model when the small model flags a potential loop. Always include the [FALSE_POSITIVE_CHECKS] section in the prompt template, which asks the model to explicitly list reasons why the observed pattern might not be a loop (e.g., legitimate retries, progressive refinement, or tool unavailability). This reduces over-triggering.

Before shipping, build a small eval set of 20–30 action sequences: 10 with known loops (repeated tool calls with identical arguments, cycling through the same 3 actions, revisiting completed subtasks), 10 with legitimate repetition (retrying after a transient error, iterating through paginated results, re-checking a condition that changed), and 5–10 edge cases (empty action logs, single-action sessions, rapid context switches). Measure precision and recall on this set. Tune the [ACTION_COUNT] window and the confidence threshold until false positives are acceptable for your risk tolerance. In regulated domains, keep a human in the loop for all state resets until the detector has demonstrated >95% precision over 1,000 production decisions.