Stuck Detection

Agents can get stuck by repeating the same tool call or hitting one failure after another. Stuck detection recognizes those patterns and applies the configured recovery strategy.

Configuration

json
{
  "on_stuck": {
    "iterations": 3,
    "action": "escalate",
    "hint": "Try a different approach or use __complete__ with your best answer."
  }
}
Property Type Required Description
iterations number No Number of repeated iterations before triggering (default: 3)
action string No Recovery strategy: "fail", "escalate", or "retry_with_hint" (default: "fail")
hint string No Guidance text injected into the prompt (only used with "retry_with_hint")

How Detection Works

The engine monitors the agent's action history across iterations. It detects stuck patterns when:

  • The agent calls the same action with the same parameters for N consecutive iterations
  • The last N trace entries are errors or unsuccessful tool calls

When any pattern is detected for the configured number of iterations, the recovery strategy fires.

Recovery Strategies

"fail": terminate

The agent loop ends immediately with a failure status. Use when you'd rather fail fast than risk incorrect results.

json
{ "on_stuck": { "iterations": 3, "action": "fail" } }

The agent ends with a stuck status and a message that it could not make progress.

"escalate": pause for a person

The agent pauses and creates a review request, similar to __pause_for_human__. The request includes recent actions and enough context for a person to respond.

json
{ "on_stuck": { "iterations": 3, "action": "escalate" } }

The human can provide guidance via POST /agents/:id/resume, and the agent continues with the human's input as additional context. This is the recommended strategy for production agents in critical workflows.

"retry_with_hint": redirect

The engine injects a hint into the agent's next prompt, nudging it toward a different approach. The agent gets one more chance to make progress.

json
{
  "on_stuck": {
    "iterations": 3,
    "action": "retry_with_hint",
    "hint": "You seem to be repeating yourself. Try using __complete__ to provide your best answer with the information you have, or try a different tool."
  }
}

If the agent gets stuck again after the hint, it fails. The hint is a one-shot redirect, not an infinite retry.

Setting Thresholds

iterations: 2 triggers quickly but can catch an agent that legitimately retries a tool, such as polling for a delayed result.

iterations: 3 is the default and allows one repeated call before the recovery policy acts.

iterations: 5 gives tools more room when repeated calls can return different results.

Example: Stuck Detection in Practice

An agent investigating an unmatched invoice:

text
Iteration 1:
  Thought: "Let me search for related payments."
  Action: search_payments { "invoice_id": "INV-099" }
  Observation: { "results": [] }

Iteration 2:
  Thought: "No results. Let me try searching again with a broader query."
  Action: search_payments { "invoice_id": "INV-099" }   <- same action, same params
  Observation: { "results": [] }

Iteration 3:
  Thought: "Still nothing. Let me search once more."
  Action: search_payments { "invoice_id": "INV-099" }   <- stuck detected

With "action": "escalate", the agent pauses here and a human reviews the trace. The human might respond: "This invoice is from a new vendor not yet in the payment system. Mark as pending vendor setup."

With "action": "retry_with_hint" and hint "No payments exist for this invoice. Consider whether it might be from a new vendor or a different system.", the agent gets one more iteration with this additional context.

Best Practices

  • Configure on_stuck for production agents. Use "fail" when a terminal result is safer, or "escalate" when a person can supply useful direction.

  • Pair stuck detection with max_iterations as a hard ceiling. Stuck detection catches loops; max_iterations catches everything else.

  • Write hints that suggest alternatives, not just "try again." Good: "If the search returns no results, use complete to report that no match was found." Bad: "Try harder."

  • Monitor stuck rates via platform metrics. High stuck rates indicate the objective is unclear, tools are insufficient, or the model needs more guidance.

ā†’ Next: Reasoning Traces