Skip to content
AI Engineer Guide.

drill · drills · beginner · concept 14 of 33

Debug: agent loops

0 of 33 complete

Why it matters

Agents loop because the model is optimising against observations, and an observation that never changes gives it no reason to change plan. The cause is usually mechanical: an error message the model cannot act on, a tool that reports success without effect, or a task with no completion criterion. Prompt edits sometimes mask it for one case and leave the mechanism intact, which is why the trajectory has to be read first.

Mental model

A loop is a thermostat with a broken sensor: it keeps heating because the reading never reaches the target. The metaphor breaks because the agent can also misread a correct sensor, so you must check both the observation and the model's interpretation of it.

How it works

Mechanism, step by stepInteractive
  1. 1Pull one failing trajectory and list the tool calls in order with their inputs and returned observations.
  2. 2Mark the first repeated action and check whether the observation differed from the previous one.
  3. 3Classify the loop: repeated identical call, alternating pair, or a plan that never reaches the finish action.
  4. 4Check the tool's error text for actionable information, since a bare failure string invites a retry.
  5. 5Verify that the tool actually changed state when it reported success.
  6. 6Add or tighten the termination condition: step budget, no-progress detector, or an explicit give-up action that returns partial work.

Step 1 of 6

Pull one failing trajectory and list the tool calls in order with their inputs and returned observations.

Step 1/6 · step 1

Figure. The mechanism in this page's own steps. The figure adds sequence, not new claims.

What to notice. A step can be read alone, but the order is the mechanism. The control lets you stop on any one.

Text version

The page's steps: 1. Pull one failing trajectory and list the tool calls in order with their inputs and return… 2. Mark the first repeated action and check whether the observation differed from the previo… 3. Classify the loop: repeated identical call, alternating pair, or a plan that never reache… 4. Check the tool's error text for actionable information, since a bare failure string invit… 5. Verify that the tool actually changed state when it reported success. 6. Add or tighten the termination condition: step budget, no-progress detector, or an explic…

  1. Pull one failing trajectory and list the tool calls in order with their inputs and returned observations.
  2. Mark the first repeated action and check whether the observation differed from the previous one.
  3. Classify the loop: repeated identical call, alternating pair, or a plan that never reaches the finish action.
  4. Check the tool's error text for actionable information, since a bare failure string invites a retry.
  5. Verify that the tool actually changed state when it reported success.
  6. Add or tighten the termination condition: step budget, no-progress detector, or an explicit give-up action that returns partial work.

Trade-offs

ChoiceGood forCostFails when
Hard step capBounded cost and latencyComplex tasks end incompleteTasks legitimately need many steps
No-progress detectorStops repetition earlyFalse positives on legitimate pollingThe tool is asynchronous by design
Retry with error feedbackRecovers from transient failuresCan amplify a persistent errorThe error is not fixable by the model
Ask the model to reflectSometimes breaks the patternExtra tokens and unreliableThe root cause is a broken tool
Trade-off mapInteractive

Good for

Bounded cost and latency

Cost

Complex tasks end incomplete

Fails when

Tasks legitimately need many steps

  1. Tasks legitimately need many steps
  2. The tool is asynchronous by design
  3. The error is not fixable by the model
  4. The root cause is a broken tool

Figure. Each choice with what it buys, what it costs, and the case where it loses.

What to notice. The fourth column is the decision: if the losing case describes your situation, the choice is wrong.

Text version

Four trade-offs: Hard step cap is good for Bounded cost and latency, costs Complex tasks end incomplete, and fails when Tasks legitimately need many steps. No-progress detector is good for Stops repetition early, costs False positives on legitimate polling, and fails when The tool is asynchronous by design. Retry with error feedback is good for Recovers from transient failures, costs Can amplify a persistent error, and fails when The error is not fixable by the model. Ask the model to reflect is good for Sometimes breaks the pattern, costs Extra tokens and unreliable, and fails when The root cause is a broken tool

Failure modes

  • Success without effect. A write tool returns ok but the record is unchanged, so the agent repeats the call. Debug: compare the tool's reported result with the stored state after one call.
  • Unreadable error. The tool returns a stack trace the model cannot map to an action. Debug: read the observation text in the trajectory and check whether it names the bad argument.
  • Alternating pair. Two tools undo each other and the step count climbs. Debug: find the repeating pair and check their effects on the same record.

In production

Log step count, tool name and observation hash per turn, and alert on runs that hit the step cap. Cap spend per request so a loop cannot become an incident.

Common misconceptions

People think: A looping agent needs a better prompt.

Actually: The prompt is one cause; unchanged observations and missing termination rules are more common and cheaper to fix.

People think: More steps mean a harder task.

Actually: Repeated identical steps mean no progress, which is a mechanism failure rather than task difficulty.

Interview angle

Describe how you would read a trajectory, classify the loop and fix the mechanism, then how you would bound it in production. Weak answers suggest prompt tweaks without looking at the observations.

Sources