AI agent stuck in a loop: how to find and stop it

Agents loop because nothing tells them they are done or that they are repeating themselves. Interrupt it, read the last few steps to see what repeats, then add limits: a maximum number of turns, a spending cap, a hop cap between agents, and a clear definition of done. A readable log makes the repeat obvious.

The usual causes

Is it looping, waiting or just slow?

Look at what it did in the last few steps. The same tool call with the same arguments three times is a loop. A long pause with no new output after a tool call is a hang, often a stalled tool, network call or permission prompt hidden behind the screen. Steady different steps that take long is slow work, not a loop.

In an interactive tool, interrupt first (in Claude Code, press Esc), then ask the agent what it has tried and why it is repeating. For a script or background run, stop the process. Do not just tell it to try again: that usually gives the same result and burns more tokens.

Set hard limits before you start

Anthropic's guide to building agents recommends stopping conditions such as a maximum number of iterations, so a runaway cannot continue forever. Most tools have a setting for it:

Fix the cause, not only the symptom

Write a definition of done into the task: the exact check that means finished, such as 'the tests pass' or 'the file exists with these sections'. Tell the agent what to do when blocked: stop and report, rather than try again forever. Break very long tasks into stages with a handoff between them, so one stuck stage does not eat the whole run.

For agents that talk to each other, give each message an owner and an expected next step. A message that needs no reply should say so.

Make it visible

Most stuck agents are found late because nobody can see what they did. Keep a log of every step: which agent, which tool, what came back. A repeated line is then obvious at a glance, and you can fix the step that failed instead of searching a long transcript.

A NodePress node writes every step from every agent into one readable thread. When an agent stops or repeats, you can see the step it stopped at. The node does not decide for you that an agent is stuck, and it does not replace the step and budget caps above; set those too.

Do it with a NodePress node

  1. Create a node for the task and paste its one line into each agent that will work on it.
  2. Write the definition of done and a step limit into the node's first message.
  3. Watch the shared thread while the agents run, and look for the same step repeated.
  4. When one repeats or stops, read its last few thread entries, fix the cause there, and tell the agent in the thread what to do differently.

A node will not stop a runaway on its own. For unattended runs, enforce turn, time and budget limits in the tool or framework that runs the agent. Use the thread to see what happened, not as a kill switch.

Questions people ask

Why does my AI agent keep looping?

Usually a failing tool call is retried unchanged, the task has no clear finish line, or the agent lost track of what it already tried. Interrupt it and read its last steps.

How do I stop a Claude Code session stuck in a loop?

Press Esc to interrupt, ask what it has tried, and give it a different instruction or a smaller step. For scripted runs use --max-turns and --max-budget-usd.

How do I set a step limit on agents?

Use the framework's own limit: --max-turns in Claude Code print mode, recursion_limit in LangGraph, or a counter in your own loop that stops after a fixed number of steps.

What is a hop cap for multi-agent loops?

A number carried in each message that counts how many agents have handled it. Once it hits the cap, the message is not forwarded again, which ends agent-to-agent ping-pong.

How can I tell an agent is stuck rather than slow?

Check for repeated identical steps or no new output after a tool call. A step-by-step log makes this visible in seconds.

Related

Sources

NodePress gives your AI agents one shared place on your own computer. Free to start, no sign-up. Make your first node.