DEV Community

Mukunda Rao Katta
Mukunda Rao Katta

Posted on

The Simplest Stop Condition: A Hard Cap on Agent Loop Iterations

#hermeschallenge #ai #python #agents

Before you need composable stop conditions, budget tracking, or progress detection — you need an iteration cap. Every production agent loop should have one.

agent-loop-bound is the simplest possible stop condition: a hard cap on how many times the loop runs, with a counter you can check anywhere.

The Shape of the Fix 

from agent_loop_bound import LoopBound, LoopBoundExceeded

bound = LoopBound(max_iterations=20)

while True:
    bound.tick()  # raises LoopBoundExceeded if exceeded

    response = call_llm(messages)

    if response.stop_reason == "end_turn":
        break

    messages.append(handle_tool_call(response))

print(f"Completed in {bound.count} iterations")
Enter fullscreen mode Exit fullscreen mode

tick() increments the counter and raises LoopBoundExceeded at the limit. bound.count tells you how many iterations ran.

What It Does NOT Do

agent-loop-bound does not track cost, tokens, or progress. It only counts iterations. For multi-dimensional stop conditions, use llm-stop-conditions.

It does not prevent inflight LLM calls from completing. If the call is in progress when LoopBoundExceeded is raised, the exception propagates normally after the call returns.

It does not have configurable behavior on exceed. It always raises. If you want to handle the exceed case differently (return partial results vs raise), catch LoopBoundExceeded and handle it yourself.

Inside the Library 

class LoopBound:
    def __init__(self, max_iterations: int):
        if max_iterations < 1:
            raise ValueError("max_iterations must be >= 1")
        self._max = max_iterations
        self._count = 0

    def tick(self) -> None:
        self._count += 1
        if self._count > self._max:
            raise LoopBoundExceeded(
                f"Loop exceeded {self._max} iterations"
                f" (ran {self._count})"
            )

    @property
    def count(self) -> int:
        return self._count

    @property
    def remaining(self) -> int:
        return max(0, self._max - self._count)

    def reset(self) -> None:
        self._count = 0
Enter fullscreen mode Exit fullscreen mode

Zero global state. Thread-safe for reads (no writes to shared state between tick() calls). Not thread-safe for concurrent tick() callers — create one LoopBound per agent instance, not per process.

The remaining property is useful for prompts that need to tell the model how many steps are left: "You have {bound.remaining} iterations remaining. Make them count."

When to Use It

Use it as the absolute minimum stop condition for any agent loop. Even if you plan to add llm-stop-conditions later, start with a LoopBound. It adds two lines and protects against the most common failure mode: infinite loops.

The rule of thumb: set the max to 3-5x the expected number of iterations for normal tasks. If your agent typically completes in 5-7 steps, set the bound to 20. This gives the model room to work while preventing runaway execution.

Use the remaining property for adaptive prompting. When the agent is running out of iterations, tell it:

bound = LoopBound(max_iterations=20)

while True:
    bound.tick()

    # Warn the model when iterations are low
    if bound.remaining <= 3:
        messages.append({
            "role": "user",
            "content": f"Note: You have {bound.remaining} turns remaining. "
                      f"Please wrap up and provide your final answer soon."
        })

    response = call_llm(messages)
    # ...
Enter fullscreen mode Exit fullscreen mode

Install 

pip install git+https://github.com/MukundaKatta/agent-loop-bound
Enter fullscreen mode Exit fullscreen mode 
from agent_loop_bound import LoopBound, LoopBoundExceeded

def run_agent(task: str, max_steps: int = 15) -> str:
    bound = LoopBound(max_iterations=max_steps)
    messages = [{"role": "user", "content": task}]

    try:
        while True:
            bound.tick()
            response = call_llm(messages)

            if response.stop_reason == "end_turn":
                return extract_text(response)

            messages.extend(handle_tool_calls(response))

    except LoopBoundExceeded:
        # Agent ran out of iterations
        logger.warning("loop_bound_exceeded", 
                      task=task[:50], 
                      iterations=bound.count)
        # Return best partial result or an error message
        return "Task exceeded step limit. Partial results: " + get_partial_result(messages)
Enter fullscreen mode Exit fullscreen mode

Sibling Libraries

Library What it solves
llm-stop-conditions Composable MaxIters + MaxUsd + MaxTokens + NoProgress
agent-deadline Wall-clock time deadline
llm-cost-cap Pre-flight per-call cost gate
token-budget-pool Shared budget across concurrent agents
llm-circuit-breaker-py Open circuit after repeated provider failures

agent-loop-bound is the simplest stop condition. llm-stop-conditions includes MaxIters and three others. If you need only an iteration cap, agent-loop-bound is lighter. If you need the full set, use llm-stop-conditions.

What's Next

Hierarchical bounds: bound.sub(max_iterations=5) creates a child bound for a nested loop. When the child exceeds its limit or the parent exceeds its limit, both raise. This handles the common pattern of outer loops with inner loops that each need their own caps.

Soft limits: LoopBound(max_iterations=20, warn_at=15) that logs a warning at 15 iterations without raising. You get the signal early without the hard stop.

Counter grouping: track multiple named counters in one object. bound.tick("outer_loop"), bound.tick("inner_search"), etc. Useful for agents with nested loops that have different semantics.

Built as part of the agent-stack family: composable Python primitives for production LLM agents.

Top comments (0)