An AI agent loop is a run where the agent keeps calling the same tool with the same arguments because the result never moves it forward: an empty or ambiguous result, an error it doesn't understand, or no clear stop condition. Detect it by counting identical (tool name, arguments) pairs per run; three or more is a strong signal. Prevent it with a per-run repeat guard, a hard step limit, and tool results that say plainly what happened and whether retrying can help.
Why agents loop
- The result doesn't change and doesn't explain. A status API returns
{"status": "pending"}; the model asks again, gets the same answer, asks again. - Errors look retryable. A tool returns "something went wrong" with no hint whether retrying makes sense.
- Empty results. A search returns nothing, and the model retries the same query instead of changing it or telling the user.
- No stop condition. The prompt says "keep going until you have the answer", and there is no limit in code.
- Lost context. Earlier tool results are trimmed from the context, so the model "forgets" it already made the call.
A logistics assistant answers "where is my parcel?" with a track_shipment tool. For one shipment the carrier API keeps returning {"status": "pending", "eta": null}. The agent calls track_shipment seven times with identical input, then hits the framework's step limit and replies "I'm still checking, please wait."
How to debug a loop
- Find runs with many steps. Sort runs by number of observations, latency or cost. Loops are expensive, so they stand out at the top of any of those lists.
- Look at the shape of the run. In a trace tree, a loop is the same tool name repeated down the page. Langfuse's agent graph view collapses repeated steps into one node with a count, which makes this obvious.
- Compare the arguments. Identical arguments mean the agent is stuck. Arguments that change each time (page 1, 2, 3) may be legitimate pagination.
- Read the tool output the agent kept getting. That output is usually the cause: here,
pendingwith no ETA and no instruction. - Read the generation right after. It shows the model's reasoning for calling the tool again. Often it is "the result is not available yet, let me check again".
- Check the cost. Every iteration re-sends the growing context, so later iterations cost more than early ones.
trace where-is-my-parcel latency 38.2s cost $0.31 GENERATION llm.chatTOOL track_shipment {"shipment_id": "SHP-9000"} -> {"status": "pending", "eta": null} GENERATION llm.chat "The status is pending. Let me check again."TOOL track_shipment {"shipment_id": "SHP-9000"} -> {"status": "pending", "eta": null} ... (5 more identical calls) GENERATION llm.chat "I'm still checking, please wait."
Detect loops in code
Count identical calls per run. Compare arguments in a canonical form (keys sorted), otherwise {"a":1,"b":2} and {"b":2,"a":1} look different.
import jsonfrom collections import CounterLOOP_REPEATS = 3def find_loops(tool_steps): calls = Counter((s["name"], json.dumps(s["input"], sort_keys=True, default=str)) for s in tool_steps) return [(name, n) for (name, _args), n in calls.items() if n >= LOOP_REPEATS]# find_loops(steps) -> [("track_shipment", 7)]
Prevent them
- Guard repeats in the tool layer. Before executing a call, check whether the same (tool, arguments) already ran in this run. On the second repeat, return the cached result with a note instead of calling again.
- Set a hard step limit in code. Most agent frameworks have a maximum iteration or recursion setting. Treat hitting it as a failure you log, not a normal ending.
- Make tool results decisive. Return
{"status": "pending", "retry": false, "message": "Carrier has no update yet; tell the user and offer a follow-up."}instead of a bare status. - Handle empty results explicitly. "No results for this query. Try a different query or tell the user." gives the model a way out.
- Keep earlier tool results in context, or summarize them, so the model can see it already asked.
def guarded(call_tool, max_repeats=2): seen = {} def run(name, args): k = (name, json.dumps(args, sort_keys=True, default=str)) seen[k] = seen.get(k, 0) + 1 if seen[k] > max_repeats: return {"error": "repeated_call", "retry": False, "message": f"{name} was already called with these arguments. Use the earlier result or ask the user."} return call_tool(name, args) return run
Common mistakes
- Relying only on the step limit. It stops the bill from growing, but the run still fails and nobody learns why.
- Comparing raw argument strings. Key order and whitespace differences hide real repeats.
- Only counting consecutive calls. Agents often alternate: search, think, search again with the same query.
- Retrying on empty results automatically. Retry logic for transient errors (429, 503) should not apply to "no results".
- Flagging pagination as a loop. Different arguments per call are usually fine; identical ones are not.
When Rootline helps
Rootline flags a run as an Agent loop when the same tool is called three or more times with identical input in that run, comparing inputs as JSON with sorted keys, whether or not the calls are consecutive. Loops get critical severity. The dashboard flags a runaway loop when a looping run also costs more than $0.10, and on the Team plan Rootline can email you about new loops. A loop issue exported as a regression test asserts that no tool is called three or more times with identical input when the recorded outputs are replayed.
Only tool steps are counted, and only exact repeats: a loop whose arguments change every time (a timestamp, a page number, a reworded query) is not flagged as a loop, though it may still show up as a timeout or high-cost run. A model that loops in its own reasoning without calling tools is not visible as a loop either.
Official documentation
- Langfuse agent graphs (repeated steps collapse into one node)langfuse.com
- Langfuse observation types: tool, agent, generationlangfuse.com
- OpenTelemetry semantic conventions for GenAI agent spansopentelemetry.io
- Python json.dumps (sort_keys)docs.python.org