The Agent Loop & Stopping

The loop is easy to write and easy to get catastrophically wrong. Two failure modes bracket every agent: it stops too early (returns a half-done answer) or it never stops (burns your budget in circles). Engineering the stopping rule is engineering the agent.

The model signals "I'm done" by returning a response with no tool calls — just text. That's your natural stopping condition. But relying on it alone is how agents run away, because a confused model will keep calling tools forever. So a real loop has three ways to stop, in priority order:

1. Natural stop — the model returned a final text answer (no tool_use). The good ending.
2. Step budget — a hard max_steps cap. The safety net that guarantees termination.
3. Stuck detection — the loop is making no progress (repeating actions). The early bail-out that saves budget.

The runaway loop, in numbers

Leave out the step cap and give an agent a task it can't complete — a tool that keeps erroring, or a goal with no solution — and it doesn't gracefully give up. It retries, rephrases, tries adjacent tools, and keeps going. An agent with no cap on an impossible task in one test ran 50+ steps before it was killed manually, at which point it had spent roughly $4 on a single request that should have failed in 3 steps for a fraction of a cent. Multiply by real traffic and a missing max_steps is a genuine outage-and-invoice event. Every production loop has a hard cap. No exceptions.

Stuck detection — cheaper than the cap

The step cap guarantees termination but is wasteful: you still pay for all N steps before it fires. Better to notice the agent is spinning and bail early. The simplest, most effective signal: the agent repeats an identical (tool, arguments) pair it already tried. If it just called get_weather("Paris") for the second time this task, it's looping. Detecting a repeated action and injecting a nudge ("You already tried that and got X; try a different approach or stop") recovers many stuck runs — and if the nudge doesn't help, you stop. In practice, repeat-action detection catches the majority of runaway trajectories before they hit the hard cap, cutting wasted spend on failing tasks substantially.

Design the final answer, not just the stop

When the loop ends, what do you return? On a natural stop, the model's text. But on a capped or stuck stop, returning the model's last confused message is a bad user experience. Give those endings a defined output: "I couldn't complete this — here's what I found and where I got stuck." An agent that fails honestly is far more useful than one that returns a confident guess after 8 flailing steps.

Starter code

# A stand-in "model" that stubbornly retries the same failing tool.
def fake_model(messages):
    # Always wants to call broken_tool with the same args => a loop.
    return {"tool":"broken_tool", "args":{"x":1}}

def broken_tool(args):
    return "ERROR: service unavailable"

def loop(max_steps=20, detect_stuck=False):
    messages, seen, steps = [], set(), 0
    for steps in range(1, max_steps+1):
        act = fake_model(messages)
        if act is None:
            return steps, "natural"
        key = (act["tool"], tuple(sorted(act["args"].items())))
        if detect_stuck and key in seen:
            # nudge once already given? here we just stop on 2nd repeat
            return steps, "stuck"
        seen.add(key)
        result = broken_tool(act["args"])
        messages.append(result)
    return steps, "capped"

# TODO: run loop() both ways and print steps + reason for each.

print(loop(max_steps=20, detect_stuck=False))   # (20, 'capped')
print(loop(max_steps=20, detect_stuck=True))    # (2,  'stuck')