Stuck Agent Detection and Alert Prompt

This prompt is for runtime monitors and agent operators who need to detect when an autonomous agent has stopped making forward progress. The job-to-be-done is classifying an agent's execution trace as stuck or healthy, then producing a structured alert with evidence and a recommended recovery action. The ideal user is an engineering team building agent harnesses that run multi-step workflows—where silent stalls waste tokens, violate latency budgets, and corrupt downstream state. You should use this prompt when you have access to a sequence of recent agent actions (tool calls, reasoning steps, or state transitions) and need a programmatic signal to trigger a retry, escalation, or replanning event.

This prompt is not a replacement for simple timeout-based detection. If your agent runs a single tool call with a known SLA, a wall-clock timeout is cheaper and more reliable. Use this prompt when stalls are semantic rather than temporal—for example, when an agent repeatedly calls the same tool with slightly different arguments, loops through identical reasoning patterns, or generates valid-looking outputs that don't advance the task state. The prompt requires a structured trace input containing timestamps, action types, and step descriptions. It works best when paired with a sliding window of recent actions (typically 5–20 steps) rather than a full session history, which can dilute the stall signal.

Before wiring this into production, define what 'stuck' means for your specific agent topology. A coding agent stuck in a test-fix loop requires different thresholds than a research agent cycling through search queries. Calibrate the repetition count, time budget, and progress indicators against your normal execution patterns. Always pair this prompt with a circuit breaker: if the detection prompt itself fails or returns ambiguous classifications, your harness should default to a safe action (escalate or pause) rather than silently continuing. The next section provides the copy-ready template you can adapt to your trace format and stall definitions.

This template analyzes agent execution traces to identify stall patterns—repeated tool calls without progress, looped reasoning, or steps exceeding time budgets—and produces a structured stuck-state classification with evidence and a recommended recovery action. The prompt is designed to be wired into an agent runtime monitor that fires when a configurable condition is met, such as N consecutive tool calls with no state change or a step exceeding its time budget by a threshold.

textCopy
You are an agent execution monitor. Your job is to analyze the provided execution trace and determine whether the agent is stuck in a non-productive loop, stalled without progress, or proceeding normally.

## INPUT

[EXECUTION_TRACE]

## TASK

1. Examine the sequence of actions, tool calls, reasoning steps, and state changes in the trace.
2. Identify any of the following stall patterns:
   - **Repetition loop**: The same tool call or reasoning pattern repeats [REPETITION_THRESHOLD] or more times with no change in inputs, outputs, or state.
   - **No-progress stall**: The agent has taken [STALL_THRESHOLD] or more actions without advancing toward the stated goal, producing new information, or changing state.
   - **Time-budget exceedance**: A single step or the overall trace has exceeded its configured time budget of [TIME_BUDGET] without completion.
   - **Circular reasoning**: The agent revisits the same decision point multiple times without resolving it or gathering new evidence.
3. Classify the trace as one of: `STUCK`, `STALLED`, or `PROGRESSING`.
4. If `STUCK` or `STALLED`, identify the specific pattern, cite evidence from the trace, and recommend a recovery action from: `ABORT`, `REPLAN`, `ESCALATE_TO_HUMAN`, `SKIP_STEP`, or `RETRY_WITH_CONSTRAINT`.

## OUTPUT SCHEMA

Return a valid JSON object with this exact structure:

{
  "classification": "STUCK" | "STALLED" | "PROGRESSING",
  "pattern_detected": "repetition_loop" | "no_progress_stall" | "time_budget_exceeded" | "circular_reasoning" | null,
  "evidence": [
    {
      "trace_index": <integer referencing the action or step in the trace>,
      "observation": "<specific description of what indicates the stall>"
    }
  ],
  "recovery_action": "ABORT" | "REPLAN" | "ESCALATE_TO_HUMAN" | "SKIP_STEP" | "RETRY_WITH_CONSTRAINT" | null,
  "recovery_rationale": "<one-sentence explanation of why this recovery action is appropriate>",
  "confidence": <float between 0.0 and 1.0>
}

## CONSTRAINTS

- Do not classify as STUCK or STALLED unless you can cite specific evidence from the trace.
- A single repeated action is not a loop unless it meets the repetition threshold.
- If the agent is making slow but observable progress, classify as PROGRESSING.
- If you are uncertain, set confidence below 0.7 and prefer ESCALATE_TO_HUMAN as the recovery action.
- Do not invent trace events. Only reference actions present in [EXECUTION_TRACE].

Adaptation guidance: Replace [EXECUTION_TRACE] with the structured log of agent actions, tool calls, and reasoning steps from your runtime. Set [REPETITION_THRESHOLD], [STALL_THRESHOLD], and [TIME_BUDGET] to values appropriate for your agent's expected step latency and tolerance for retries. For high-risk domains such as healthcare or finance, set lower thresholds and always require human review when classification is STUCK with confidence below 0.9. The output schema is designed for direct ingestion by an orchestration layer that can trigger the recommended recovery action programmatically.

Validation and testing: Before deploying, run this prompt against a golden dataset of known traces: normal progress, genuine loops, slow-but-valid progress, and edge cases like a single repeated tool call that is actually productive. Verify that the classification matches expected labels and that evidence citations reference real trace indices. Add an eval check that rejects outputs where classification is STUCK but evidence is an empty array, or where recovery_action is null for non-PROGRESSING classifications. For production, log every classification decision with the trace ID, classification, confidence, and recovery action taken so operators can audit false positives and tune thresholds over time.

This prompt is designed to run as a sidecar evaluator inside an agent runtime, not as a user-facing chat interaction. The primary integration point is the agent's execution loop: after every N tool calls or at a configurable heartbeat interval, the runtime should assemble the recent trace window and invoke this prompt. The output is a structured classification that your harness must parse and act on—either logging a warning, triggering a replanning step, or escalating to a human operator. Do not treat this as a passive logging prompt; its value comes from the automated control flow decisions it enables.

Wiring pattern: Wrap the prompt call in a lightweight async function that accepts a trace window and returns a typed result. Validate the output against a strict schema before acting on it. If the model returns stuck_state: true, immediately increment a stall counter. On the first detection, inject a replanning prompt into the agent's context. On the second consecutive detection for the same step, pause the agent and route to a human review queue with the full trace and the model's recovery_action recommendation. If the output fails schema validation, retry once with a stricter system instruction; if it fails again, treat it as an unknown state and escalate conservatively. Log every invocation with the trace window hash, model response, validation result, and action taken for post-incident analysis.

Model choice and latency: This prompt benefits from models with strong instruction-following and structured output capabilities. Use a fast model (e.g., GPT-4o-mini, Claude Haiku) for the detection call to keep overhead low—this is a monitoring path, not a reasoning path. Set a tight timeout (under 5 seconds) and configure your harness to treat a timeout as a degraded signal: log it, do not block the main agent loop, and fall back to a simple heuristic check (e.g., identical consecutive tool calls > 3 times). For high-stakes production systems, pair this prompt with a deterministic pre-filter that catches obvious loops (exact duplicate tool calls, repeated reasoning strings) before invoking the LLM, reducing both cost and latency.

Testing and eval: Before deploying, build a regression suite of trace windows with known labels: normal progress, genuine loops, slow-but-valid progress, and edge cases like tool calls that look repetitive but produce different side effects. Measure precision and recall against your operational tolerance—false positives that interrupt valid workflows are more damaging than missed detections in most systems. Include eval checks for output schema compliance, evidence field specificity (it must cite concrete step IDs or timestamps, not vague summaries), and recovery_action feasibility (it must reference actual available tools or escalation paths). Run these evals on every prompt or model version change as a CI gate.